> Issue: foo.help()
[[I proposed adding a function help() to each module which looks up
the file module.doc in sys.path.]]
> position: against. help should be a builtin.
>
> why: consistant behaviour is a very good thing in a documentation
> system. multiple instances of function needless work for parser.
Making it a built-in has the problem that it fixes the behaviour
unless you are very careful to make it extensible or overridable.
What I could do is make a built-in help() that imports the standard
module _help (written in Python) and calls a function _help.help(arg).
This function could be clever and extract the module name if the
argument is a module object, etc.
> Issue: literate programming / embedded documentation
>
> position: vaguely for it.
> references: m3totex, c2man.
>
> why: when the docs are 3 lines from the code, you are likely to keep
> it up to date, or at least delete it is it is wrong.
Agreed, but two problems: (1) converting existing docs and (2)
developing a spec. The spec should have two parts: (a) a syntax so
that the stuff could be picked up and formatted automatically (this is
really two pieces again -- brackets to separate the docs from the code
and a formatting language to be used in the docs part), and (b)
conventions for what to document and how. Both parts of the spec
should be geared (in my opinion) to power users -- at all costs avoid
having to write a page of documentation for each three-line function.
Possibly the same mechanism could be used to generate several
different sets of docs: for the Python end user, for the extension
writer, and for the few (e.g. myself :-) who actually hack the
interpreter.
> ideas: get some matching comments into python (* foo *), so that
> generic tools like pytotex/pytolout/pytoroff can be written to
> extract formatted documentation from a module.
Doesn't have to be a change to the language -- could be done with
something like #$$[ ... #$$]. Also note that much of the
documentation goes with C code, not with Python code. Again /*$$[
... $$]*/ might work. What do other C literate programming projects
use? I have a feeling that this is so simple (couple of pages of
Python to get started) that we needn't adopt an existing system,
though we could probably usefully borrow ideas...
> <various ideas about typeseter-free formatting techniques>
I currently favor either HTML (possibly HTML+) or a format that is
easily converted to HTML(+). HTML keeps a lot of structure without
being a general formatting language like LaTeX. (The problem with the
latter is that it is hard to convert to another format, which is
essential since we may want to make the info available through the
user's favorite on-line help system, e.g. MS Help, Mosaic or Emacs
Info.)
> bizarre idea: natural language generator to convert python code to
> natural language
>
> def foo():
> i = 5
> f = i * 10
> a = bar()
> return a
>
> Define function foo, which takes no arguments to do the following:
> Assign the value 5 to variable 'i', then multiply 'i' by 10, and
> store the result in 'f'. Call function 'bar' with no arguments, and
> save the return value in 'a', then return the value of 'a'.
>
> Looks like a great overly ambitous idea to me. would be vaguly useful
> to someone i bet.
I don't see the point. Surely a function of any use would generate a
sentence that may formally be English but is much *less* readable than
the Python original (in fact this is already true for your example).
Remember the COBOL fallacy.
> John Redford (AKA GArrow) | 3,600 hours of tape.
> jredford@lehman.com | 5 cans of Scotchguard.
--Guido van Rossum, CWI, Amsterdam <Guido.van.Rossum@cwi.nl>