[Doc-SIG] Version 0.3 of quickref

[David Goodger]

Tony J Ibbs (Tibs) <tony@lsl.co.uk> wrote on 2001-08-13 09:11:
> I've just uploaded version 0.3 of the "quick" reference:
> 
>      http://www.tibsnjoan.co.uk/reST/quick_reST.html
...
> Let's hope I'm getting the hang of this now, and thus have fewer
> bugs in the spec!

The spec is bigger so it's easier for bugs to crawl in. Let's squash
'em:

- "Inline markup", last row of the table. I'd change ``\* and \` but
  \\`` to something like ``\*escape* \`with` "\\"``, whose typical
  result would be ``*escape* `with` "\"`` (note: just one backslash
  after parsing). A lone "*" or "`" won't count as markup, so escaping
  isn't necessary. I'll add "escaped space may mean non-breaking space
  in the future" to the spec.

- "Implicit crossreferences": Perhaps "Implicit
  (crossreference|hyperlink) targets"? I'd add footnotes as well;
  footnote labels become implicit targets. Oh, this is what you have
  in "proposed footnote tricks", the first one. I'd either move it or
  mention it here.

- "Proposed footnote tricks":

  - First row. Footnote labels can't have any whitespace, so this
    won't work::

        Given a footnote [like this]_, one
        can also refer to it `like this`_.

    Should change to ``[like_this]_`` or something.

  - Second row. The formatting is funny on the plaintext side::

        They may be assigned 'counters', for
        instance, [#a], [#b]

  - Rather than 'counters', I'd call these 'reference labels' or
    something. The autonumbered footnotes would *not* contain the
    label (you should have [1] [2] [3] ... [6], not [a1] [b1] etc.).
    I'll write this into the spec.

  - You have the plaintext sentences broken in two, with footnotes
    in-between, but somehow the paragraphs get joined up under
    "Typical result". Magic?

    Note that auto-numbered footnotes & references won't have to be in
    lock-step, just in the same relative order::

        [#]_ is first, [#]_ is second.

        .. _[#] first
        .. _[#] second

- "Directives": There's not going to be a "comment" directive. Perhaps
  a section on comments? Include that an empty comment does *not*
  gobble up subsequent indented blocks. (I'll write this into the
  spec, so you may want to wait until that's done to see the model
  text.)

- "Field lists": The two authors would become a single paragraph::

      :Authors:
          Guido van Rossum
          Tim Peters

  Either add a comma after GvR, make them into a two-item bullet list,
  or put a blank line between for two paragraphs.

- There's a hyphen missing from the top border of the table.

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