Re: [Python-Dev] New Pythondoc by effbot
For me, the -nospam suffix works relatively good to avoid spam, as most harvesting programs will think this is a false address. http://spambayes.org works, too, without bothering others 0.5 wink =Tony.Meyer ___ 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
Re: [Python-Dev] New Pythondoc by effbot
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
Re: [Python-Dev] New Pythondoc by effbot
Georg Brandl wrote: [...] 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.) Vertical spacing is IMHO pretty bad on this page. Everything has the same distance from everything else. This makes understanding the structure of the page pretty hard. Bye, Walter Dörwald ___ 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
Re: [Python-Dev] New Pythondoc by effbot
Walter Dörwald wrote: Georg Brandl wrote: [...] 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.) Vertical spacing is IMHO pretty bad on this page. Everything has the same distance from everything else. This makes understanding the structure of the page pretty hard. The main content is the original zipfile.html from http://www.effbot.org/lib/zipfile.html. Only the sidebar is my addition. 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
Re: [Python-Dev] New Pythondoc by effbot
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
Re: [Python-Dev] New Pythondoc by effbot
Georg Brandl wrote: Vertical spacing is IMHO pretty bad on this page. Everything has the same distance from everything else. This makes under- standing the structure of the page pretty hard. The main content is the original zipfile.html from http://www.effbot.org/lib/zipfile.html. Only the sidebar is my addition. the effbot.org/lib material is raw HTML; at this stage, I'm working on getting the translation and the information model right, not polishing the formatting. formatting ideas are of course welcome (especially in CSS form), but comments on the information structure are more useful at this time. /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
Re: [Python-Dev] New Pythondoc by effbot
(this is the main motivator behind my documentation and site efforts; we should learn not to press control-enter when we mean enter. anyway, what I intended to say was that we should work harder on lowering the threshold for drive-by contributions; it should be possible for anyone to notice a problem, add a comment or correction, preview the correction properly rendered, and submit it to a moderation queue, in less than a minute. (I still think moderation is needed before corrections are made visible, but that should be no harder, nor require any more tools, than making the correction in the first place. I'm sure we could get some turbogears/django hackers to build us a nice moderation queue webapp in no time at all...) /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
Re: [Python-Dev] New Pythondoc by effbot
Guido van Rossum wrote: On this page, 8 of 30 entries have a 'new in' comment. For anyone with no interest in the past, these constitute noise. I wonder if for 3.0, the timer can be reset and the docs start clean again. To keep them backwards compatible, they would also have to be littered with 'changed in 3.0' and 'deleted in 3.0' entries. Better, I think, to refer people to the last 2.x docs and a separate 2.x/3.0 changes doc. (That has nothing to do with Fredrik's efforts of course -- he's just faithfully copying the annotations from the existing docs.) If Python 3.0 is indeed the major incompatible release that we currently expect it will be, I agree that new in 3.0 and new in 2.x annotations make little sense, since so much will be new in 3.0 (or deleted in 3.0). It's probably better to have a separate document explaining the differences between 2.x and 3.0. absolutely. For the 2.x line, however (and again post-3.0) I think the new in X annotations are important -- lots of people have to deal with different Python versions, and it's a lot easier to depend on new in X notations than to manually compare two or more versions of the docs. (Although you still need to do thorough testing -- like the rest of the docs, these annotations can't be 100% perfect.) if we move over to a web-oriented (wiki-ish) maintenance model, we probably have to accept that X will, sometimes, be a future release. /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
Re: [Python-Dev] New Pythondoc by effbot
Fredrik Lundh wrote: (this is the main motivator behind my documentation and site efforts; we should learn not to press control-enter when we mean enter. anyway, what I intended to say was that we should work harder on lowering the threshold for drive-by contributions; it should be possible for anyone to notice a problem, add a comment or correction, preview the correction properly rendered, and submit it to a moderation queue, in less than a minute. (I still think moderation is needed before corrections are made visible, but that should be no harder, nor require any more tools, than making the correction in the first place. I'm sure we could get some turbogears/django hackers to build us a nice moderation queue webapp in no time at all...) Or go low-tech and have a 'mailto' link that goes to a documentation discussion list ;) Cheers, Nick. P.S. I do like the way this is coming together - particularly if we can find some cross-platform CSS like Georg's to keep the handy list of links on the right. -- Nick Coghlan | [EMAIL PROTECTED] | Brisbane, Australia --- http://www.boredomandlaziness.org ___ 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
Re: [Python-Dev] New Pythondoc by effbot
On 1/21/06, Georg Brandl [EMAIL PROTECTED] wrote: And, of course, the new in 2.x could be formatted less space-consuming, perhaps to the right of the method name. No, that would give it too much attention. It's getting way too outstanding in effbot's sample, probably because he didn't implement the formatter for @since yet. It should simply be an addition to the text paragraph that precedes it, like in the regular docs. -- --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
Re: [Python-Dev] New Pythondoc by effbot
(This is a bulk reply to several messages in this thread from Georg and Fredrik.) [Georg] http://effbot.org/lib/os.path.join [Guido] Which (despite having perma in its name) evaporates and leaves behind a link to os.path.html#join. [Georg] 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 ;) Rather than allowing users to add new markers I'd like the document to be sprinked generously with pregenerated markers to which one can easily linked. I've seen sample docs (not for Python) with such a feature. [Fredrik, in a different message] 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 That sounds overkill. But if you could drop the redundant .html, the links in the source could look like like .../os.path#join which is just fine with me (and solves the problem of what part is the module, on which you spend altogether much time explaining how to compute in the current version :-). however, at this point, I'm more interested in getting the information model to a point where this can be done. Understood. What's still missing from the info model? It looks pretty complete to me from a quick scan. [Georg again] 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. [Guido] 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.) [Georg] 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.) I believe there's a CSS trick (most often used for images) that can makes the summary window float to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition! 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. Have you studied wikipedia's approach? It's multi-layered and worth learning from (start with their FAQ on editing). (And by the way, I am *not* advocating writing the docs as one big wikipedia -- only the user commentary.) [Fredrik again] the [] syntax has its issues, including that it makes keyword arguments look like positional arguments, (I think that is actually Python's fault for not distinguishing them in the function definition. :-) 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. Or (my favorite, but still wrong) foo([a, b, c, d, e, f]) there are ways to address all these problems with a more pythonic syntax, but I'll have to get back to that later. Please do. [Fredrik, in yet another message] anyway, what I intended to say was that we should work harder on lowering the threshold for drive-by contributions; it should be possible for anyone to notice a problem, add a comment or correction, preview the correction properly rendered, and submit it to a moderation queue, in less than a minute. Given that it will take significantly longer to *process* the queue I don't necessarily want to make the contribution process *too* easy -- we need to balance the quality of the contributions with the ease to make them. For many simple corrections (spelling, grammar, inversions, some factual mistakes) the need to preview the correction properly rendered is quite unnecessary; the important part is being able to *point* at any word or words in the text and attach a comment. (I still think moderation is needed before corrections are made visible, but that should be no harder, nor require any more tools, than making the correction in the first place. I'm sure we could get some turbogears/django hackers to build us a nice moderation queue webapp in no time at
Re: [Python-Dev] New Pythondoc by effbot
2006/1/22, Georg Brandl [EMAIL PROTECTED]: Guido van Rossum wrote: ... 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. I can see three levels of permissiveness. Everybody (with or without registration?) will be able to post whatever, but the annotation... - will be posted always - will go through an antispam - will go through a posting-revision-comitee (that is, a human antispam, ;)). I don't like the first one, I'm +1 with the second and +0 with the third. In the last two, specially in the third one, you'll need human workforce. I'm stepping forward for that, if you need it. .Facundo Blog: http://www.taniquetil.com.ar/plog/ PyAr: http://www.python.org/ar/ ___ 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
Re: [Python-Dev] New Pythondoc by effbot
Guido van Rossum wrote: 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 ;) Rather than allowing users to add new markers I'd like the document to be sprinked generously with pregenerated markers to which one can easily linked. I've seen sample docs (not for Python) with such a feature. Exactly what I had in mind. And we can add markers by request of the c.l.py support regulars. 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.) I believe there's a CSS trick (most often used for images) that can makes the summary window float to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition! Well, floating the summary is no problem, but it wouldn't stay at the side if you scroll down then. I updated the mockup a bit: http://home.in.tum.de/~brandlg/zipfile.html An alternative with floating summary: http://home.in.tum.de/~brandlg/zipfile-float.html 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. Have you studied wikipedia's approach? It's multi-layered and worth learning from (start with their FAQ on editing). (And by the way, I am *not* advocating writing the docs as one big wikipedia -- only the user commentary.) Agreed. Something like a discussion page could be fruitful. (I still think moderation is needed before corrections are made visible, but that should be no harder, nor require any more tools, than making the correction in the first place. I'm sure we could get some turbogears/django hackers to build us a nice moderation queue webapp in no time at all...) Agreed. But as I said above, I think there should also be a way to simply add comments, without moderation (but with wikipedia-style editing / spam-removal / moderation after-the-fact). And, probably, if we don't get to the moderation queue etc., the comments wiki could serve as a moderation queue as well. Being public, it would also reduce the submission of duplicate corrections (especially when the moderator is out of town for a while). +1. [Fredrik, later] if we move over to a web-oriented (wiki-ish) maintenance model, we probably have to accept that X will, sometimes, be a future release. This makes me worry that you're thinking of abandoning having separate docs per version. That would be a shame; I think the docs ought to be maintained well enough to be authorative for a particular version (modulo bugs in the docs). Perhaps we could add links that let you navigate between versions quickly, and hopefully we can somehow (optionally?) merge the wiki-style user comments across versions. +1. (Although I can also see the point of starting afresh for each release -- at some point the sheer amount of (possibly outdated) user comments reduces their usefulness. That would have to be decided in situ. regards, 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
Re: [Python-Dev] New Pythondoc by effbot
[Aahz] Aside to Georg: your messages are all getting /dev/null'd because you use spam in your From: line. I get too much spam to change that, and I'll bet other people use that heuristic. Please change your From: line for this mailing list. [Georg Brandl] I don't quite understand that. Why would a spam email have spam in the From? In general it wouldn't. Aahz didn't tell us everything, or he's simply not making sense. Because I still like ;-) the SpamBayes project, I don't do anything to try to stop receiving spam, and have several email addresses that have been visible for years. Of the 4456 spam I received via Outlook in the last 30 days, onlly 3 had spam in the From header: From: [EMAIL PROTECTED] From: .Φ.αΦδ .α±ΩεΓ [EMAIL PROTECTED] From: spam [EMAIL PROTECTED] It was much more common among ham, including email from you, from the spambayes mailing lists, from SORBS, If: The `From:` header contains spam as a substring, case-insensitively. were a feature SpamBayes scored, it would be a strong ham clue in my training database. For me, the -nospam suffix works relatively good to avoid spam, as most harvesting programs will think this is a false address. Of course, that may be more useful in Usenet, not in mailing lists. It's OK by me if you keep using it. ___ 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
Re: [Python-Dev] New Pythondoc by effbot
Guido van Rossum wrote: I believe there's a CSS trick (most often used for images) that can makes the summary window float to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition! Something like this... http://beta.python.org/download/releases/2.4.1/ Tim ___ 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
Re: [Python-Dev] New Pythondoc by effbot
Tim Parkin wrote: Guido van Rossum wrote: I believe there's a CSS trick (most often used for images) that can makes the summary window float to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition! Something like this... http://beta.python.org/download/releases/2.4.1/ It would also be simple to add an 'alternate stylesheet' that can hide the left hand navigation. A small link could be added to switch styles (which would include javascript) but all good browsers allow you to choose which stylesheet you wish to use without the aid of javascript (which I beleive should only be used for 'optional enhancements' to a website). The layout also positions the main navigation at the bottom of the html source so the first items you see using a 'text browser' are the breadcrumb and document level navigation. Tim Parkin ___ 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
Re: [Python-Dev] New Pythondoc by effbot
Tim Parkin wrote: Tim Parkin wrote: Guido van Rossum wrote: I believe there's a CSS trick (most often used for images) that can makes the summary window float to the right so that below it the main text resumes the full breadth of the window. If you can pull that off I think this is a good addition! Something like this... http://beta.python.org/download/releases/2.4.1/ That's an ordinary float, I presume? It would also be simple to add an 'alternate stylesheet' that can hide the left hand navigation. A small link could be added to switch styles (which would include javascript) but all good browsers allow you to choose which stylesheet you wish to use without the aid of javascript (which I beleive should only be used for 'optional enhancements' to a website). Good idea! Dito for options like enlarge text or such. 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
Re: [Python-Dev] New Pythondoc by effbot
Georg Brandl wrote: Tim Parkin wrote: Something like this... http://beta.python.org/download/releases/2.4.1/ That's an ordinary float, I presume? indeed it is. It would also be simple to add an 'alternate stylesheet' that can hide the left hand navigation. A small link could be added to switch styles (which would include javascript) but all good browsers allow you to choose which stylesheet you wish to use without the aid of javascript (which I beleive should only be used for 'optional enhancements' to a website). Good idea! Dito for options like enlarge text or such. It already has a 'large text' alternate style sheet, however it needs a couple of tweaks since I've made some big style sheet changes. The style sheet switching is well documented here with example code etc... http://www.brothercake.com/site/resources/scripts/iotbs/ Tim ___ 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
Re: [Python-Dev] New Pythondoc by effbot
[Fredrik, later] if we move over to a web-oriented (wiki-ish) maintenance model, we probably have to accept that X will, sometimes, be a future release. This makes me worry that you're thinking of abandoning having separate docs per version. That would be a shame; I think the docs ought to be maintained well enough to be authorative for a particular version (modulo bugs in the docs). Perhaps we could add links that let you navigate between versions quickly, and hopefully we can somehow (optionally?) merge the wiki-style user comments across versions. (Although I can also see the point of starting afresh for each release -- at some point the sheer amount of (possibly outdated) user comments reduces their usefulness. It would probably be best to clear out the comments for each minor release. Otherwise they will just organically grow. Problem is that useful examples might disappear. This might suggest that having possible example usage tagged on to a method or such could be saved and, by default, made folded (ala folding in Ian Bicking's Python doc comment system: http://blog.ianbicking.org/python-doc-comments.html). These examples could also be verified using something like doctest so that invalidated examples do not persist or submitted. And to /F, kudos from me. I have been randomly thinking about it and I understand your desire for semantic markup now. Hopefully something can get hammered out so that at least the Python 3 docs can premiere having been developed on by the whole community. -Brett ___ 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
