[Doc-SIG] Approaches to structuring module documentation

[Moshe Zadka]

On Fri, 12 Nov 1999, Fred L. Drake, Jr. wrote:

> Moshe Zadka writes:
>  > Hmmmmm....define User's Manual. What do you want from it?
> 
>   How to work with the interpreter and related tools.  It wouldn't
> teach the language, but would teach the environment and provide
> reference material for things like the user interface (for PythonWin
> or IDLE, or readline information for Unix).  Debuggers and profilers
> generally fall into this category of information.

Uh, OK. Would the things that are currently in the Python manual be part
of it? Obscure options like -X, -S or -i?

>  > But I can live with straight XML, if that's the party line.
> 
>   I don't think there's a "party line"; I just want to avoid
> introducing new dialects and processing stages.  There's enough that
> really needs doing on the content side of things that we don't need to 
> create new problems.

I thought we're trying to come up with a party line. Which would include,
among other things, a markup language...I just remarked I'm not adamant
on the SGML->XML stage, though I think it would improve the life of
documentation writers.

I think the looks should be always to Perland, in that respect. They
managed to come up with a standard so good, *every* module from CPAN has
a half-decent documentation at the least, which is very accessible. POD is
very light on the eyes and easy to write, and I do believe XML+ a bit of
SGML minimization could approach the ease, but I doubt XML alone could do
it. Just consider

<function/reverse/

Vs. either

<function>reverse</function>

Or

<function name="reverse"/>

It all depends on how much of SGML we wish to take. Other alternatives
include:

<function>reverse</>

(That last one is my favourite because modifying current XML tools to
deal with it seems relatively easy: an empty closing tag is mapped to the
last tag on the stack)
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.