From mike at pcblokes.com Wed Nov 3 12:30:54 2004 From: mike at pcblokes.com (Voidspace) Date: Wed Nov 3 12:31:06 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <20041102192742.B8BEB18E89A@grendel.fdrake.net> References: <20041102192742.B8BEB18E89A@grendel.fdrake.net> Message-ID: <4188C16E.9030107@pcblokes.com> What's the best way to get involved with contributing to python documentation. I'd like to write some better docs for urllib2 - but I don't know how to learn the required documetnations standard. Regards, Fuzzy Fred L. Drake wrote: >The development version of the documentation has been updated: > > http://www.python.org/dev/doc/devel/ > >Python 2.4b2 documentation. > >A downloadable package containing the HTML is also available: > > http://www.python.org/dev/doc/python-docs-devel.tar.bz2 >_______________________________________________ >Doc-SIG maillist - Doc-SIG@python.org >http://mail.python.org/mailman/listinfo/doc-sig > > > > > -- http://www.Voidspace.org.uk The Place where headspace meets cyberspace. Online resource site - covering science, technology, computing, cyberpunk, psychology, spirituality, fiction and more. --- http://www.Voidspace.org.uk/atlantibots/pythonutils.html Python utilities, modules and apps. Including Nanagram, Dirwatcher and more. --- http://www.fuchsiashockz.co.uk http://groups.yahoo.com/group/void-shockz --- Everyone has talent. What is rare is the courage to follow talent to the dark place where it leads. -Erica Jong Ambition is a poor excuse for not having sense enough to be lazy. -Milan Kundera From mwh at python.net Wed Nov 3 16:29:10 2004 From: mwh at python.net (Michael Hudson) Date: Wed Nov 3 16:29:16 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <4188C16E.9030107@pcblokes.com> (Voidspace's message of "Wed, 03 Nov 2004 11:30:54 +0000") References: <20041102192742.B8BEB18E89A@grendel.fdrake.net> <4188C16E.9030107@pcblokes.com> Message-ID: <2mk6t354u1.fsf@starship.python.net> Voidspace writes: > What's the best way to get involved with contributing to python > documentation. > > I'd like to write some better docs for urllib2 - but I don't know how > to learn the required documetnations standard. Well, there's http://docs.python.org/doc/... what else do you need to know? Cheers, mwh -- If you don't use emacs, you're a pathetic, mewling, masochistic weakling and I can't be bothered to convert you. -- Ron Echeverri From mike at pcblokes.com Wed Nov 3 17:50:15 2004 From: mike at pcblokes.com (Voidspace) Date: Wed Nov 3 17:50:26 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <2mk6t354u1.fsf@starship.python.net> References: <20041102192742.B8BEB18E89A@grendel.fdrake.net> <4188C16E.9030107@pcblokes.com> <2mk6t354u1.fsf@starship.python.net> Message-ID: <41890C47.5020807@pcblokes.com> Michael Hudson wrote: >Voidspace writes: > > > >>What's the best way to get involved with contributing to python >>documentation. >> >>I'd like to write some better docs for urllib2 - but I don't know how >>to learn the required documetnations standard. >> >> > >Well, there's http://docs.python.org/doc/... what else do you need to >know? > > Hmmm... that should just about do it. Thanks Fuzzy >Cheers, >mwh > > > -- http://www.Voidspace.org.uk The Place where headspace meets cyberspace. Online resource site - covering science, technology, computing, cyberpunk, psychology, spirituality, fiction and more. --- http://www.Voidspace.org.uk/atlantibots/pythonutils.html Python utilities, modules and apps. Including Nanagram, Dirwatcher and more. --- http://www.fuchsiashockz.co.uk http://groups.yahoo.com/group/void-shockz --- Everyone has talent. What is rare is the courage to follow talent to the dark place where it leads. -Erica Jong Ambition is a poor excuse for not having sense enough to be lazy. -Milan Kundera From mike at pcblokes.com Wed Nov 10 17:33:28 2004 From: mike at pcblokes.com (Michael Foord) Date: Wed Nov 10 17:19:27 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <20041110154700.5763718E89A@grendel.fdrake.net> References: <20041110154700.5763718E89A@grendel.fdrake.net> Message-ID: <419242D8.9010004@pcblokes.com> What's the easiest way to go about suggesting/submitting minor changes to the docs ? I'd like to improve the docs for urllib2. I had a look at the documenting python stuff - but it seems horrendously complex, including latex markup etc. Ideally I'd love to submit text - I don't want to create extra work for other people, but I think my contribution would be worth it !! Regards, Fuzzyman Fred L. Drake wrote: >The development version of the documentation has been updated: > > http://www.python.org/dev/doc/devel/ > >Lots of changes to how tables are actually formatted, with much of the >styling moved from the HTML to the CSS stylesheet. > >Tables also look nicer in supporting browsers. > >Please review the tables and report any strange presentations; be sure >to include the specific browser (including platform and version!) in >your report. > > >A downloadable package containing the HTML is also available: > > http://www.python.org/dev/doc/python-docs-devel.tar.bz2 >_______________________________________________ >Doc-SIG maillist - Doc-SIG@python.org >http://mail.python.org/mailman/listinfo/doc-sig > > > > > From fdrake at acm.org Wed Nov 10 17:37:45 2004 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Wed Nov 10 17:37:55 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <419242D8.9010004@pcblokes.com> References: <20041110154700.5763718E89A@grendel.fdrake.net> <419242D8.9010004@pcblokes.com> Message-ID: <200411101137.45943.fdrake@acm.org> On Wednesday 10 November 2004 11:33 am, Michael Foord wrote: > What's the easiest way to go about suggesting/submitting minor changes > to the docs ? Filing a bug/issue on SourceForge is best, since that way it doesn't get lost in my mailbox. > I'd like to improve the docs for urllib2. I had a look at the > documenting python stuff - but it seems horrendously complex, including > latex markup etc. You don't need to learn all that. That's documented for those who want to do all that, and are comfortable with LaTeX. Some people are actually using the tools we use for other documentation projects (often for Python-related software). > Ideally I'd love to submit text - I don't want to create extra work for > other people, but I think my contribution would be worth it !! The text is certainly the most important part. You don't need to worry about the markup. I'm happy to convert the plain text myself if you can provide new text. I've added some comments to "Documenting Python" recently (last week) to try and emphasize that contributors don't need to learn or use LaTeX; perhaps you looked at it before that went in. I'm always interested in suggestions! I appreciate your interest in helping out. -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Wed Nov 10 21:33:23 2004 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Wed Nov 10 21:33:38 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <16786.29365.808646.948039@montanaro.dyndns.org> References: <20041110154700.5763718E89A@grendel.fdrake.net> <16786.29365.808646.948039@montanaro.dyndns.org> Message-ID: <200411101533.23469.fdrake@acm.org> On Wednesday 10 November 2004 02:57 pm, Skip Montanaro wrote: > Fred> Lots of changes to how tables are actually formatted, with much > of Fred> the styling moved from the HTML to the CSS stylesheet. > > Fred> Tables also look nicer in supporting browsers. > > Any idea what browsers those would be? All graphical browsers I tested with until I booted a Windows machine. ;-) Specifically: Mozilla 1.8a4 on Linux, Opera 7.21 on Linux, Galeon 1.2.13 (yet another Gecko wrapper) on Linux. Things looked fine on links, lynx, and w3m as well, though I don't expect they looked better than before. ;-) > Fred> Please review the tables and report any strange presentations; > be Fred> sure to include the specific browser (including platform and > Fred> version!) in your report. > > Using Firefox 1.0PR on a Solaris system I checked out > > http://www.python.org/dev/doc/devel/lib/boolean.html > > There are no left, right or top borders. A PNG is at That's right. I liked that better myself; fewer extra lines. The lines below the header and at the bottom of the table are slightly heavier than the other lines as well. I'm surprised that the first and last columns aren't centered, and that the heading for the second column is. I'll need to review more of the actual tables in the documents, though the tables I used are quite similar to this one. -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Thu Nov 11 05:42:06 2004 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu Nov 11 05:42:29 2004 Subject: [Doc-SIG] Re: [Python-Dev] Re: [development doc updates] In-Reply-To: <000301c4c76d$89518400$af0189c3@oemcomputer> References: <000301c4c76d$89518400$af0189c3@oemcomputer> Message-ID: <200411102342.06528.fdrake@acm.org> On Wednesday 10 November 2004 04:37 pm, Richard Brodie wrote: > It seems to me that: > > .realtable th {text-align: inherit} is more specific than > .center {text-align: center} , > > so the second rule needs strengthening. Bingo! I need the second rule in its simple form elsewhere, but I can actually remove the first completely since I set the alignment-controlling class for all cells in a .realtable. The first of those rules was added while I was trying to make useful for column layout, but browsers haven't implemented that sufficiently to do so yet. I've tested the fix with my browsers and committed to CVS; an updated version of the documentation should be online later this evening. -Fred -- Fred L. Drake, Jr. From cben at users.sf.net Sat Nov 13 18:19:28 2004 From: cben at users.sf.net (Beni Cherniavsky) Date: Sat Nov 13 18:19:47 2004 Subject: [Doc-SIG] [development doc updates] In-Reply-To: <20041113064452.B36C518E89A@grendel.fdrake.net> References: <20041113064452.B36C518E89A@grendel.fdrake.net> Message-ID: <41964220.9060605@users.sf.net> Fred L. Drake wrote: > > - Textual navigation links on the top navigation bar have been > removed. (These are a subset of the iconic links still present.) > This is harmful for keyboard-dominated surfing which is very important for some people (think disabilities) and is just very convenient on Firefox. If there was a textual "Index" link, I could just type some prefix of "index" until it finds the link and press Enter. Same for "Contents". For "Previous"/"Up"/"Next", there are textual links at the bottom following these words so I can type "prev", press Tab to select the link and press Enter to follow it. Still, I would prefer if these words were part of the link itself (to avoid the need to press tab) and I request that textual Contents/Index links be provided as well. And it would be optimal if textual links were provided at the top, so that stray words like "index" in the text will not disturb the keyboard navigation habits. If you ask me, I would just scratch the images in favor of text but this is a matter of taste... -- "Not just a none, but the None. The definate article. The alpha and omega, unchanging and unwilling to act." --- Chris Cioffi against PEP 336 (Make None Callable) on c.l.python. From Felix.Wiemann at gmx.net Sat Nov 13 18:28:27 2004 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Sat Nov 13 18:30:15 2004 Subject: [Doc-SIG] Re: [development doc updates] References: <20041113064452.B36C518E89A@grendel.fdrake.net> <41964220.9060605@users.sf.net> Message-ID: <87y8h5bqv8.fsf@news2.ososo.de> Beni Cherniavsky wrote: > If you ask me, I would just scratch the images in favor of text I agree. I don't find the icons particularly useful either and enjoy keyboard navigation, too. -- When replying to my email address, please ensure that the mail header contains 'Felix Wiemann'. http://www.ososo.de/ From mike at pcblokes.com Sun Nov 14 01:38:22 2004 From: mike at pcblokes.com (Michael Foord) Date: Sun Nov 14 01:24:02 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <87y8h5bqv8.fsf@news2.ososo.de> References: <20041113064452.B36C518E89A@grendel.fdrake.net> <41964220.9060605@users.sf.net> <87y8h5bqv8.fsf@news2.ososo.de> Message-ID: <4196A8FE.2060805@pcblokes.com> Felix Wiemann wrote: >Beni Cherniavsky wrote: > > > >>If you ask me, I would just scratch the images in favor of text >> >> > >I agree. I don't find the icons particularly useful either and enjoy >keyboard navigation, too. > > > Sorry to disagree - but I like the images. Regards, Fuzzyman From aahz at pythoncraft.com Sun Nov 14 01:27:19 2004 From: aahz at pythoncraft.com (Aahz) Date: Sun Nov 14 01:27:22 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <87y8h5bqv8.fsf@news2.ososo.de> References: <20041113064452.B36C518E89A@grendel.fdrake.net> <41964220.9060605@users.sf.net> <87y8h5bqv8.fsf@news2.ososo.de> Message-ID: <20041114002719.GA10095@panix.com> On Sat, Nov 13, 2004, Felix Wiemann wrote: > Beni Cherniavsky wrote: >> >> If you ask me, I would just scratch the images in favor of text > > I agree. I don't find the icons particularly useful either and enjoy > keyboard navigation, too. +1 Actually, +1000, but y'all knew that. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ WiFi is the SCSI of the 21st Century -- there are fundamental technical reasons for sacrificing a goat. (with no apologies to John Woods) From jlg at dds.nl Wed Nov 17 10:26:46 2004 From: jlg at dds.nl (Johannes Gijsbers) Date: Thu Nov 18 09:44:13 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <20041113064452.B36C518E89A@grendel.fdrake.net> References: <20041113064452.B36C518E89A@grendel.fdrake.net> Message-ID: <20041117092646.GA7603@surfboy> [please CC, I am not subscribed] On Sat, Nov 13, 2004 at 01:44:52AM -0500, Fred L. Drake wrote: > - All navigation icons are now on the left side. > > - The document title is pushed all the way to the right. Shouldn't these two be the other way around? It feels rather unnatural to have the document title on the right for someone who's grown up reading left-to-right like me. I would also link to see a link to the Python Documentation Index in the upper left corner. This is a bit of a standard, and even though I've been using the Python docs for a couple of years, I still frequently find myself looking for the non-existent link to the index. As Jakob Nielsen likes to say, "People spend most of their time on *other* websites". So, to summarize, I would like to see the navbar become like this: "Python Documentation > Python Library Reference " > - Some of the spaces between page elements have been reduced slightly. This is about the 'letter-spacing: -x' declarations on the tt and .keyword selectors, I think? If so, please take them out. They're far too small under Firefox 1.0 + Bitstream Vera Sans Mono, to the point where there's no space between an expression and a word [1]. IE renders this better, but I suspect that this is just because under CSS1 "Browsers may treat any value of this property as if it was set to 'normal.'" [2]. The other changes, I like them a lot. Cheers, Johannes [1] E.g.: http://www.python.org/dev/doc/newstyle/lib/boolean.html [2] http://www.blooberry.com/indexdot/css/properties/text/letterspace.htm From fdrake at acm.org Thu Nov 18 16:56:00 2004 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu Nov 18 16:56:07 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <20041117092646.GA7603@surfboy> References: <20041113064452.B36C518E89A@grendel.fdrake.net> <20041117092646.GA7603@surfboy> Message-ID: <200411181056.00176.fdrake@acm.org> On Wednesday 17 November 2004 04:26 am, Johannes Gijsbers wrote: > > - The document title is pushed all the way to the right. > > Shouldn't these two be the other way around? It feels rather unnatural > to have the document title on the right for someone who's grown up > reading left-to-right like me. The idea would be that the first things on the page would be the navigation links, with "Next" (as the presumably most-used) being the first. Some of these links were always in the lead position. Having the title in the page head is more like the header on pages in a book; it's there for reference if you need it. The title page still has the title big and centered. > I would also link to see a link to the Python Documentation Index in the > upper left corner. This is a bit of a standard, and even though I've > been using the Python docs for a couple of years, I still frequently That would be nice. I've been loathe to add more links, simply because more links requires more real-estate, that that something people haven't wanted to give up in the past. (I remember the reaction when I made the top navigation stay in the browser window even as the user scrolled down; people wanted the screen real-estate for content so they could make the window small enough to show next to their editor.) You can use the "Up" link to move out of the specific documents to the documentation index. > find myself looking for the non-existent link to the index. As Jakob > Nielsen likes to say, "People spend most of their time on *other* > websites". > > So, to summarize, I would like to see the navbar become like this: > > "Python Documentation > Python Library Reference " I'll think about how to get these links in there. It took me a moment to realize that you meant "the list of documents" rather than "the index of the current document." > > - Some of the spaces between page elements have been reduced slightly. > > This is about the 'letter-spacing: -x' declarations on the tt and > .keyword selectors, I think? If so, please take them out. They're far I've removed the two attempts to control letter spacing; this is just too font-specific to keep. The online version includes this change. But the comment about page elements was actually about the spacing between the navigation icons and horizontal rules; there's simply less empty space there in the new style (very intentionally, to support the less-space-spent-on-navigation idea). -Fred -- Fred L. Drake, Jr. From fdrake at acm.org Thu Nov 18 17:01:19 2004 From: fdrake at acm.org (Fred L. Drake, Jr.) Date: Thu Nov 18 17:01:27 2004 Subject: [Doc-SIG] Commentary on iconic versus text links Message-ID: <200411181101.19983.fdrake@acm.org> I've written up a few comments on the recent discussion of iconic and text links in navigation. http://starship.python.net/~fdrake/nb/nb.cgi/ Feel free to discuss here if you like. -Fred -- Fred L. Drake, Jr. From u_schlaepfer at bluewin.ch Thu Nov 18 22:15:53 2004 From: u_schlaepfer at bluewin.ch (Ueli =?ISO-8859-1?B?U2NobORwZmVy?=) Date: Thu Nov 18 22:16:05 2004 Subject: [Doc-SIG] Re: [development doc updates] In-Reply-To: <200411181056.00176.fdrake@acm.org> References: <20041113064452.B36C518E89A@grendel.fdrake.net> <20041117092646.GA7603@surfboy> <200411181056.00176.fdrake@acm.org> Message-ID: <20041118221553.29bf602f.u_schlaepfer@bluewin.ch> On Thu, 18 Nov 2004 10:56:00 -0500 "Fred L. Drake, Jr." wrote: [...] > > The idea would be that the first things on the page would be the navigation > links, with "Next" (as the presumably most-used) being the first. Some of > these links were always in the lead position. > [...] > > You can use the "Up" link to move out of the specific documents to the > documentation index. I've tried this, and found one thing quite annoying in a redesign that I liked at first: When one reaches the top level of *current* document, the "previous" icon (which is on the far left) disappears, shifting all others by one icon width to the left. To get to the Documentation Index (i.e. the list of documents), I have to follow that shift with the mouse, or I'll keep cycling through the document. I suggest making this an empty space on the top level pages and any page that doesn't have a "Previous" button. It's a small sacrifice of screen real estate which would IMHO far outweigh the gain in usability. Thanks, Ueli From Felix.Wiemann at gmx.net Fri Nov 19 19:52:46 2004 From: Felix.Wiemann at gmx.net (Felix Wiemann) Date: Fri Nov 19 19:52:31 2004 Subject: [Doc-SIG] Re: Commentary on iconic versus text links References: <200411181101.19983.fdrake@acm.org> Message-ID: <87sm758ydd.fsf@news2.ososo.de> Fred L. Drake, Jr. wrote: > http://starship.python.net/~fdrake/nb/nb.cgi/ | [...] I couldn't actually get firefox to select those bits of the page | first when I tried using the find-in-page feature to select the link. | A link to the index in the top navigation area, indicated by the word | "Index" in a link, was not the first selection when searching for | "ind"; an occurrance later in the page was found first. | | My current expectation is that there's no way to predict the behavior | of browsers (especially on the leading edge) as regards the latest | crop of popular features. Firefox (0.10.1 here) (and Mozilla too, I guess) should always find text starting at the top. You may get different behavior after scrolling, or due to one of the numerous bugs in the Mozilla browsers, but in general I think the behavior can be considered predictable. -- When replying to my email address, please ensure that the mail header contains 'Felix Wiemann'. http://www.ososo.de/