docutils-users — General discussions, questions, help requests.

[Docutils-users] Section titles, with or without multiple sections in document

[Ben F. <ben...@be...>]

Howdy all,

How can I disable the special-case treatment of a lone section title as
the document title?

The default reST parser treats a lone section title as a special case,
promoting it as the document title. What I want is to disable that
behaviour, and have the first section treated as a section regardless of
whether any sections follow it.

A document with two top-level sections is parsed as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document source="<stdin>">
    <section ids="first-section" names="first\ section">
        <title>
            First Section
        <paragraph>
            Lorem ipsum, dolor sit amet.
    <section ids="second-section" names="second\ section">
        <title>
            Second Section
        <paragraph>
            Praesent eleifend ligula eget luctus consectetur.
=====

But if the document has only one top-level section, the special case
applies and I don't get the sections as I want:

=====
$ cat foo.txt
First Section
=============

Lorem ipsum, dolor sit amet.

Second Section
==============

Praesent eleifend ligula eget luctus consectetur.

$ rst2pseudoxml < foo.txt
<document ids="first-section" names="first\ section" source="<stdin>" title="First Section">
    <title>
        First Section
    <paragraph>
        Lorem ipsum, dolor sit amet.
=====

What I want is:

=====
$ rst2pseudoxml < foo.txt
<document source="<stdin>">
    <section ids="first-section" names="first\ section">
        <title>
            First Section
        <paragraph>
            Lorem ipsum, dolor sit amet.
=====

In fact, I'm accessing this document programmatically using a custom
Writer. How can I get the parsing result I want?

-- 
 \         “A politician is an animal which can sit on a fence and yet |
  `\                  keep both ears to the ground.” —Henry L. Mencken |
_o__)                                                                  |
Ben Finney

Re: [Docutils-users] Good ReStructuredText editors

[Eric K. <eri...@gm...>]

Virgil Arrington <cuyfalls <at> hotmail.com> writes:

> I've read online about people writing whole books in ReStructuredText. 
> So, my question is, what editor are y'all using to get the job done?

For anyone on Mac OS X, I wrote a reST language module for BBEdit or 
TextWrangler. I wrote it to make editing this book <http://lassoguide.com>
much easier. Find it here: <http://ericfromcanada.bitbucket.org>
---
Eric3

Re: [Docutils-users] Git or Mercurial?

[Guenter M. <mi...@us...>]

On 2014-12-17, Marc Abramowitz wrote:

> [-- Type: text/plain, Encoding:  --]

> Has anyone suggested moving from Subversion to Git or Mercurial?

Many have, see the list archive.

> Most Python projects use one of those two and usually either GitHub or
> Bitbucket, because it makes collaboration a lot easier.

Collaboration is not the problem. It is a matter of familiarisation - the
current Docutils developers are more familiar with SVN. 
OTOH, I support a move to Git because setting up brances is a pain with SVN.

However, I don't think there is need to change the host, as Sourceforge
supports the "modern" vcs. (If we do not want to exclude possible
developers from Cuba, we should move to a non-US host, though.)

Günter

Re: [Docutils-users] ImportError: No module named admindocscorsheaders

[David G. <go...@py...>]

Sorry Nancy, I have no idea why you're having this problem. There is
no "admindocscorsheaders" module in Docutils, or anything like that.
The Django docs you referenced do have "admindocs" in the URL. I
suspect you may have a typo somewhere. Try searching for "admindocs"
in your files.

Perhaps the Django people can help more. Good luck!

David Goodger


On Tue, Dec 16, 2014 at 10:53 AM, Poekert Family <po...@ve...> wrote:
> I never used docutils before.  I followed the instructions to use it in the
> Django docs at
> https://docs.djangoproject.com/en/1.7/ref/contrib/admin/admindocs/
>
> When I run manage.py runserver, I get the error: "ImportError: No module
> named admindocscorsheaders"
>
> First I installed docutils with pip and I got the above error.  Then I
> installed it from the tarball and uninstalled the pip version.  I am still
> getting the error.
>
> I ran the alltests.py from the test directory and there were no errors.
>
> I am running on a MacBook Pro with Mavericks, Python 2.7, and Django 1.7.
>
> Any help on this will be appreciated.
>
> Regards,
>
> Nancy
>

Re: [Docutils-users] ImportError: No module named admindocscorsheaders

[David G. <go...@py...>]

On Wed, Dec 17, 2014 at 12:22 PM, engelbert gruber
<eng...@gm...> wrote:
> On 16 December 2014 at 17:53, Poekert Family <po...@ve...> wrote:
>> I never used docutils before.  I followed the instructions to use it in the
>> Django docs at
>> https://docs.djangoproject.com/en/1.7/ref/contrib/admin/admindocs/
>>
>> When I run manage.py runserver, I get the error: "ImportError: No module
>> named admindocscorsheaders"
>
> there is no refernce on manpage.py on that page , where did you get
> this commandline from
>
> my understanding is: django preprocesses reST documents and produces
> html by means of docutils
>
> and i would assume one queries django via http not n commandline
>
> manpage.py produces man pages that is manual pages for unix systems
> you are on a mac ... open a terminal type "man man<enter>"
>
> or am i totally misled

Engelbert, you're mistaken. It's "manage.py", not "manpage.py". IIRC,
"manage.py" is Django's way of starting up applications and services.

-- 
David Goodger <http://python.net/~goodger>

Re: [Docutils-users] ImportError: No module named admindocscorsheaders

[engelbert g. <eng...@gm...>]

On 16 December 2014 at 17:53, Poekert Family <po...@ve...> wrote:
> I never used docutils before.  I followed the instructions to use it in the
> Django docs at
> https://docs.djangoproject.com/en/1.7/ref/contrib/admin/admindocs/
>
> When I run manage.py runserver, I get the error: "ImportError: No module
> named admindocscorsheaders"

there is no refernce on manpage.py on that page , where did you get
this commandline from

my understanding is: django preprocesses reST documents and produces
html by means of docutils

and i would assume one queries django via http not n commandline

manpage.py produces man pages that is manual pages for unix systems
you are on a mac ... open a terminal type "man man<enter>"

or am i totally misled

Re: [Docutils-users] tox for testing multiple Python versions

[David G. <go...@py...>]

On Wed, Dec 17, 2014 at 5:27 AM, Ben Finney <ben...@be...> wrote:
> Marc Abramowitz <msa...@gm...> writes:
>
>> Any interest in using tox to test docutils on multiple Python
>> versions?
>
> That is less a topic for discussion here (the forum for Docutils
> end-users), and more a topic for discussion at ‘docutils-develop’ which
> is for Docutils developers.

+1

-- 
David Goodger <http://python.net/~goodger>

Re: [Docutils-users] Git or Mercurial?

[David G. <go...@py...>]

On Wed, Dec 17, 2014 at 12:52 AM, Marc Abramowitz <msa...@gm...> wrote:
> Has anyone suggested moving from Subversion to Git or Mercurial?
>
> Most Python projects use one of those two and usually either GitHub or
> Bitbucket, because it makes collaboration a lot easier.
>
> Has it come up before?

Many times; see the mailing list archives for this list and
Docutils-develop. I'm not averse to switching, it just has to be done
properly and completely with minimal perturbation. Mercurial is my
preference, because it's written and extensible in Python, and because
I find Git slightly harder to use (although much better than it used
to be).

Docutils pre-dates widespread DVCS use. Once you're set up and used to
SVN, the cost of switching outweighs the benefits, at least in the
short term. And I don't drink the "switch to Github and prepare for a
deluge of pull requests" koolaid.

-- 
David Goodger <http://python.net/~goodger>

Re: [Docutils-users] tox for testing multiple Python versions

[Ben F. <ben...@be...>]

Marc Abramowitz <msa...@gm...> writes:

> Any interest in using tox to test docutils on multiple Python
> versions?

That is less a topic for discussion here (the forum for Docutils
end-users), and more a topic for discussion at ‘docutils-develop’ which
is for Docutils developers.

-- 
 \     “When I was a kid I used to pray every night for a new bicycle. |
  `\    Then I realised that the Lord doesn't work that way so I stole |
_o__)                   one and asked Him to forgive me.” —Emo Philips |
Ben Finney

[Docutils-users] tox for testing multiple Python versions

[Marc A. <msa...@gm...>]

Any interest in using tox to test docutils on multiple Python versions?

https://github.com/msabramo/docutils/pull/2

Looks like this:

[marca@marca-mac2 docutils]$ tox
...
  py26: commands succeeded
  py27: commands succeeded
  py33: commands succeeded
  py34: commands succeeded
  congratulations :)


Marc

[Docutils-users] Git or Mercurial?

[Marc A. <msa...@gm...>]

Has anyone suggested moving from Subversion to Git or Mercurial?

Most Python projects use one of those two and usually either GitHub or
Bitbucket, because it makes collaboration a lot easier.

Has it come up before?

Marc

Re: [Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[Marc A. <msa...@gm...>]

> You're right, my apologies. I forgot to look there for aliases, and
> forgot that "code-block" is standard. Please ignore that part.

No problem. Thanks for confirming.

> It would have to be *really* specific. E.g., Docutils would have to
> check that it was called by distutils only.

OK, I updated the patch at https://sourceforge.net/p/docutils/bugs/270/ to
do this.

> Maybe somebody else can investigate. I don't have much time for
> Docutils these days.

Sure. Is there someone you might suggest? I thought perhaps Günter Milde
(cc'd), since he seems to have touched that file a lot.

Marc

On Tue, Dec 16, 2014 at 8:34 AM, David Goodger <go...@py...> wrote:
>
> [CC'ing to Docutils-users. Please "reply-all", not just to me.]
>
> On Tue, Dec 16, 2014 at 10:12 AM, Marc Abramowitz <msa...@gm...>
> wrote:
> > First off, thanks David, for taking the time to respond!
> >
> >> "code-block" is not a standard Docutils reST directive
> >
> > Apologies. I'm not too familiar with docutils proper so I may have
> confused
> > docutils with Sphinx. But does the following not mean that "code-block"
> is
> > an alias for "code"?
> >
> > *
> >
> https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/parsers/rst/languages/en.py
>
> You're right, my apologies. I forgot to look there for aliases, and
> forgot that "code-block" is standard. Please ignore that part.
>
> >> It makes assumptions that may not always be true
> >
> > Yeah, this is my first time touching docutils so I am not surprised. I'm
> > willing to work on it though. Do you think that if you were specific
> about
> > what those assumptions are that the patch could be made to be acceptable?
>
> It would have to be *really* specific. E.g., Docutils would have to
> check that it was called by distutils only.
>
> The problem in your patch is, you're introducing a dependency on the
> stock RST parser, and client code might be using an alternate parser
> (modified, or different) or none. I don't want to screw 3rd-party code
> that uses Docutils, just to fix Python's bug. This smells kludgey.
>
> I don't understand why the issue is happening. Maybe it is a Docutils
> bug, I don't know.
>
> > Or
> > is there nothing that can be done on the docutils side, because...
> >
> >> If the bug is in Python's distutils, that's where the fix should be
> >
> > Yes, I agree in principle and I mentioned in the sourceforge ticket that
> > this might be more of a distutils problem. The thing is that even if we
> > correct the problem in distutils (which I think is present at least as
> far
> > back as Python 2.7 and as recent as Python 3.4), it won't be available to
> > users until Python 3.5 is released and it will only be available to
> Python 3
> > users; Python 2 folks will be out of luck. So while I agree that fixing
> the
> > problem in distutils might be the more correct approach, I'm also
> thinking
> > about "practicality beats purity".
> >
> > That said, I did submit a patch to CPython at
> > http://bugs.python.org/issue23063 and I'll try to push that through, but
> > like I said, it will only be for Python 3.5 I think. Whereas if we can do
> > something in docutils, then folks can easily upgrade docutils and be
> able to
> > validate more of their RST documents.
>
> Maybe somebody else can investigate. I don't have much time for
> Docutils these days.
>
> David Goodger
>
>
>
> > On Tue, Dec 16, 2014 at 7:13 AM, David Goodger <go...@py...>
> wrote:
> >>
> >> On Mon, Dec 15, 2014 at 2:46 PM, Marc Abramowitz <msa...@gm...>
> >> wrote:
> >> > python setup.py check --restructuredtext --strict --metadata fails
> with:
> >> >
> >> > warning: check: Could not finish the parsing.
> >> >
> >> > if the RST document uses code or code-block directives.
> >> >
> >> > This is annoying because the document is valid, but it appears to be
> >> > invalid
> >> > and confuses people.
> >> >
> >> > I filed a ticket for this (with a patch included):
> >> >
> >> > https://sourceforge.net/p/docutils/bugs/270/
> >>
> >> "code-block" is not a standard Docutils reST directive, so I don't see
> >> how the document could be valid. "code-block" should always break.
> >> Maybe it's a Sphinx extension, and your environment has that
> >> installed. Did you try with just the "code" directive?
> >>
> >> -1 on the patch. It makes assumptions that may not always be true. If
> >> the bug is in Python's distutils, that's where the fix should be. But
> >> first, make sure your document is truly valid.
> >>
> >> --
> >> David Goodger <http://python.net/~goodger>
>

Re: [Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[Marcelo H. <mar...@gm...>]

El 16/12/2014 a las 01:34 p.m., David Goodger escibió:
> I don't have much time for
> Docutils these days.

Not to be an alarmist or anything, but should we be worried about Docutils'
future, given this?

-- 
   o-=< Marcelo >=-o

[Docutils-users] ImportError: No module named admindocscorsheaders

[Poekert F. <po...@ve...>]

I never used docutils before.  I followed the instructions to use it in the
Django docs at
https://docs.djangoproject.com/en/1.7/ref/contrib/admin/admindocs/

When I run manage.py runserver, I get the error: "ImportError: No module
named admindocscorsheaders"

First I installed docutils with pip and I got the above error.  Then I
installed it from the tarball and uninstalled the pip version.  I am still
getting the error.

I ran the alltests.py from the test directory and there were no errors.

I am running on a MacBook Pro with Mavericks, Python 2.7, and Django 1.7.

Any help on this will be appreciated.

Regards,

Nancy

Re: [Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[David G. <go...@py...>]

[CC'ing to Docutils-users. Please "reply-all", not just to me.]

On Tue, Dec 16, 2014 at 10:12 AM, Marc Abramowitz <msa...@gm...> wrote:
> First off, thanks David, for taking the time to respond!
>
>> "code-block" is not a standard Docutils reST directive
>
> Apologies. I'm not too familiar with docutils proper so I may have confused
> docutils with Sphinx. But does the following not mean that "code-block" is
> an alias for "code"?
>
> *
> https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/parsers/rst/languages/en.py

You're right, my apologies. I forgot to look there for aliases, and
forgot that "code-block" is standard. Please ignore that part.

>> It makes assumptions that may not always be true
>
> Yeah, this is my first time touching docutils so I am not surprised. I'm
> willing to work on it though. Do you think that if you were specific about
> what those assumptions are that the patch could be made to be acceptable?

It would have to be *really* specific. E.g., Docutils would have to
check that it was called by distutils only.

The problem in your patch is, you're introducing a dependency on the
stock RST parser, and client code might be using an alternate parser
(modified, or different) or none. I don't want to screw 3rd-party code
that uses Docutils, just to fix Python's bug. This smells kludgey.

I don't understand why the issue is happening. Maybe it is a Docutils
bug, I don't know.

> Or
> is there nothing that can be done on the docutils side, because...
>
>> If the bug is in Python's distutils, that's where the fix should be
>
> Yes, I agree in principle and I mentioned in the sourceforge ticket that
> this might be more of a distutils problem. The thing is that even if we
> correct the problem in distutils (which I think is present at least as far
> back as Python 2.7 and as recent as Python 3.4), it won't be available to
> users until Python 3.5 is released and it will only be available to Python 3
> users; Python 2 folks will be out of luck. So while I agree that fixing the
> problem in distutils might be the more correct approach, I'm also thinking
> about "practicality beats purity".
>
> That said, I did submit a patch to CPython at
> http://bugs.python.org/issue23063 and I'll try to push that through, but
> like I said, it will only be for Python 3.5 I think. Whereas if we can do
> something in docutils, then folks can easily upgrade docutils and be able to
> validate more of their RST documents.

Maybe somebody else can investigate. I don't have much time for
Docutils these days.

David Goodger



> On Tue, Dec 16, 2014 at 7:13 AM, David Goodger <go...@py...> wrote:
>>
>> On Mon, Dec 15, 2014 at 2:46 PM, Marc Abramowitz <msa...@gm...>
>> wrote:
>> > python setup.py check --restructuredtext --strict --metadata fails with:
>> >
>> > warning: check: Could not finish the parsing.
>> >
>> > if the RST document uses code or code-block directives.
>> >
>> > This is annoying because the document is valid, but it appears to be
>> > invalid
>> > and confuses people.
>> >
>> > I filed a ticket for this (with a patch included):
>> >
>> > https://sourceforge.net/p/docutils/bugs/270/
>>
>> "code-block" is not a standard Docutils reST directive, so I don't see
>> how the document could be valid. "code-block" should always break.
>> Maybe it's a Sphinx extension, and your environment has that
>> installed. Did you try with just the "code" directive?
>>
>> -1 on the patch. It makes assumptions that may not always be true. If
>> the bug is in Python's distutils, that's where the fix should be. But
>> first, make sure your document is truly valid.
>>
>> --
>> David Goodger <http://python.net/~goodger>

Re: [Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[David G. <go...@py...>]

On Mon, Dec 15, 2014 at 2:46 PM, Marc Abramowitz <msa...@gm...> wrote:
> python setup.py check --restructuredtext --strict --metadata fails with:
>
> warning: check: Could not finish the parsing.
>
> if the RST document uses code or code-block directives.
>
> This is annoying because the document is valid, but it appears to be invalid
> and confuses people.
>
> I filed a ticket for this (with a patch included):
>
> https://sourceforge.net/p/docutils/bugs/270/

"code-block" is not a standard Docutils reST directive, so I don't see
how the document could be valid. "code-block" should always break.
Maybe it's a Sphinx extension, and your environment has that
installed. Did you try with just the "code" directive?

-1 on the patch. It makes assumptions that may not always be true. If
the bug is in Python's distutils, that's where the fix should be. But
first, make sure your document is truly valid.

-- 
David Goodger <http://python.net/~goodger>

[Docutils-users] python setup.py check --restructuredtext --strict --metadata fails for valid document with syntax highlighting

[Marc A. <msa...@gm...>]

python setup.py check --restructuredtext --strict --metadata fails with:

warning: check: Could not finish the parsing.

if the RST document uses code or code-block directives.

This is annoying because the document is valid, but it appears to be invalid
and confuses people.
I filed a ticket for this (with a patch included):

https://sourceforge.net/p/docutils/bugs/270/

Marc

Re: [Docutils-users] footnotes

[Virgil A. <cuy...@ho...>]

On 12/15/2014 11:27 AM, David Goodger wrote:
> There is currently no functionality to do automatic rearranging in the 
> HTML writer (there may be in other writers). I intended to write a 
> "footnotes" directive that would "move all footnotes in the document 
> to this point", but never got around to it. It wouldn't be that 
> difficult to write; contributions are welcome. If you have a lot of 
> footnotes, I offer this workaround. Keep your footnotes in a separate 
> file, say "footnotes.txt". At the point in your document where you 
> want the footnotes to appear, use ".. include: footnotes.txt". That's 
> the best I can think of, right now. 

Thank you for the quick response.

Virgil

Re: [Docutils-users] footnotes

[David G. <go...@py...>]

On Mon, Dec 15, 2014 at 9:46 AM, Virgil Arrington <cuy...@ho...> wrote:
> In the Docutils Quick Reference Guide, I find the following with respect to
> footnotes.
>
>
> Footnote references, like [5]_.
> Note that footnotes may get
> rearranged, e.g., to the bottom of
> the "page".
>
> .. [5] A numerical footnote. Note
>    there's no colon after the ``]``.
>
>
> Does anyone know what determines where footnotes appear in the resulting
> HTML file? I'm finding that, if I insert a footnote as shown in the example,
> the footnote will appear in the resulting document right below the paragraph
> containing the footnote reference. I prefer footnotes at the end of the HTML
> document. To obtain this, I put the actual footnote text at the end of the
> source code document. But, on a long document with more than a few
> footnotes, I can lose track of my footnotes. If I want to move footnotes
> around, finding the footnote text that links with the footnote reference can
> be a challenge.
>
> With MarkDown Extra, footnotes always appear at the end of the document even
> if I put them right after the reference paragraph in the source document.
>
> So, what determines whether a footnote gets "rearranged, e.g., to the bottom
> of the 'page'"?

There is currently no functionality to do automatic rearranging in the
HTML writer (there may be in other writers). I intended to write a
"footnotes" directive that would "move all footnotes in the document
to this point", but never got around to it. It wouldn't be that
difficult to write; contributions are welcome.

If you have a lot of footnotes, I offer this workaround. Keep your
footnotes in a separate file, say "footnotes.txt". At the point in
your document where you want the footnotes to appear, use ".. include:
footnotes.txt". That's the best I can think of, right now.

-- 
David Goodger <http://python.net/~goodger>


> For my browser, I'm using Mozilla Firefox on Ubuntu Linux.
>
> Virgil

[Docutils-users] footnotes

[Virgil A. <cuy...@ho...>]

In the Docutils Quick Reference Guide, I find the following with respect 
to footnotes.


Footnote references, like [5]_.
Note that footnotes may get
rearranged, e.g., to the bottom of
the "page".

.. [5] A numerical footnote. Note
    there's no colon after the ``]``.


Does anyone know what determines where footnotes appear in the resulting 
HTML file? I'm finding that, if I insert a footnote as shown in the 
example, the footnote will appear in the resulting document right below 
the paragraph containing the footnote reference. I prefer footnotes at 
the end of the HTML document. To obtain this, I put the actual footnote 
text at the end of the source code document. But, on a long document 
with more than a few footnotes, I can lose track of my footnotes. If I 
want to move footnotes around, finding the footnote text that links with 
the footnote reference can be a challenge.

With MarkDown Extra, footnotes always appear at the end of the document 
even if I put them right after the reference paragraph in the source 
document.

So, what determines whether a footnote gets "rearranged, e.g., to the 
bottom of the 'page'"?

For my browser, I'm using Mozilla Firefox on Ubuntu Linux.

Virgil

Re: [Docutils-users] Good ReStructuredText editors

[Mantas <si...@gm...>]

I find Voom [1] (vim plugin) very useful for editing rst files with
many sections.

[1] http://vim-voom.github.io/

2014-12-15 9:54 GMT+02:00 Guenter Milde <mi...@us...>:
> On 2014-12-11, Virgil Arrington wrote:
> ...
>> I've read online about people writing whole books in ReStructuredText.
>> So, my question is, what editor are y'all using to get the job done?
> ...
>
> The `Docutils link list`__ has a section on editors.
> (Most entries were already mentioned, except for JED, one more free
> extensible text editor with rst support.)
>
> Günter
>
> __ http://docutils.sourceforge.net/docs/user/links.html#editors
>
>
> ------------------------------------------------------------------------------
> Download BIRT iHub F-Type - The Free Enterprise-Grade BIRT Server
> from Actuate! Instantly Supercharge Your Business Reports and Dashboards
> with Interactivity, Sharing, Native Excel Exports, App Integration & more
> Get technology previously reserved for billion-dollar corporations, FREE
> http://pubads.g.doubleclick.net/gampad/clk?id=164703151&iu=/4140/ostg.clktrk
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.



-- 
                 Mantas aka sirex
      __o                                   /\
    _ \<,_   -- launchpad.net/~sirex --  /\/  \
___(_)/_(_)_____________________________/_/    \
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Re: [Docutils-users] Good ReStructuredText editors

[Guenter M. <mi...@us...>]

On 2014-12-11, Virgil Arrington wrote:
...
> I've read online about people writing whole books in ReStructuredText. 
> So, my question is, what editor are y'all using to get the job done?
...

The `Docutils link list`__ has a section on editors.
(Most entries were already mentioned, except for JED, one more free
extensible text editor with rst support.)

Günter

__ http://docutils.sourceforge.net/docs/user/links.html#editors

Re: [Docutils-users] Good ReStructuredText editors

[Bernhard G. <ber...@gm...>]

Hi,

* Virgil Arrington <cuy...@ho...> [12.12.2014 22:39]:
> I've downloaded both VIM and Emacs, and I must say they both look 
> impressive in their respective feature sets, and their users seem 
> fiercely loyal. But, in both cases, as soon as I try to start using 
> them, the learning curve hits me in the face. They are sooooo different 
> from anything else I've ever used. I'd really like to learn them (or one 
> of them), but right now, it's a little like tackling Greek.

One of the most important Vim-Plugins for writing Restructured Text may be
snipMate:

http://www.vim.org/scripts/script.php?script_id=2540

With this plugin, you can define your own keyboard shortcuts in a way like this:

--------------------

snippet abbrev
	template

Example:

snippet toc

	.. toctree::
		:maxdepth: 2

		${1}

--------------------

In the example above, when you write "toc" and hit the tab-key (or whatever key
you choose as a trigger), the plugin replaces your input with the given template
and puts your cursor at the position ${1}. In this way, you can even have
LaTeX-Code-Completion within Restructured-Text-Files.

I don't know if Emacs also comes with such a feature.

Greetings,

Bernhard


P.S.: You can call "vimtutor" in a shell to learn the very basics of Vim.

P.P.S.: If you also have Vim-LaTeX-Suite installed, you can use <++> as further
jumping points inside of your templates. With a line like 

imap <c-l> <PLUG>IMAP_JumpForward

in your Vim configuration file, you can jump to the next <++> mark by typing
``Ctrl l`` in insert mode. I use this quite often..

Re: [Docutils-users] Good ReStructuredText editors

[Aahz <aa...@py...>]

On Sun, Dec 14, 2014, Ben Finney wrote:
> Aahz <aa...@py...> writes:
>> 
>> That last bit is exactly why I stick with vim -- my pinky hurts when I
>> use Emacs, and I'm still very much a command-line fanatic (I run Vim
>> in a terminal window).
> 
> I can't imagine asking anyone to make heavy use of either of Vim nor
> Emacs, without mapping the key directly next to the pinky finger's home
> position -- usually labelled "Caps Lock" -- as a "Ctrl" key.

Been doing that for a couple of decades, ever since keyboards stopped
putting the CTRL key where God intended it.

> If you're wanting to make heavy keyboard use of any Unix-style program,
> you'll be pressing "Ctrl" quite a lot. Your pinky finger will thank you
> for mapping that key to a more easily-accessible position.

Duh.

> I don't see that using Vim makes that any less true than for Emacs; they
> both require use of a lot of key chords with the "Ctrl" key.

vim requires fewer for editing and navigation.  That's the joy of command
mode versus insert mode.  Keep in mind that I initially made the decision
of vi versus emacs on an honest-to-goodness terminal (can't remember
whether it was actually a VT100 or something else), and another stellar
advantage of vi was that it consumed far fewer resources.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Member of the Groucho Marx Fan Club  

Re: [Docutils-users] Good ReStructuredText editors

[Virgil A. <cuy...@ho...>]

On 12/14/2014 08:18 AM, Peter Funk wrote:
> Did you know that both VIM and Emacs today also come with
> a decent graphical user interface which can help you a lot as
> training wheels on your first steps?
Yes, both versions of VIM and Emacs that I have downloaded have that 
feature and it is helpful.
> Since you mentioned gedit I assume you are using some flavor of Linux.
> Back to your original question: The Tools menu of gvim contains
> a sub menu called: "Folding" which allows to collapse and expand
> chapters, sections and subsections of large documents at will.

Yes, that's what I'm looking for. I've read about "folding" but never 
understood the term. I've only seen it used in the VIM or Emacs world.

> I'm pretty sure that the other text editors (Emacs, Leo) will provide
> similar features.

I've been impressed with Geany. It has a separate panel showing section 
headings. I also like the way you can create your own build commands for 
different systems, such as LaTeX, MarkDown and ReStructuredText. I 
imagine VIM and Emacs can do the same thing, but it'll be a while before 
I can figure it out.

One thing I've noticed is that there are many different uses for these 
programs. I'm sure many of you are programmers or web developers who 
need the features in programs like VIM and Emacs. I just like writing 
prose mostly for fun, or for various academic endeavors. In the past, my 
writing was mainly printed out on paper. Now, more often than not, I'll 
format it to my Kindle and never print out a hard copy. This is where I 
like ReStructuredText.

Thanks to all for your suggestions. It's nice to know that there are 
powerful options out there.

Virgil