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. > 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.) > 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? > 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) ? 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. -- --Guido van Rossum (home page: http://www.python.org/~guido/) _______________________________________________ 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
