[Doc-SIG] Slightly newer version of quickref

[David Goodger]

Tony J Ibbs (Tibs) (tony@lsl.co.uk) wrote on 2001-08-08 4:05 AM:
> I *did* have time to make the next iteration of the quick
> reference...
> 
>     http://www.tibsnjoan.co.uk/reST/quick_reST.html

Although it's a great resource, I think it has grown too large to be usable
as a quick reference. Perhaps a quickref page (like the first version, just
the yellow bits) with links to a separate details page (full explanations)?

How about adding links to the project home page? Better yet, how about
adding the quickref *to* the project? Please let me know your
SourceForge ID (get a free account if you don't already have one), and
I'll add you as a developer. We can put the quickref into the project
docs.

Once the parser is done, we can *do* the quickref with
reStructuredText.

Bugs:

- "Inline Markup", third paragraph of blue section::

      Markup characters can be escaped with backslash ("\\") - for
      instance, "\*" - or by enclosing them in

  1. We don't need a double-backslash here. A Python habit?

  2. "*" (inside quotes) need not be escaped. Rephrase as,
     "- as \*in this example* -".

- "Inline Markup", end of blue section::

      For instance, consider ``this   example,   which
        has   lots   of   spaces``.

  That won't work. The second line is indented relative to the first,
  and will currently be recognized as a definition list. The unclosed
  backquotes will generate a warning (level 1).

  The sentence ending the preceding paragraph doesn't make sense in
  this context: "Spaces at the *start* of a line are counted relative
  to the left margin of the current paragraph." Perhaps the same bug.

- "Inline Markup", yellow block following "The correct form for inline
  markup is:". There are omissions and small errors here. Why not just
  copy the text from the spec verbatim? Into the "Details" page
  though, please.

- "Links". This is still wrong::

       Internal crossreferences, like example_.

       .. _example: This is an example
          crossreference target.

  The target should be::

       .. _example:

       This is an example cross reference target.

- "Definition lists". Still waiting for an answer on:

      The spec (and the parser) require blank lines between definition
      list items. This requirement could be relaxed, as it has been
      for other lists. What do you think?

  Your example has no blank line between definition list items.

-- 
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