Guido 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.
"permalink" was george's term; I'm just calling them "link URLs"
http://online.effbot.org/2006_01_01_archive.htm#link-doc
to make them "real permalinks", we could:
- generate individual pages for all targets (on demand), with
a "see this in context"
- return the same page and use some javascript trickery to
emulate anchors
or use some other approach that I cannot think of right now
however, at this point, I'm more interested in getting the information
model to a point where this can be done.
> > 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?
wikipedia has a large numbers of volunteers that constantly monitor all
updates to the site. I'm not we have enough volunteers in python land,
and even if we have, I'm not sure site monitoring is the best way to use
the volunteer resources.
(this is the main motivator behind my documentation and site efforts; we
> > 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.
the [] syntax has its issues, including that it makes keyword arguments
look like positional arguments, and that descriptions that have lots of
optional arguments tend to look like either
foo([a[,b[,c[,d[,e[,f]]]]]])
foo([a][,b][,c][,d][,e][,f])
where the first one is ugly and hard to read, and the latter is, strictly
speaking, not correct.
there are ways to address all these problems with a more pythonic syntax,
but I'll have to get back to that later.
</F>
_______________________________________________
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
