[Doc-SIG] Comments on the reST notes
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 3 Aug 2001 11:01:57 +0100
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.)