[PYTHON DOC-SIG] Structured documentation syntax

[Jim Fulton]

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

No, the quotes are stripped.  Double quotes are not used for examples
specifically
so that you can use them for string literals and for actually quoting
other text.

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

When reading the text itself, the various types of bullets are helpful
for
visually separating different levels.  Also, the goal should be to
make the formatter as smart as possible about detecting formatting
so that authors can spend time thinking about documenting their
software and less time thinking about formatting.

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

You said this in another message a while ago and I didn't have a chance
to get back to you. (sorry:)  Could you send me a sample text that isn't 
converted properly?

> But as it stands now both of your examples above would
> be treated as OL and be numbered according to indentation.

I guess another option would be to treat numbered lists like descriptive
lists
to retain the original numbering.  So 

  iii. foo 

would become:

  <dt>iii</dt><dd>foo</dd>

Perhaps then there could be a separate notation for auto-numbering, 
like:

  #. foo

Does this make sense???

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

I wouldn't mind if 

  *python is my favorite language* became 
  <strong>python is my favorite language</strong>

But I'm note sure what to use for emphasis except that I don't like
using _ because of the overloaded language meaning.

Some possabilities:

  /python is my favorite language/ 

  **python is my favorite language**

bleh

> |>
> |> Btw, how do you make headings?  Do you just make everything a
> |> sub-paragraph of a short paragraph containing the heading?
> Yes.

Specifically, one-line paragraphs.
 
> |>
> |> 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!

Most of it has been clearly defined, but not will documented.

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