[Doc-SIG] Comments on the reST notes

[David Goodger]

on 2001-08-03 6:01 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote:
> reStructuredText notes version 1.29 of 2001/07/20
> =================================================
> 
> notes:`Enumerated lists`_
> 
>     I would say that worrying about "compound enumerators" is not worth
>     the mind space. Let someone provide a convincing demonstration of
>     why they want it before worrying about it.

That's why it's in the notes file. :-)

> notes:`Literal blocks`_
> 
>     I don't understand what you are wanting the triple-quotes convention
>     to do

Basically, to easily allow the construction of something like your
"Quick Reference". Write the construct once, see it twice: once raw,
once processed. But it's probably a lame idea. That's why it's in the
notes file too. :-)

I've added a header and intro explaining that these ideas are "of
questionable probability".

> notes:`Indentation of list items`_
> 
>     NB: I'm assuming that we do explicitly allow::
> 
>         9. This is some text
>            that lines up like this.
> 
>         10. And obviously this text
>             lines up one space further right.

I assume the indentation above was what you meant? That the "10" text lines
up one space further right because "10" is one character wider than "9"? But
the text lines of each element line up with each other? (Due to tabs & email
clients, I couldn't tell where everything was supposed to line up.)

If my assumption is correct, then yours is too.

> notes:`Horizontal rules`_
> 
>     The solution is to introduce them into a mode specifically for
>     producing HTML documents, and leave them out of other modes
>     (since other modes may also be used for producing other sorts of
>     output format).

reStructuredText is not a page layout language. I'm reluctant to add
these, at least for now.

> notes:`Parser notes`_
> 
>     Incorrect indentation should:
> 
>     a) generate a warning (level 1?)

I'm thinking that I'll leave it alone. There's nothing preventing a
block quote from containing another block quote. We shouldn't prevent
a block quote from beginning with a nested block quote either.

>     Note that use in "batch" environments (such as Wikis) will alway
>     require a reasonable best guess, since they produce the visible
>     documentation (HTML) from the internal format, and there is no
>     author to ask if that internal format is in error.

But surely the author gets a chance to correct their input? I'm going
to leave the "guessing" out for now; others can add it later if it
proves necessary. I want reStructuredText to be as deterministic as
possible all on its own.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net