[Doc-SIG] Version 0.3 of quickref
David Goodger
dgoodger@bigfoot.com
Mon, 13 Aug 2001 23:36:08 -0400
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