[Python-Dev] New Pythondoc by effbot (original) (raw)

Georg Brandl g.brandl at gmx.net
Sun Jan 22 10:23:24 CET 2006

Guido van Rossum wrote:

On 1/21/06, Georg Brandl <g.brandl-nospam at gmx.net> wrote:

What Fredrik hacks together there (http://www.effbot.org/lib) is very impressive. I especially like the "permalinks" in this style:

http://effbot.org/lib/os.path.join Which (despite having "perma" in its name) evaporates and leaves behind a link to os.path.html#join.

There may be other uses (e.g. marking a certain location in the docs with a "permalink" marker so that one can point the user to /lib/marker. Especially useful for the tutorial and recurring c.l.py questions ;)

What I would suggest (for any new doc system) is a "split" view: on the left, the normal text, on the right, an area with only the headings, functions, example and "see also" links (which preferably stays in sight). This way, you always keep the outline in view. Can you mock that up a bit? I'm somewhat confused about what you're requesting, and also worried that it would take up too much horizontal space. (Despite that monitors are wider than tall, horizontal real estate feels more scarce than vertical, because horizontal scrolling is such a pain.)

Something like

http://home.in.tum.de/~brandlg/zipfile.html

(It works this way (position: fixed) in most browsers, for IE one would have to apply compatibility hacks.)

Of course, I wouldn't say no to a user-commenting system, but this would have to be moderated. Why? If wikipedia can do without moderation (for most pages) then why couldn't the Python docs?

Well, why not... it's surely worth a try. Perhaps using a spam filter like most modern weblogs would suffice.

What I'm also curious about regarding the current docs, why are optional arguments in function declarations not written in Python style? I'm assuming you're asking why we use foo(a[, b[, c]]) instead of foo(a, b=1, c=2) ?

Yep.

I can see several reasons; arguments with default values aren't necessarily usable keyword arguments (at least not if they function/method is implemented in C); the default value isn't always relevant (or is dynamic, or is a huge expression); and square brackets are the standard way in computer manuals to indicate optional parts of syntax.

Thanks.

Georg

More information about the Python-Dev mailing list