From fuzzyman at voidspace.org.uk Sun Jun 15 15:39:24 2008 From: fuzzyman at voidspace.org.uk (Michael Foord) Date: Sun, 15 Jun 2008 14:39:24 +0100 Subject: [Doc-SIG] Python in the Browser: Interactive interpreter in the browser for documentation and tutorials Message-ID: <48551B8C.4050909@voidspace.org.uk> Hello all, I thought you might be interested in my latest project as it could be very useful for providing live examples for documentation and tutorials. I've setup a project page for "Python in the Browser", an interactive Python interpreter that runs in an HTML textarea. http://code.google.com/p/pythoninthebrowser/ There's no download yet, but I have checked in the current code. "Python in the Browser" is an interactive Python interpreter that runs in the browser, using Silverlight 2 and IronPython?. This is ideal for tutorials and documentation, where example Python code can actually be tried in the browser. It requires Silverlight 2 Beta 2, and the Python version is 2.5. The interpreter runs in an HTML textarea, with Javascript that communicates with Silverlight and prevents you deleting text from the console except after the interactive prompt. Target browsers are Firefox 2 & 3, Safari and IE 7. (Although reports on compatibility with other browsers welcomed.) Currently it 'works' but is at an early stage of development. The project is a combination of IronPython? (for the interpreter loop), Javascript (for the 'console behaviour' in the textarea) and C# (as a helper to call into Silverlight from Javascript). I've entered the known issues at: http://code.google.com/p/pythoninthebrowser/issues/list There is a live example at: http://www.voidspace.org.uk/ironpython/silverlight-console/console.html I'm not sure how quickly I will be able to develop this (I have a book to finish!), but it should be very easy to knock out a couple of the simpler issues quickly. If you want to contribute then please post patches to the issue tracker. Michael Foord -- http://www.ironpythoninaction.com/ http://www.theotherdelia.co.uk/ http://www.voidspace.org.uk/ http://www.ironpython.info/ http://www.resolverhacks.net/ From list8a.forest at tibit.com Thu Jun 19 18:56:22 2008 From: list8a.forest at tibit.com (Forest) Date: Thu, 19 Jun 2008 09:56:22 -0700 (PDT) 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: <8007.75.55.199.5.1213894582.squirrel@webmail.sonic.net> This issue is now in the tracker: http://bugs.python.org/issue3143 On Wed, May 7, 2008 3:24 pm, Forest wrote: > 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 amk at amk.ca Fri Jun 20 14:41:40 2008 From: amk at amk.ca (A.M. Kuchling) Date: Fri, 20 Jun 2008 08:41:40 -0400 Subject: [Doc-SIG] Proposal: don't nest optional brackets Message-ID: <20080620124140.GA6015@amk-desktop.matrixgroup.net> To show a series of optional parameters, currently we nest square brackets. http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings warnings.filterwarnings(action[, message[, category[, module[, lineno[, append]]]]]) My proposal is that we drop the nesting and write this as: warnings.filterwarnings(action [, message, category, module, lineno, append]) Currently the stylesheets make the brackets very big and dark, so I've also added a space before the bracket. This change means we'd lose the ability to show when two optional arguments must be supplied at the same time, which could currently be written like this: warnings.filterwarnings(action[, message, category[, module]]) In this hypothetical example, if you supply 'message' you must also supply 'category'. But I think that for most functions, you can supply each optional argument or not; you rarely need to supply two optional arguments that are tied in this way, and we can handle such cases by adding a sentence such as "Both message and category parameters must be supplied." A few places (difflib, doctest, probably others) use this format: .. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) It's better than the nested version -- at least it avoids the ]]]]]) at the end -- but I think having a single set of square brackets also works and reduces the symbolic noise further. .. function:: context_diff(a, b [, fromfile, tofile, fromfiledate, tofiledate, n, lineterm]) The brackets are large enough that I think this would still be quite readable; it doesn't seem likely that readers will miss that these parameters are optional. What does everyone think? --amk From p.f.moore at gmail.com Fri Jun 20 14:51:36 2008 From: p.f.moore at gmail.com (Paul Moore) Date: Fri, 20 Jun 2008 13:51:36 +0100 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: <20080620124140.GA6015@amk-desktop.matrixgroup.net> References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: <79990c6b0806200551m11475416iaf16a23452f550dc@mail.gmail.com> On 20/06/2008, A.M. Kuchling wrote: > My proposal is that we drop the nesting and write this as: > > warnings.filterwarnings(action [, message, category, module, lineno, append]) [...] > What does everyone think? Sounds OK to me - this is documentation, not a formal spec, so readability is more important than absolute precision. I wonder - what do other projects do? Consistency with common practice is likely to help readability, as well. Paul. From g.brandl at gmx.net Sun Jun 22 13:36:55 2008 From: g.brandl at gmx.net (Georg Brandl) Date: Sun, 22 Jun 2008 13:36:55 +0200 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: <20080620124140.GA6015@amk-desktop.matrixgroup.net> References: <20080620124140.GA6015@amk-desktop.matrixgroup.net> Message-ID: A.M. Kuchling schrieb: > To show a series of optional parameters, currently we nest square > brackets. > > http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings > > warnings.filterwarnings(action[, message[, category[, module[, > lineno[, append]]]]]) > > My proposal is that we drop the nesting and write this as: > > warnings.filterwarnings(action [, message, category, module, lineno, append]) > > Currently the stylesheets make the brackets very big and dark, so I've > also added a space before the bracket. Which will be ignored by the signature parser :) > This change means we'd lose the ability to show when two optional > arguments must be supplied at the same time, which could currently be > written like this: > > warnings.filterwarnings(action[, message, category[, module]]) > > In this hypothetical example, if you supply 'message' you must also > supply 'category'. But I think that for most functions, you can > supply each optional argument or not; you rarely need to supply two > optional arguments that are tied in this way, and we can handle such > cases by adding a sentence such as "Both message and category parameters > must be supplied." That's reasonable. I can't remember if there's a function like this anywhere (with only the signature as a sign of this calling requirement). > A few places (difflib, doctest, probably others) use this format: > > ... function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm]) > > It's better than the nested version -- at least it avoids the ]]]]]) > at the end -- but I think having a single set of square brackets also > works and reduces the symbolic noise further. > > ... function:: context_diff(a, b [, fromfile, tofile, fromfiledate, tofiledate, n, lineterm]) > > The brackets are large enough that I think this would still be quite > readable; it doesn't seem likely that readers will miss that these > parameters are optional. > > What does everyone think? I'm +0. I'd like to hear Fred's opinion since (I guess) he introduced the nested bracket notation. If he's okay with it, I'll write a script that converts the signatures in the whole documentation. cheers, Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. From mark at msapiro.net Mon Jun 23 05:10:09 2008 From: mark at msapiro.net (Mark Sapiro) Date: Sun, 22 Jun 2008 20:10:09 -0700 Subject: [Doc-SIG] Proposal: don't nest optional brackets In-Reply-To: Message-ID: Georg Brandl wrote: >A.M. Kuchling schrieb: >> To show a series of optional parameters, currently we nest square >> brackets. >> >> http://docs.python.org/dev/library/warnings.html#warnings.filterwarnings >> >> warnings.filterwarnings(action[, message[, category[, module[, >> lineno[, append]]]]]) >> >> My proposal is that we drop the nesting and write this as: >> >> warnings.filterwarnings(action [, message, category, module, lineno, append]) [...] >> What does everyone think? > >I'm +0. I'd like to hear Fred's opinion since (I guess) he introduced the >nested bracket notation. If he's okay with it, I'll write a script that >converts the signatures in the whole documentation. The nested bracket notation has been around for a very long time. It is used primarily to indicate positional arguments, any of which may logically be omitted, but all those to the left of the desired argument must be specified because of the positional nature of the arguments. Of course, the Pythonic thing is to specify just the desired arguments as keyword arguments and allow the rest to assume their defaults. I think that the strict notation to express this might be something like warnings.filterwarnings(action[, message=][, category=][, module=][, lineno=][, append]) but perhaps warnings.filterwarnings(action[, message, category, module, lineno, append]) is understood in a Python context to mean the same thing. +0 -- Mark Sapiro The highway is for gamblers, San Francisco Bay Area, California better use your sense - B. Dylan From grubert at users.sourceforge.net Thu Jun 26 09:10:09 2008 From: grubert at users.sourceforge.net (grubert at users.sourceforge.net) Date: Thu, 26 Jun 2008 09:10:09 +0200 (CEST) Subject: [Doc-SIG] Docutils 0.5 released Message-ID: Short list of changes * Python2.1 support was dropped, as are Netscape0.4 compromises in the HTML writer. * Enhanced citation support and literal-block parametrization for LaTeX2e writer. * The PEP writer supports new python.org website structure and pep2pyramid.py. * New OO API for directives. Hebrew (and possibly other language) mappings. Configuration files are now assumed and required to be UTF-8-encoded. Some templates and enhanced emacs support. download: http://prdownloads.sourceforge.net/docutils/docutils-0.5.tar.gz?download Changelog: http://docutils.sourceforge.net/0.5/HISTORY.html -- From aahz at pythoncraft.com Thu Jun 26 16:10:00 2008 From: aahz at pythoncraft.com (Aahz) Date: Thu, 26 Jun 2008 07:10:00 -0700 Subject: [Doc-SIG] Docutils 0.5 released In-Reply-To: References: Message-ID: <20080626140959.GB19360@panix.com> On Thu, Jun 26, 2008, grubert at users.sourceforge.net wrote: > > [...] Many congratulations! -- Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/ "as long as we like the same operating system, things are cool." --piranha