Not really, just with the note that this was not meant to be a
polished message.
>> > Issue: foo.help()
>>
>> 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.
I can see this. My point against a help() in every module is that one
author would write help() in one way, and another in another way. I am
sure the code reuse and consistent interface issues there are obvious.
>> > Issue: literate programming / embedded documentation
>>
>> 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.
This all sounds good, but I dont see why a 'power user' is defined as
someone likely to write 3 line functions. :) They are more likely to
write larger ones I hope. Missing documentation can always be handled
"foo: no documentation found".
>> > 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...
Does #$$[ have some meaning I am unaware of? It seems needlessly
line-noise like offhand. The issue is more one of delimiting a
indentation-context free region, so that one dosent need to fit a long
documentation line into the right 30 columns.
I also don't know how useful it would be to make C comments into docs.
since it is useful to avoid knowing where code is, it might be better
to embed the docs into the object files as string literals. It makes
the case of importing foo.o more likely to bring documentation along.
>> > <various ideas about typesetter-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.)
I am not familiar with HTML, but this is definitely a distinct topic.
What the docs are actually written in is only related to python when
there is an attempt to validate or auto-generate the documentation
from the code.
>> > bizarre idea: natural language generator to convert python code to
>> > natural language
>>
>> 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.
Well, It was just being said for the hell of it. This type of idea is
'closer' to the literate programming goal (which as i see it is having
language X that can be read or compiled).
-- John Redford (AKA GArrow) | 3,600 hours of tape. jredford@lehman.com | 5 cans of Scotchguard.