[PYTHON DOC-SIG] setext in doc strings
Jim Fulton
jim.fulton@digicool.com
Tue, 06 Aug 1996 08:26:21 -0400
Robin Friedrich wrote:
>
> |> 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.
Hm. It was only a K or so. I got a copy through the list. Dod anyone
else
not get the StructuredText note? Did everyone else get this note?
Robin, I forwarded another copy to you.
> |>
> |> - The sourse text os more readable,
>
> Really?:-)
Yes, assuming it is spelled correctly.
> |> - 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.
But it is easy to tell the two apart:
* this is a bulleted item. Notice the space after the star and no
"closing" star
But this paragraph *has some emphasized* text. Notice the position of
the * relative
to whitespace.
> |>
> |> > 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.
But I would argue that, while python documentation strings should not
be bound by HTML, they should share the philosphy of content, rather
than
presentation-oriented markup.
> |>
> |> 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.
Which characters? Are there limits? Are spaces allowed? What about
single quotes?
I think you need to be more specific.
> |>
> |> > 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.
Uh, you mean, as in __getstate__ or __add__?
> |>
> |> > 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/
Hm. I didn't try to address this in StructuredText. But there has to
be
a better way.
Something I've done in the past is:
(See so and so.)
gets translated, in HTML, to:
(See <a href="url derived from so and so">so and so</a>.)
> |>
> |> > >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.
It comes up *all the time* in my doc strings. If I am mentioning
a function name or argument to a method, I quote it to separate it from
the
rest of the text. Ditto if I mention a small snippet of code within
prose.
> |>
> |> > -------------------- ------------------- --------------- ------------ ---
> |> > [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...
I did. But I didn't see any new explanation. I studied the table some
more and
figured out that the ^ must mean the begining of a line. So let me see
if I've
got this straight:
- A line beginning with two dots is a "comment".
- There are special comments:
- A line with just two dots is the end of the document.
- A line beginning with two dots, a space, and an underscore
defines the
target of a reference in some fashion.
- A line ending in two dollar signs defines the end of a document
component.
But, of course, document components have not been defined.
> ...
> |> > -----------------------------------------------------------------------
> |> > 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.
I saw that below. But much of the argument for using setext seems to be
that you are leveraging an existing mechanism. Buy you aren't really.
You are
borrowing from it the things you like.
> |>
> |> 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.) ':-(
Hey, please don't take my note of a criticism of your work. I'm
just trying to comment on the format. I apreciate you and Dan moving
this
thing along.
> |>
> |> > .. _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!!
I did.
Jim
--
Jim Fulton Digital Creations
jim@digicool.com 540.371.6909
## Python is my favorite language ##
## http://www.python.org/ ##
=================
DOC-SIG - SIG for the Python Documentation Project
send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================