[Doc-SIG] some ideas for reStructuredText & document model

[David Goodger]

Looking at the recent HTML output, I've had some ideas regarding changes to
the reStructuredText syntax and the Docutils document model. Please comment
on any or all. Thanks.

- Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been
  discussed before?
  
  Rationale: The footnote is the only explicit markup construct that
  directly translates to a visible body element. I've always been a
  little bit uncomfortable with the ``.. `` marker for footnotes
  because of this (we once said that ``.. `` implied "hidden"; it
  would be nice if that were uniformly true). And the leading
  underscore syntax (dropped because ``.. _[1]`` was verbose) is a
  useful reminder that it's a kind of hyperlink target. Time for
  another break from StructuredText?
  
  Example, current syntax::

      .. [GVR2001] Python Documentation; van Rossum, Drake, et al.;
         http://www.python.org/doc/

  Proposed new syntax::
  
      _[GVR2001] Python Documentation; van Rossum, Drake, et al.;
      http://www.python.org/doc/

  Note that the body of the footnote need not be indented.

- Differentiate author-date "citations" (``[GVR2002]``) from numbered
  footnotes? Create a new set of DTD elements: "citation" and
  "citation_reference"?
  
  Citations could be treated differently from footnotes. Footnotes
  could be rendered something like this::
  
      | 1. This is a footnote. The brackets could be dropped
      | from the label, and a vertical bar could set them
      | off from the rest of the document in the HTML. If
      | converted to endnotes (by a directive/transform),
      | a horizontal half-line might be used instead.
      | Page-oriented output formats would retain the
      | horizontal line.
  
  And citations would look like this::
  
      [GVR2001] Python Documentation; van Rossum, Drake, et al.;
       http://www.python.org/doc/

- Render footnote references as superscripts without "[]"? (But only
  if we differentiate numerical footnotes from textual citations.)

- Make footnotes two-way, GNU-style? What if there are multiple
  references to a single footnote?

- Directive ideas: TOC (GNU-style two-way), endnotes *here*,
  citations *here*.
  
- Add a list of pending transforms to the document node, generated by
  directives? Or add an element, "pending" perhaps, which encapsulates
  the transform, the point at which to apply it, and any data
  required.

- Add a "sidebar" element to the DTD? Like a generic admonition or
  floating mini-section. Useful for TOC, system messages section,
  abstract, etc.

- Add character processing? For example:

  - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash)
  - convert quotes to curly quote entities
  - various forms of ":-)" to smily icons
  - others?
  
  How to represent entities in the text though? Unicode?

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