Mailman 3 November 2004 - Doc-SIG

Commentary on iconic versus text links
by Fred L. Drake, Jr. Nov. 19, 2004

Nov. 19, 2004

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. <fdrake at acm.org>

2 1

Re: [development doc updates]
by Johannes Gijsbers Nov. 18, 2004

Nov. 18, 2004

[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 <navigation icons>" > - 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

3 2

Re: [Doc-SIG] [development doc updates]
by Beni Cherniavsky Nov. 14, 2004

Nov. 14, 2004

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.

4 3

Re: [Python-Dev] Re: [development doc updates]
by Fred L. Drake, Jr. Nov. 11, 2004

Nov. 11, 2004

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 <col> 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. <fdrake at acm.org>

1 0

Re: [development doc updates]
by Fred L. Drake, Jr. Nov. 10, 2004

Nov. 10, 2004

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. <fdrake at acm.org>

1 0

Re: [Doc-SIG] [development doc updates]
by Michael Foord Nov. 10, 2004

Nov. 10, 2004

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(a)python.org >http://mail.python.org/mailman/listinfo/doc-sig > > > > >

2 1

Re: [Doc-SIG] [development doc updates]
by Voidspace Nov. 3, 2004

Nov. 3, 2004

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(a)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

2 2