[PYTHON DOC-SIG] Structured documentation syntax

[Robin Friedrich]

|> Date: Tue, 10 Sep 1996 10:08:38 +0900
|> From: Ka-Ping Yee <s-ping@orange.cv.tottori-u.ac.jp>
|> 
|> Syntactic things:
|> -----------------
|> 
|> I know that it may not be my place to speak so soon, as i have
|> not spent any time researching what has been done, but a look
|> at the description on the doc-sig page produced these thoughts
|> (in order of decreasing strength):
|> 
|>   - Double-quotes seem too common to be used as hyperlink delimiters.
|>     More in keeping with common practice might be the use of [],
|>     the way most people use them to mark references.

Text found in double quotes are checked against the footnote references
found at the bottom of the doc string. If no match is found, it's just
left alone.
|> 
|>   - Also, it would make sense for double and single quotes to both
|>     mark example code.  What if you need to talk about a single-quoted
|>     string, for example?

I'll let Jim Fulton answer this one. The double quotes would be overused
if applied to this case as well, IMO.  Single quoted text gets marked as
<code> but the quotes remain, I believe.
|> 
|>   - As noted on the page, use of "--" is reasonably common for
|>     em-dashes (in fact, i'd even suggest turning them into real
|>     &emdash; entities in HTML).  Why not use "::" instead for
|>     tagged list elements?

Again the effort here was to make it as natural looking as possible.
I originally chose :: but changed it after Jim objected. I think it's
more likely to be found in existing docs with dashes.

|> 
|>   - Couldn't you just choose one bullet marker for list elements,
|>     instead of three?

Again, the intent is to minimize the need for overhaul of existing 
doc strings.
|> 
|>   - Is it true that a first-level list begins "12 First sentence..."
|>     but deeper levels begin "3.4. First sentence..."?  That is, the
|>     description on the page seems to imply that the periods follow
|>     each ordering component, rather than separate them.

The nesting paragraph stuff isn't fully functional in the current
gendoc beta. But as it stands now both of your examples above would 
be treated as OL and be numbered according to indentation.
|> 
|>   - It might be nicer (simpler) to use _underscores_ for italics
|>     and use *single asterisks* for bold.  (Special Python names
|>     that start and end with underscores should be marked as code
|>     examples anyway...)

Again, we used to do exactly this when setext was used as the standard.
But it makes things difficult to distinguish things like __init__ as
not needing to be marked up.
|> 
|> Btw, how do you make headings?  Do you just make everything a
|> sub-paragraph of a short paragraph containing the heading?
Yes.

|> 
|> Semantic things:
|> ----------------
|> 
|> Has there been any thought towards a well-defined standard
|> for documenting functions?  I'm thinking of things about
|> the interface, like parameter lists and descriptions of
|> parameters, and maybe a defined place for a one-sentence
|> (or even one-predicate) summary of what the function does,
|> and/or what circumstances it expects to be run under.

This hasn't been dicussed much yet but needs to be. That's 
precisely what this group is about!
|> 
|> I think this could be fairly useful.  A project i'm working
|> on now (called MINSE, for the representation of structured
|> expressions -- like math -- in HTML documents) needs a way
|> to describe just these kinds of things about functions, and
|> not just for the sake of documentation but actually as a real
|> part of its operation.  I want it to produce semantic information
|> attached to the structures in the expression, and the perfect
|> place to describe this seems to be __doc__.  So i am thinking
|> about designing a way to specify this information, but after
|> reading the post thought that it might be better for gendoc
|> and MINSE to understand things the same way.
|> 
|> For more info on MINSE, please see http://www.lfw.org/math/.
|> (Slightly out of date, so i can give more details if anyone
|> has questions.)
|> 
|> It currently has a working renderer for math expressions,
|> which makes it possible for anyone to write math directly
|> in their HTML and anyone to view it in any graphical OR
|> textual browser.  It's done in Python, of course. :)
|> 
|> 
|> Ping

Looks promising. I'm looking forward to your contributions.
-Robin

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

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