Mailman 3 May 2008 - Doc-SIG

development docs waste a lot of horizontal space
by Forest June 19, 2008

June 19, 2008

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.

2 2

Re: [Doc-SIG] [Python-Dev] Finishing up PEP 3108
by Steve Holden May 31, 2008

May 31, 2008

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/

1 0

FAQ
by gagsl-py3＠yahoo.com.ar May 13, 2008

May 13, 2008

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

2 2