Guido van Rossum wrote: > On 1/21/06, Georg Brandl <[EMAIL PROTECTED]> 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 _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
