[Doc-SIG] some ideas for reStructuredText & document model
Thu, 28 Feb 2002 00:07:00 -0500
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 ``.. `` to ``_``? Has this been
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 ``.. _`` 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.;
Proposed new syntax::
_[GVR2001] Python Documentation; van Rossum, Drake, et al.;
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
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.;
- 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*,
- 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
- Add a "sidebar" element to the DTD? Like a generic admonition or
floating mini-section. Useful for TOC, system messages section,
- 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
How to represent entities in the text though? Unicode?
David Goodger email@example.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