[PYTHON DOC-SIG] setext in doc strings
Robin Friedrich
friedric@rose.rsoc.rockwell.com
Tue, 23 Jul 1996 15:21:28 -0500
I've been working with Daniel Larsson on gendoc. Currently there is a
little setext parser built into gendoc which identifies text structure
and stores the components in a metadocument which can be rendered in a
number of output formats (notably HTML and MML). Since most folks are
not necessary familiar with setext markup I'd like to provide a brief
synopsis. If you use this stuff in your doc strings nice things will
happen to your autogenerated manuals.:-)
SETEXT 101
==========
Below is the setext definitions from the BSDI project. Note that not
all tags are supported (or needed) in python doc strings.
Valid Typotags Table
---------------------
____________________ ___________________ _______________ ____________ v14
current (online) use setext form acted upon or name of
of text emphasis of same displayed as the typotag ?
==================== =================== =============== ============ ===
Internet mail header From <source> Subject: shown subject-tt (a)
(start of a message) minimal mail header [Date: & From:]
-------------------- ------------------- --------------- ------------ ---
title (1 per text) "Title a title title-tt (b)
in distinct position =====" in chosen style
-------------------- ------------------- --------------- ------------ ---
heading (1+/ text) "Subhead a subhead subhead-tt (c)
in distinct position -------" in chosen style
-------------------- ------------------- --------------- ------------ ---
body text 66-char lines in- lines undented indent-tt (d)
[plain not-indented] dented by 2 space and unfolded
-------------------- ------------------- --------------- ------------ ---
1+ bold word(s) **[multi]word** 1+ bold word(s) bold-tt (e)
a single italic word ~word~ 1 italic word italic-tt (f)
1+ underlined words [_multi]_word_ underlined text underline-tt (g)
hypertextual 1+ word [multi_]word_ 1+ hot word(s) hot-tt (h)
>followed by text >[space][text] > [mono-spaced] include-tt (i)
bullet-text in pos1 *[space][text] [bullet] [text] bullet-tt (j)
`_quoted typotag!_` `_left alone!_` quote-tt (k)
-------------------- ------------------- --------------- ------------ ---
[hypertext link def] ^.. _word URL jump to address href-tt (l)
[hypertext note def] ^.. _word Note:("*") ("cause error") note-tt (m)
-------------------- ------------------- --------------- ------------ ---
end of first? setext $$ [last on a line] [parse another] twobuck-tt (n)
^..[space][not dot] [line hidden] suppress-tt (o)
logical end of text ^..[alone on a line] [taken note of] twodot-tt (p)
==================== =================== =============== ============ ===
Note: only one instance of the element (c) (or, in its absence, (b))
is absolutely _required_ for a text to be considered a valid setext.
All the elements but (c) are in effect optional, not necessary for
a setext to be declared as such. Element (a) deals with setexts
that arrive via email and end up being parsed (processed) as
unedited mailbox files; fully employed the (a), (b) and (c) make
it possible to distribute "multisetexts", i.e. setexts with one
additional level of logical structure (= more than one setext per
message; more than one message in a mailbox). If such file is
viewed as a multisetext it will result in 3-level-outline
structure: mail-subjects become top-level chapters, setext titles
denote subchapters (topics) and the subheads yet finer threads
within these (still a notch ABOVE mere "paragraphs of text").
$$
-----------------------------------------------------------------------
The following doc string example illustrates the usage of all setext
constructs recognized by the gendoc tool. (i think)
class Setext(Text):
"""Lets you change markup to stylize your text
SETEXT 102
==========
**Setext** can be used to mark your text in a non-obtrusive
manner. Text within double asterisks are treated as bold,
while single words with tilde at the front and back are
rendered as ~Italic~. You can _underline_a_phrase_ but it
will be rendered as bold in HTML. Placing hyperlinks
is easy; just hilite_the_tag_ and at the bottom of the doc
string include the address which it points to on a line by
itself.
New paragraphs are separated by blank lines.
> And a bunch of literal text
> can be specified with the left
> arrow. This gets marked as <pre> in HTML.
Otherwise the text will be wrapped according to whatever
output formatter is used.
A bulleted list is done with single asterisks thusly:
* Lettuce
* Onions
* Pickles
Extension to setext
-------------------
A frequent construct in python doc strings is to list ones
keyword arguments. This made us wish for a way to specify
a definition list so that it looks nice is html (and others).
I propose the following. I have this working in my version.
The double colons won't be in the output.
item1 :: definition 1
item2 :: definition 2
item3 :: a rather long and involved definition for item 3
spanning more than one line.
item4 :: back to brevity with definition 4
.. _hilite_the_tag http://www.python.org
"""
Notes:
The indenting inserted by python-mode for the entire doc string is
detected and processed out before setext rules are applied. So
eventhough titles for example are required to start in column one they
will if they obey the overall indenting for that doc string.
The underlines for the title and subtitle should be the same length as
the title itself.
Spaces around tokens are important (for the "* ", "> ", and " :: ")
Comment are hearby welcome.
-Robin Friedrich
=================
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================