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

[Edward D. Loper]

Mike said:
> 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).

Does it have any provisions for specifying descriptions of parameters,
etc?  Like "@param" and "@return" etc. in javadoc?

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

It's more heavyweight than what I was aiming for, but that's not to
say that it's too heavyweight.  I was just reacting to what I
percieved as the desire of most people..

> It's \emph{really} nice to have the \key{PASTE} key as a conversion
> tool. I find myself documenting modules a lot, classes a little,
> etc.  and by then, a first draft of the reference documentation is
> already done.

It still seems to me like this won't *quite* work with your system,
since you'll allow comments that include unbackslashed &'s and
\\s and whatever other characters LaTeX treats funnily..  But it's
certainly much closer than the markup languages we've been talking 
about on docsig.

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

It seems like a lot of the indexing and table-of-contents stuff is
really a tool issue, not a markup language issue..  How much explicit
info do you put in?  The markup language I've been thinking about is
mainly intended for API-level documentation, which is arguably
different from reference docs..  (I'm not one of the people who says
that the reference docs should be included inline).  I wouldn't
imagine most docstrings using sections, etc.

-Edward