[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.
intro:`Goals`_
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.
intro:`Goals`_
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".
intro:`History`_
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...
spec:`Whitespace`_
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::
aaaaaaaaaaaaaaa
This is a title
aaaaaaaaaaaaaaa
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.
spec:`Tables`_
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.
spec:`Footnotes`_
"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.)
spec:`Comments`_
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
"comment".
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
afraid).
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`_
to::
`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
time...).
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).
spec:`Hyperlinks`_
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
where
external hyperlinks are *not* folded in. Clearly one is better for
online
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
attribute").
"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.)