[PYTHON DOC-SIG] setext in doc strings

[Daniel Larsson]

Jim Fulton wrote:
> 
> Robin Friedrich wrote:
> >
> 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.

Yes, I got it.

> > |>   - It supports arbitrary levels of nesting, including numbered,
> > |> bulleted
> > |>     and descriptive lists.
> >
> > Nice.

I started yesterday to fool around with your module. It will probably be
awhile before I have something to share, but I would really like to use
your stuff, Jim, especially the nested/numbered list stuff.

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

Originally, gendoc used *emphasized string*, but I changed it to setext
syntax. I'd be happy to change it back, if that is the consensus of this
group.

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

Yes, that sounds reasonable. That is also what gendoc does. I don't (as
far as
I can remember...) use the physical markups of HTML.

> 
> > |>
> > |> >  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__?

Since variables with surrounding double underscores are *very* common in
Python, I explicitly check for this.

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

How do you derive the url?

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

*, - and o is now valid bullets ('o' is not in version 0.5). I'll add
quoted text, if no one objects.

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

Only the last is implemented in gendoc.

>   - A line ending in two dollar signs defines the end of a document
> component.
>     But, of course, document components have not been defined.

This is skipped too in gendoc

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

Yes that's correct (with the possible exception that I'm not sure I like
all I borrowed :-)

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

Well, this discussion is precisely what I wanted to see when I released
gendoc to this group. As I stated in the README, this is supposed to
be a collaborative effort, and I hope we can make this into a very
useful
tool for a lot of people in the Python community.

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

As I said, I want to take a good look at Jim's work. Unfortunately, some
of the work expected from me by my employer needs to be done, so I'm
afraid
it might take a couple of weeks before I have something for you to try
out.

Keep on discussing!

> 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
> =================

-- 
Daniel Larsson, ABB Industrial Systems AB

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================