[Doc-SIG] Suggestions for reST "modes"
Tony J Ibbs (Tibs)
tony@lsl.co.uk
Fri, 3 Aug 2001 11:02:09 +0100
reStructuredText "modes"
========================
"raw" or "plain" mode
---------------------
This is the default - nothing special. It should actually be sufficient
for a good many documents.
Python docstrings
-----------------
Adds a way of indicating a Python value: ``self.thing()``, and
some form of disambiguating those if necessary.
Doctest blocks, as in pyextensions.txt.
I think that is *all* that is needed.
NB: in the Python source code, have a variable which defines what form
the following docstrings take::
__docformat__ = "raw"
"raw" is the default, "reST" is reStructuredText, "ST" is
StructuredText, etc.
((check all of this - I think I've got it vaguely wrong))
Email
-----
Adds RFC style headers, in a single block, at the start of the
text.
Recognises signature delimiter at the end, and treats that as if it were
typed::
-- ::
<signature text>
Recognises various common forms of quoting for blocks of text that are
being replied to (sorry, the proper term escapes me!). Steal ideas
vigorously from the relevant Emacs modes...
PEP
---
Has a header block similar to that of Email, but with limited keys
allowed (i.e., the ones allowed in PEPs). Otherwise, pretty plain reST.
A special output formatter is provided to produce "original" PEP format
from the reST PEP format (as well, of course, as direct output to HTML,
etc.)
Wiki
----
Allows any word of the form ``word_`` to be looked up in the document
itself, and if it is not found, looks it up as a Wiki link word.
Thus one can create a WikiLink_, or indeed a wikilink_. One does not
need the to !EscapeThings, because they're not links unless made so. One
also doesn't need [this] because one can do this_.
May want to provide lazy indentation::
Lists that format like this:
1. This is the first list item
and it can continue here.
2. But the second list item *must*
be separated from the first by a blank
line.
This won't be so onerous in a Wiki, I think, where the raw text is *not*
the primary means of reading it (heck, if people can put up with things
like """"""this means something""""" then they can cope with that
limitation!).
HTML/XHTML/etc.
---------------
May want to provide special support - for instance::
---------------------------------
(i.e., 3 or more hyphens) separated by blank lines before and after
means <hr>.
A directive to include a diagram, figure, etc. (follow the examples
given in
Book/paper/document
-------------------
Some more directives, such as::
.. newpage::
will be needed. I suspect that a means of marking Chapter, Appendix,
etc., explicitly may be needed - maybe by doing::
Chapter: This is a title
========================
This chapter is numbered implicitly.
Chapter 3: Another name
=======================
But this one *is* chapter 3. And both titles must
use the same "underline" because they both call
themselves chapters.
with some predefined hierarchy (as, for instance, provided by LaTeX).
(oh - and diagrams/figures as in HTML mode will be needed as well.)
--
Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)