[Doc-SIG] Suggestions for reST "modes"

[Tony J Ibbs (Tibs)]

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