[Doc-SIG] Documentation markup & processing / PEPs

[David Goodger]

on 2001-06-14 5:52 AM, Tony J Ibbs (Tibs) (tony@lsl.co.uk) 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
fact.

> 5. Did it mention whether line breaks were allowed in things? Should be
> no for literals, yes for other quoted thingies...

Inline literals:

"""
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
underline.
"""

> 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

It does:

"""
- 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
  choice.
"""

Thanks for your input. I'm looking forward to further input once you *have*
read the specs. :-)

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net