[PYTHON DOC-SIG] setext in doc strings
Robin Friedrich
friedric@rose.rsoc.rockwell.com
Mon, 5 Aug 1996 16:42:04 -0500
|> From: Jim Fulton <jim.fulton@digicool.com>
|>
|> Robin Friedrich wrote:
|> >
<snip>
|> I spent some time looking at setext after the workshop and was fairly
|> underwhelmed. Actually setext document I looked at were sort of ugly
|> in their basic form and example setext converted to html was often
|> broken.
|> I also has a tough time making out the setext documentation, which
|> colored
|> my opinion somewhat.
|>
|> In a separate note, I released a Structured text module that I consider
|> to be superior to setext in several ways:
Bummer. I didn't get it. Can you send it again? Be sure it's not >40K if
you send it to a sig list - it won't get forwarded.
|>
|> - The sourse text os more readable,
Really?:-)
|> - It supports arbitrary levels of nesting, including numbered,
|> bulleted
|> and descriptive lists.
Nice.
|> - It generates HTML tags like <strong> and <em>, rather than <bold>
|> and
|> <i>.
Actually, so doesn't gendoc.
<setext-deleted>
|> > Internet mail header From <source> Subject: shown subject-tt (a)
|> > (start of a message) minimal mail header [Date: & From:]
|>
|> I assume this doesn't apply to us?
Yes.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > title (1 per text) "Title a title title-tt (b)
|> > in distinct position =====" in chosen style
|>
|> Is gendoc using this? This mechanism of setext is rather restrictive
|> and ugly.
Yes, I thought so too but not badly so.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > heading (1+/ text) "Subhead a subhead subhead-tt (c)
|> > in distinct position -------" in chosen style
|>
|> Ditto.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > body text 66-char lines in- lines undented indent-tt (d)
|> > [plain not-indented] dented by 2 space and unfolded
|>
|> Ditto.
Don't think this one is applied.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > 1+ bold word(s) **[multi]word** 1+ bold word(s) bold-tt (e)
|>
|> *mult word* would be more readable and follows standard conventions. I
|> think
|> emphasis is better than bold. This is what I did in StructuredText.
The reason I guess was that * was used to indicate a bulleted list.
|>
|> > a single italic word ~word~ 1 italic word italic-tt (f)
|>
|> This looks ugly. Why specify italic directly? Doesn't this run counter
|> to HTML
|> philosophy.
HTML philosopy had nothing to do with setext as far as I can tell.
|>
|> If the group wants this, I'd be willing to add it to StructuredText.
|> If I do, what consitutes a 'word'?
A contiguous string of characters.
|>
|> > 1+ underlined words [_multi]_word_ underlined text underline-tt (g)
|>
|> What consitutes a word? Does this run afoul of
|> multi_word_python_variable_names?
Same. Not really as there has to be both a leading and trailing underscore.
|>
|> > hypertextual 1+ word [multi_]word_ 1+ hot word(s) hot-tt (h)
|>
|> This is weird. Where is the reference? Has this been implemented in
|> gendoc?
Yes. You specify a_hyperlink_ like this and it points to the address spec'd
at the end of the doc string. It's not obvious from the setext docs. That's
why I explained it later with examples.
.. _a_hyperlink http://www.python.org/sigs/
|>
|> > >followed by text >[space][text] > [mono-spaced] include-tt (i)
|>
|> This looks like a quoted email message. But I guess it makes sense.
|>
|> > bullet-text in pos1 *[space][text] [bullet] [text] bullet-tt (j)
|>
|> I think 'o text' and '- text' are more readable.
|>
|> > `_quoted typotag!_` `_left alone!_` quote-tt (k)
|>
|> `_e_gads!_` I like 'this much better'
Don't think this comes up much and it's not necessarily implemented yet.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > [hypertext link def] ^.. _word URL jump to address href-tt (l)
|> > [hypertext note def] ^.. _word Note:("*") ("cause error") note-tt (m)
|>
|> I have no idea what this means.
|>
|> > -------------------- ------------------- --------------- ------------ ---
|> > 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)
|>
|> Huh?
Read on McDuff...
...
|> > -----------------------------------------------------------------------
|> > 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
|> > ==========
|>
|> This is not valid setext. Setext wants the titles and headings to start
|> in column 1 and the other text in column 3, like this:
Yes but the implementation doesn't enforce that now. headings and body can
be in column one. Remember Daniel strips the leading tab/spaces from the
doc string before applying these rules.
|>
|> SETEXT 102
|> ==========
|>
|> **Setext** can be used to mark your text in a non-obtrusive
|> manner. Text within double asterisks are treated as bold, ...
|>
|> > **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
|> > -------------------
|>
|> Ditto.
|>
|> > 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
|>
|> Why not:
|>
|> item1 -- Definition 1
|> ...
|>
|> This looks much better to me, and works with StructuredText.
Hey, I just picked it out of the blue. (And I've never seen your
structured text module.) ':-(
|>
|> > .. _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.
|>
|> Hm.
|>
|> > 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.
|>
|> I think my structured text module mechanism provides richer
|> text formatting with less obtrusive markup, especially for
|> strings that have much structure, as many of mine do.
|>
|> Jim
Fine,
Send it to me!!
-Robin
=================
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================