[Doc-SIG] Documentation markup & processing / PEPs
Fri, 15 Jun 2001 00:22:52 -0400
on 2001-06-14 5:52 AM, Tony J Ibbs (Tibs) (email@example.com) wrote:
> I said I'd get round to commenting on David's documents (now formal
> PEPs - yeh!), and I still haven't had the time to read them thoroughly,
> let alone formulate proper comments.
Yes, please do. Repetition may be useful though, so:
> 2. Somewhere, I didn't notice it in my quick scan, it would be good to
> emphasise that the *primary* aim of this project is doc strings, which
> are *not* (meant to be) incredibly long. This means that constructs that
> only work well in long documents are not as important (they are a *nice
> thing*, but not the main reason for existence).
Which document are you referring to? I believe the PEPs do emphasize
docstrings; I'll make sure to emphasize the emphasis ;-). reStructuredText
is neutral on that point: applicable to docs of any length (just use what
you need). I'm trying hard to keep the issues separate so they don't get
bogged down. reStructuredText deals with markup syntax *only*, not usage.
> 3. I believe (as discussed earlier) that we could drop **strong**
> emphasis - I think one form of emphasis is enough for almost all
> purposes, especially if there are problems nesting the two forms (which
> I know Edward Loper has worried about in the past).
I don't think nesting of inline markup is useful enough to complicate
matters. And I do think both *emph* & **strong** are useful.
> 4. There is a good description of how literal quoting works (i.e., what
> characters may be adjacent to the quotes). I think this argument should
> be extended to apply (suitably amended) to other forms of quoting as
> well - I assume in David's mind it does already, but in the document I
> browsed it wasn't explicit.
You're referring to the beginning of the "Inline Markup" section, which
lists 7 "inline markup start-string and end-string recognition rules"? It's
applicable to all forms of inline markup. The examples listed use '*' in
> 5. Did it mention whether line breaks were allowed in things? Should be
> no for literals, yes for other quoted thingies...
Line breaks are *not*
preserved; other whitespace is not guaranteed to be preserved.
If you want linebreaks & whitespace preserved, use literal blocks instead.
I'll add that to the spec.
> 7. I *hate* the titles with "underlining" above as well as below - yuck.
So don't use them? ;->
The most obvious underlines are '=' and '-'. I came up with 'overlines' to
expand their use, before being forced to use other underline characters.
> 8. What are the rules for how *many* "underlines" must be present for a
> title - the same number as the title, end at the same column as the end
> of the title, at least one...
An underline/overline is a line of
non-alphanumeric characters that begins in column 1 and extends at
least as far as the right edge of the title text. When there an
overline is used, the length and character used must match the
> 9. DOM - my experience is that trying to use a DOM tree to do the work
> in leads to madness (I'll elucidate if anyone cares, but basically it's
> clearly too constraining).
Please do elucidate. I haven't gotten to the point of actually *using* the
DOM yet, so I'm open to alternatives. Using DOM's not written in stone, but
the DOM software does exist and seems to fit the bill.
> However, I still reckon that producing a DOM
> tree as final *output* is very useful.
PEP 258 specifies DOM for the output of the docstring parser and input of
the formatter. Does that (the former) qualify as "final output"?
> 10. Oh - terminology on ".." - don't refer to them as "comments", since
> "executable/meaningful comments" is an abomination. Refer to them as
> (for instance) directive delimiters,
How about 'processing instructions'? (He said, half seriously.)
> and note that an implementation may ignore undefined directives
- If an implementation of reStructuredText does not recognize a
directive (i.e., the directive-handler is not installed), the entire
directive block (including the directive itself) will be treated as
a literal block, and a warning generated. Thus '::' is a natural
Thanks for your input. I'm looking forward to further input once you *have*
read the specs. :-)
David Goodger firstname.lastname@example.org Open-source projects:
- Python Docstring Processing System: http://docstring.sf.net
- reStructuredText: http://structuredtext.sf.net
- The Go Tools Project: http://gotools.sf.net