From list8a.forest at tibit.com Thu May 8 00:24:11 2008 From: list8a.forest at tibit.com (Forest) Date: Wed, 7 May 2008 15:24:11 -0700 (PDT) Subject: [Doc-SIG] development docs waste a lot of horizontal space Message-ID: <21772.75.55.199.5.1210199051.squirrel@webmail.sonic.net> Hi, folks. I was just browsing the development docs, and noticed that the new left-side navigation bar wastes a lot of horizontal space on the web page. It fills nearly a third of my browser window (at its usual size) with useless blank space, at the expense of the pertinent information. This makes it harder to get much use out of a docs window placed next to my editor window, since I am now forced to switch active windows and/or scroll around the docs window just to read the section I'm working with. In a few cases, it leaves space for so few words per line that even the visible part of the docs actually become harder to read (especially with text justification). For comparison, here are screen shots from the old and new documentation: http://hestiafire.org/forest/img/doc25.png http://hestiafire.org/forest/img/doc26.png Is this side bar going to be present in the final release of the python 2.6 docs? I hope not. It's a significant loss in readability, IMHO. From gagsl-py3 at yahoo.com.ar Tue May 13 04:29:31 2008 From: gagsl-py3 at yahoo.com.ar (gagsl-py3 at yahoo.com.ar) Date: Mon, 12 May 2008 23:29:31 -0300 (ART) Subject: [Doc-SIG] FAQ Message-ID: <475070.67462.qm@web32803.mail.mud.yahoo.com> Hello I've noticed that the Python FAQ is somewhat old and mostly unmaintained. I would like to volunteer as a maintainer, but strangely I can't find the FAQ itself in the documentation package; moreover, I can't find it *anywhere* in the svn tree... How can I help to maintain the FAQ? And where *IS* it? -- Gabriel Genellina Yahoo! Encuentros. Ahora encontrar pareja es mucho m?s f?cil, prob? el nuevo Yahoo! Encuentros http://yahoo.cupidovirtual.com/servlet/NewRegistration From skip at pobox.com Tue May 13 04:45:29 2008 From: skip at pobox.com (skip at pobox.com) Date: Mon, 12 May 2008 21:45:29 -0500 Subject: [Doc-SIG] FAQ In-Reply-To: <475070.67462.qm@web32803.mail.mud.yahoo.com> References: <475070.67462.qm@web32803.mail.mud.yahoo.com> Message-ID: <18473.201.492244.963984@montanaro-dyndns-org.local> Gabriel> I've noticed that the Python FAQ is somewhat old and mostly Gabriel> unmaintained. I would like to volunteer as a maintainer, but Gabriel> strangely I can't find the FAQ itself in the documentation Gabriel> package; moreover, I can't find it *anywhere* in the svn Gabriel> tree... How can I help to maintain the FAQ? And where *IS* it? Gabriel, It is in the website svn repo. Here's the repo url: svn+ssh://pydotorg at svn.python.org/trunk/beta.python.org Within that it's down this rabbit hole: % ls build/data/doc/faq/ content.ht extending gui it programming es general installed library windows I can never remember how to find it by browsing . Good thing I already have it checked out. ;-) Skip From gagsl-py3 at yahoo.com.ar Tue May 13 08:00:10 2008 From: gagsl-py3 at yahoo.com.ar (gagsl-py3 at yahoo.com.ar) Date: Tue, 13 May 2008 03:00:10 -0300 (ART) Subject: [Doc-SIG] FAQ In-Reply-To: <18473.201.492244.963984@montanaro-dyndns-org.local> Message-ID: <797424.12797.qm@web32805.mail.mud.yahoo.com> --- skip at pobox.com escribi?: > Gabriel> I've noticed that the Python FAQ is > somewhat old and mostly > Gabriel> unmaintained. I would like to volunteer > as a maintainer, but > Gabriel> strangely I can't find the FAQ itself > in the documentation > Gabriel> package; moreover, I can't find it > *anywhere* in the svn > Gabriel> tree... How can I help to maintain the > FAQ? And where *IS* it? > > Gabriel, > > It is in the website svn repo. Here's the repo url: > > > svn+ssh://pydotorg at svn.python.org/trunk/beta.python.org > > I can never remember how to find it by browsing > . > Good thing I already have it checked out. ;-) Ah, thanks! Looks like the browser interface is at: But I would never have found it there. I'd think the FAQ would have been located on the same tree as the main Python documentation, not buried inside the website contents... Yahoo! Encuentros. Ahora encontrar pareja es mucho m?s f?cil, prob? el nuevo Yahoo! Encuentros http://yahoo.cupidovirtual.com/servlet/NewRegistration From kirr at mns.spb.ru Tue May 13 09:17:30 2008 From: kirr at mns.spb.ru (Kirill Smelkov) Date: Tue, 13 May 2008 11:17:30 +0400 Subject: [Doc-SIG] development docs waste a lot of horizontal space In-Reply-To: <21772.75.55.199.5.1210199051.squirrel@webmail.sonic.net> References: <21772.75.55.199.5.1210199051.squirrel@webmail.sonic.net> Message-ID: <200805131117.30609.kirr@mns.spb.ru> ? ????????? ?? ??????? 08 ??? 2008 Forest ???????(a): > Hi, folks. > > I was just browsing the development docs, and noticed that the new > left-side navigation bar wastes a lot of horizontal space on the web page. > It fills nearly a third of my browser window (at its usual size) with > useless blank space, at the expense of the pertinent information. This > makes it harder to get much use out of a docs window placed next to my > editor window, since I am now forced to switch active windows and/or > scroll around the docs window just to read the section I'm working with. > In a few cases, it leaves space for so few words per line that even the > visible part of the docs actually become harder to read (especially with > text justification). > > For comparison, here are screen shots from the old and new documentation: > http://hestiafire.org/forest/img/doc25.png > http://hestiafire.org/forest/img/doc26.png > > Is this side bar going to be present in the final release of the python > 2.6 docs? I hope not. It's a significant loss in readability, IMHO. I'm too strongly +1 for at least to have an option to turn this sidebar off. Kirill. From steve at holdenweb.com Sat May 31 17:42:24 2008 From: steve at holdenweb.com (Steve Holden) Date: Sat, 31 May 2008 11:42:24 -0400 Subject: [Doc-SIG] [Python-Dev] Finishing up PEP 3108 In-Reply-To: References: Message-ID: <484171E0.4050204@holdenweb.com> Georg Brandl wrote: > Brett Cannon schrieb: > >>>> Issue 2873 - htmllib is slated to go, but pydoc still uses it. Then >>>> again, pydoc is busted thanks to the new doc format. >>> >>> I will try to handle this in the coming week. >>> >> >> Fred had the interesting suggestion of removing pydoc in Py3K based on >> the thinking that documentation tools like pydoc should be external to >> Python. With the docs now so easy to generate directly, should pydoc >> perhaps just be gutted to only what is needed for help() to work? > > pydoc is fine for displaying docstring help, and interactive help. > This should stay. > > Of course, it would also be nice for ``help("if")`` to work effortlessly, > which it currently only does if the generated HTML documentation is > available somewhere, which it typically isn't -- on Unix most distributions > put it in a separate package (from which pydoc won't always find it > of its own), on Windows only the CHM file is distributed and must be > decompiled to get single HTML files. > > Now that the docs are reST, the source is almost pretty enough to display > it raw, but I could also imagine a "text" writer that removes the more > obscure markup to present a casual-reader-friendly text version. > > The needed sources could then be distributed with Python -- it shouldn't > be more than about 200 kb. The versioned documentation will sometimes be available from the Internet if you want to think about using that as a fallback source. It *would* be nice if help("if") worked. It would be even handier if help(if) worked, but that's a syntax problem, and it would be a horrendous one to overcome, I suspect. regards Steve -- Steve Holden +1 571 484 6266 +1 800 494 3119 Holden Web LLC http://www.holdenweb.com/