[Doc-SIG] PEP-0216

[Moshe Zadka]

I hope your youngest got better.

On Mon, 13 Nov 2000, Tony J Ibbs (Tibs) wrote:

> Second, worries about documentation as a whole...
> 
> ((NOTE that this is what I would regard as pedantry - we are going to use
> STNG for docstrings, possibly subclassed, and everything else is frills. So
> continue at your peril...))

I've braved bigger Per[i]ls <wink>

> I was worried that Moshe wanted to do ALL the documentation using STNG (or
> whatever tool we decided on), but assumed that I was probably actually
> mistaken.

I depends on how you define "Moshe wants", probably.

> Oh dear, I was right. (I would point out I find the terms "parse time" and
> "run time" to be most misleading - there's documentation derived from the
> docstrings (be it at run time in an IDE, or on paper/the web statically),
> and there's documentatation written as such. OK, in the literate programming
> world there's an attempt to unify these, but we're not in that world. If
> Moshe is just assuming that *all* documentation for a module will be in
> docstrings, then I'm very confused.)

As I said, the issue of documentation outside docstrings, and it's
relationship with the documentation in the docstrings are outside the
scope of my PEP. Which is not to say they do not interest me, just
that I don't want to deal with them right now. So let's put all issues
of "inside" vs. "outside" to rest -- my PEP does not deal with external
documentation, and so has no opinion what to write where. However, I am
concerned if the format is too weak to document the whole module.
If you think this concern is baseless, please let me knw which precise
documentation requirement in the PEP causes STNG to be too heavy.

I've cruelly snipped all further references to that issue from
your e-mail.

> ...
> I believe he is right when
> he says very few people are interested in doing this, and I also trust him
> to get it right (he's done a wonderful job so far).

But Fred can't do that job, and he's not. He's documenting the Python core
moudles just fine, but what about the mass of third party modules? 
Someone has to document them, and it's up to the doc-sig to supply
standard, easy, tools. All the documentation within the module in STNG
is a great solution for those. Automatic tools which turn these into
Python-LaTeX would make documenting Python modules much easier. That's
what I want. 

> What does "inside the code" mean in [the Perl documentation] context? 

It means inside the code. *Inside*. In the same file.

Good distributions (ActivePerl for Windows, or Debian) format the
documentation to a suitable format (HTML and man pages, respectively)
before installation. Since they usually byte-compile (which gets
rid of all strings but the first -- please read my PEP carefully)
this means there is no penalty at run time either.

In any case, again, this is a non-issue, there might be a format for
external docs (in fact, there already is) -- butthis is outside
the scope of my PEP.

So we may fight later, but currently there is nothing (yet) to fight
about.
--
Moshe Zadka <moshez@math.huji.ac.il> -- 95855124
http://advogato.org/person/moshez