[Doc-SIG] which characters to use for docstring markup

[Edward D. Loper]

> The formatter is an extension that I've added to HappyDoc. I'm working with
> the author to get the changes back into the distribution; with luck they
> may be done RSN (days). I hope they will be adopted into the next version
> (the changes are small, and it really just introduces a new hdformatter).

Could you put it on the web someplace?

Incidentally, I have a question about HappyDoc terminology -- they 
seem to use the word formatter to refer to both what I would call 
a "parser" (convert representation to an interlingua) and an 
"outputter" (convert interlingua to  output representations).  Do 
they do all the translations in one step?  If so, doesn't that make 
it a pain to write outputters for each output format?  Or do they 
just use terminology differently than I expect them to (I would 
think that a "formatter" would be what I would call an "outputter"??)

> Heavyweight is a relative term of course, and I think most users of TeXinfo
> feel it's not too heavy. It's a fair balance between light and complete.

I think that many people on this sig would say that its syntax
for lists is too heavy-weight.  I myself would be ok using XML,
so I'm noot really one of the ones strongly lobbying for lightweight..
but I want somethign that people will accept.  And I think it's much
more likely that people will type:
   - lists like this
than:
\begin{itemize}
  \item lists like this
\end{itemize}

(which is not to say that I'd support any sort of hybrid.. if
you're using the subset of LaTeX supported by Doc, then you should
use just that)

> I only wrote the LaTeXinfo extention to HappyDoc last week, and already
> I'm very Happy \grin.  But the LaTeXinfo version is by far the most advanced: 
> having my entire module and class structure documented with indexing, Table
> of Contents and cross-references, in HTML, info and PDF is huge.*

I assume you use somethign like \label{foo} and \ref{foo} for 
cross-referencing?

> Sorry, what I meant was backward compatible with all the current docstrings
> in the existing Python library. It is backward compatible in the sense:
> 
> \begin{enumerate}
> \item	There are very few occurences of \textbackslash.
> \item	A blank line implies a paragraph.
> \end{enumerate}

Presumably you also have to worry about '{' and '}' because
LaTeX will treat '{hi}' as equivalant to 'hi', etc.

> \item	Implement the tty parser for docstrings so that they look pretty
> at the terminal.

For me, this would be a pretty essential precondition to accepting 
a markup language like the one you propose.

> * \footnote{If people want, I can put a copy of a HappyDoc LaTeXinfo generated
> PDF file up on starship for people to browse.}

I'd like to see what the HTML output looks like too.

-Edward