[Doc-SIG] Comments on the reST notes

[Tony J Ibbs (Tibs)]

reStructuredText notes version 1.29 of 2001/07/20
=================================================

.. namespace:: notes is rst-notes.txt

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.

notes:`Literal blocks`_

    I don't understand what you are wanting the triple-quotes convention
    to do - I'm presumably being dumb but the explanation doesn't convey
    anything to me, nor does it explain why you want to do this.

notes:`Indentation of list items`_

    .. comment:: NB: not needing to match case in links is *really*
       a good idea!

    I think that sloppy indentation should only be tried out when needed
    (which it sounds like the Wiki folk might want) because of the
    ramifications you've already discussed elsewhere.

    (Basically, in the "normal" context, I agree with you that
    "non-strict indentation isn't such a good idea - and for interests
    sake, I'm managing OK in XEmacs to type all of this without much
    support for indentation, even though I'm making heavy use of
    descriptive lists.)

    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.

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).

notes:`Parser notes`_

    Incorrect indentation should:

    a) generate a warning (level 1?)
    b) produce a *predictable* (i.e., defined in the documentation)
       result as a best guess - cf. what I tried to do in docutils,
       where it makes a consistent best guess based on the preceding
       indentation levels. Edward Loper may well have useful input
       on this as well.
    c) optionally highlight the offending text in some manner, so it
       is obvious that the indentation is dodgy and should not be
       trusted (this will help a user trying to interpret output data
       produced by a careless author who didn't remove warnings!).

    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.

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)