[Doc-SIG] PEP-0216

[Moshe Zadka]

On Fri, 10 Nov 2000, Tony J Ibbs (Tibs) wrote:

> > There are three kinds of `documentation' I want associated
> > with a tool:
> >
> > comments -- which I read when I'm modifying the tool
> > manuals  -- which I read before trying to write code which uses
> >             the tool
> > docstrings -- which I read when I find the tool in my hands
> 
> Whilst one might argue with the *detail* of those descriptions, I believe
> that there is a very distinct diffference between manuals and docstrings (in
> much the same way as there is between books and memos).[1]
> 
> I assume that when you say "documentation" you *don't*, in fact, mean
> "manuals", but I have learnt to be cautious, because I *have* seen people
> conflating the two in the past, and I want to make sure we know what we
> aren't doing...

If you read the PEP carefully, you'd notice that I'm thinking of
docstrings in two related ways: parse time and run time. The parse time
docstring is a superset of the runtime docstring. The runtime docstring
is the memo, the parse time is the book.

> I think I'm also upset if you expect people writing manuals to have to use
> the same format designed for docstrings, since the AIMS are different -
> docstrings must be pleasant to read "as is", by people inside the code, or
> people using a class browser, but very few people (um, well) read HTML or
> XML or TeX raw, and most people don't even *write* them "raw". And in "real"
> documentation you often want to have closer control over what is going on
> than StructuredText will allow.

I don't believe that is true: as you say, nobody wants to write HTML or
XML or TeX.

> Tibs, feeling he should be worried *just in case*

Not really: I'm not saying documentation for a module *must be* in the
module, I'm saying the format must be flexible enough for it to be
able to. What people will do is their own business.

In my last proposal after IPC8, there was an elabortate
template/docstring/xml trinity. At the time it was dismissed by Fred
as irrelevant: it seems there are less then 5 people on the face of the
planet interested in documentation outside the modules, so he can
decide on the format himself. I told him I *am* interested, and if
you are, you should tell him so too. In any case, the relationship
between a manual outside and a docstring inside is yet to be defined,
and not by PEP-0216. 

Let me just note that as a Perl hacker, the fact that the documentation
(up to and including the tutorial and manual) being *inside* the code
is very convinient. E.g., knowing that "perldoc HTML::Mason" just 
works, and gives me everything I need. Indeed POD is a large part
of my inspiration.
--
Moshe Zadka <moshez@math.huji.ac.il> -- 95855124
http://advogato.org/person/moshez