[Doc-SIG] Comments on the reST specification

Tony J Ibbs (Tibs) tony@lsl.co.uk
Fri, 3 Aug 2001 11:01:42 +0100

reStructuredText comments

.. comment:: same conventions used as in the DPS commentary, and
   doubtless the same formatting mistakes (I really want that cheat
   sheet - I'll work on it another day).

((For some reason, attempting to print the project history file from PFE
on Windows NT caused PFE to fall over. Very odd.))

((NB: yummy treats can't be sent over the internet - one needs a snail
mail address.))

An introduction to reStructuredText version 1.12 of 2001/07/10

.. namespace:: intro is introduction.txt

intro:`An introduction to reStructuredText`_

    This is a good docuement - I like it.


    A tertiary useful goal, for many of us (well, for me at least) is
    just to have *some* form of structured text, to read *as such*, for
    use in docstrings, and for reading within docstrings. That is,
    specifically an enhanced plain text, a set of conventions
    universally recognised that allow more expressiveness for those of
    us lazy enough to want it with markup rather than literary skill.


    The list of numbered items is a good list of the design goals.

    I've got a note against the second paragraph of the "Author's note":

        "There will inevitably be people...
	...reasonable people."

    which says simply "Yes".


    Regarding the paragraph that starts "In March 2001 a flurry", I
    would point out that for *some* of us, the markup is still
    preeminent - but a framework approach actually *increases* the
    chance of the markup being accepted and becoming predominant,
    so we should be happy as well, in the end.

reStructuredText Markup Specification version 1.41 of 2001/07/20

..namespace:: spec is reStructuredText.txt

Hmm - to someone reading the raw text, it can be useful to know whether
a link is to a target in the document or outside it. Of course, this can
be done (and probably *should* be done, by a good author) by writing the
text correctly - e.g.::

     as discussed in section `Fred Bloggins`_.

spec:`Quick syntax overview`_

    In describing paragraphs, you use the term "flush left". To me this
    means "flush against the left margin". Either "left justified" or
    (as you use elsewhere) "left aligned" would be better.

    Tables are good - thanks.

    Comments - I'll come back to these later on.

spec:`Syntax details`_

    I'm afraid that diagram doesn't mean much to me - it's too complex
    for me to digest easily. Unfortunately, I haven't read the DTDs yet,
    either, so I'll have to trust you on the nesting issues...


    You don't mention what happens if there are multiple blank lines
    between paragraphs, etc. I assume that multiple successive blank
    lines are equivalent to a single blank line, except (of course)
    within literal blocks. The phrase "one or more" comes to mind...

    Pedant mode on indentation: you say it is "used to indicate, and
    only significant in indicating" and give a list of cases. It is, of
    course, retained (and thus in some important sense significant)
    inside literal blocks as well (and since its "absence" indicates the
    *end* of a literal block...).

    As to spaces versus tabs - this sounds like it will lead to all of
    the traditional discussions we get on the Python list about whether
    one can mix spaces/tabs, and whether a tab is *really* 8 or 4
    spaces, leading finally to space eating nanoviruses (ick). I'd
    suggest that this is dangerous territory, and that the behaviour
    of tabs should be carefully undefined.

spec:`Section structure`_

    You don't say which characters may be used as "underlines" for
    section titles. Can I really do::

        This is a title

    Further down you say "nor must any specific section title style be
    used". I think that "must" would be better as "need".

spec:`Bullet lists`_

    The first incorrectly formatted example is also indented incorrectly
    - make it say so!

spec:`Enumerated lists`_

    The syntax diagram is missing.

spec:`Field lists`_

    I want to discuss these elsewhere. I think life is getting too
    complex, and too far away from what I specifically want.


    In the example, in the cell that contains lines starting ``-``, does
    that content count as a list? If so, the cell boundaries (top and
    bottom) must be acting as the delimiting blank lines - say so.


    "an left square bracket" - should be "a".

    "case insensitive single words" is unclear to me - it gets explained
    later on, so maybe that explanation could be shifted or copied?

spec:`Hyperlink targets`_

    "whitespace neutral" doesn't mean anything to me.

    When you say they may contain whitespace, clarify if you include
    newlines (some people include this as whitespace, some not). Yes, I
    know the examples later on make it clear, but it would be nice to be
    clear up front in the text.

    Is it allowed to use *redundant* backquotes - for instance::

        .. _`a b`:
	.. _`ab`:

    (I assume so, but it's not obvious.)


    Arbitrary text after a ``.. `` is treated as a comment.

    I don't think this is right.

    Initially, I didn't see *any* point to having comments, but you'll
    see I've used them occasionally in these notes. But I think the
    way to introduce a comment is with a "proper" named directive::

        .. comment:: this is a comment, and
           it continues in the normal manner
	   for a directive.

    I believe strongly that a directive that does not start in a
    legitimate manner should be treated as a "warning" (type 1 error?)
    and that an output processor should (by default) not place its text
    into the output, although it should allow the option of presenting
    it in some delimited manner (perhaps in a different colour).

    Part of this is just that I think a comment (if used) should be
    explicitly identified as such, but mostly it's for compatibility
    with Stretch - i.e., I don't want to be able to write a comment
    of the form::

        .. <format> not defined, for some reason

    and later discover that directives have been extended to make this
    have behaviour I don't expect. As it is, with the proposed scheme
    in the document, I can't start comments with text that looks like
    a hyperlink target, etc., nor with a "word" followed by two colons.
    That's already too many caveats to remember for what can't be in a

    I think we get a more robust format if:

    1. Comments are a directive like any other::

          .. comment:: some text

       Heh - it even says what it is!

    2. Anything that is not a directive or a hyperlink target or a
       footnote (I forgot those above - sorry) is of undefined
       behaviour, and will generate a warning.

       This allows for extension in all sorts of ways in the future,
       with minimal restriction.

    Incidentally, this would also mean that directives can use a single
    colon as a delimiter - I think this would be easier to remember, but
    can't say I'm too fussed (presumably a decent parser will warn me
    every time I forget that second colon - slight sarcasm there, I'm

spec:`Inline markup`_

    Item 1 says that inline markup start strings must be immediately
    preceded by whitespace and zero or more of various characters. This
    precludes having a start string at the start of a file, and maybe
    even at the start of a paragraph (depending on how one views the
    whitespace (blank line) that indicates the start of the second and
    successive paragraphs).

    Item 5 mentions '<' and '>', but items 1 and 4 do not. I assume this

    is a mistake.

spec:`Interpreted text`_

    I'm not too keen on having the "role" inside the string (as you
    might guess from my attempt at "namespaces" in these notes). I
    assume that the compelling reason, for you, is a wish to allow
    whitespace in the role name (whereas I'd overgeneralise RFC 822,
    or perhaps XML names, or Python identifiers, or something).

    Personally, I think::

        role:`interpreted text`_


        `role: interpreted text`_

    because I think the former is easier for *me* to parse (e.g.,
    specifically as something like class:`Fred`_ - the quotes go around
    the *name* which feels right).

    Ultimately, of course, this comes down to an issue of taste (all
    parsing being equal), so I'm prepared to go down grumbling on this
    one if needs be (but you already know I can grumble for a long

    By the way, it is not acceptable to leave out a description of how
    to determine the difference between (for instance)::

        `role: Fred`_
	`role: Fred`_

    in some arbitrary application where the former is identifying a
    role, but the latter is identifying something *called*
    (legitimately) "role: Fred" - and whilst I can't come up with a
    concrete example now, this disturbs me greatly (and is perhaps the
    main reason I prefer to move the role name outwith the string).


    This made more sense when I realised you'd been doing a Grand
    Unification of setext and ST. But the "_" had to go at one end or
    the other, and designer gets to choose...

spec:`Standalone hyperlinks`_

    You need to explain the explicit rules used to detect such an
    animal, otherwise this is too vague.

Miscellaneous notes
I understand (now) that the two-dots-and-a-space-after-newline
convention is
taken from setext, but why does it need to be two dots *and a space* -
given it
must occur after a newline (and optional whitespace, of course), is
there a
compelling reason for the space, or is it just for compatibility? Would
it be
better without the space?

It is not clear to me whether the output formatter should:

a) "fold in" indirect hyperlinks, or
b) treat them just the same as internal crossreferences, or

Probably both behaviours should be choosable with a command line switch.

See http://www.tibsnjoan.co.uk/further2.html for an example of the
"folded in"
style, and http://www.tibsnjoan.co.uk/further3.html for the same text
external hyperlinks are *not* folded in. Clearly one is better for
viewing as HTML and the other for printing.

Python extensions version 1.19 of 2001/07/20

.. namespace:: py is pyextensions.txt

py:`Option lists`_

    I don't think these belong here.

    These are not *Python* options - these are Unix shell command
    options (with common GNU extensions). They can clearly be dealt with
    by other means, and should be so.

    Alternatively, try defining a new syntax for "tabbed tables"
    (something like the facilities available in LaTeX) - something
    that looks like::

        .. -a            :: Output all
	.. -b		 :: Output both (this description
	                    is quite long)

    might sort of work, if I could figure how to introduce it)

    But ultimately, this is really only doable in a neat manner
    with "proper" descriptive lists, like::

        -a    -- Output all
	-b    -- Output both

    and that's a discussion best held elsewhere. Anyway, they're still
    not part of a Python specific mode.

py:`Doctest blocks`_

    Good - this is necessary, and it is indeed Python specific.

py:`Interpreted text`_

    As said elsewhere, use of `..` (undecorated with "_") to indicate
    Python "elements" is a neat idea (if one doesn't want to use

    I agree that the use of roles to disambiguate this is helpful, *but*
    I've already said elsewhere my problems with the specific way of
    doing it.

    I can't help feeling we shouldn't need as *many* roles as you
    enumerate - how is a poor user to keep track, especially of the ones
    that aren't part of normal Python terminology (like "instance

    "Class attribute" (for instance) is too long, and "classatt" too
    horrible - if we're producing these, it means we need to think
    longer about how to specify Pythonic roles.

    What is a "warning" or "warning class"?

    The "argument" role is missing.

    Specific recommendation: use "name" instead of "variable" (what's
    the other recommendation that goes with that?).

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