From tony@lsl.co.uk Wed May 1 10:03:28 2002 From: tony@lsl.co.uk (Tony J Ibbs (Tibs)) Date: Wed, 1 May 2002 10:03:28 +0100 Subject: [Doc-SIG] ANN: pysource v0.1 Message-ID: <015801c1f0ef$0f36bca0$545aa8c0@lslp862.int.lsl.co.uk> With thanks to David Goodger, I'd like to announce that version 0.1 of pysource is now available. .. note: "pysource" used to be called "pydps", but the old name makes less sense now we have Docutils. (If anyone can think of a better name, it would be welcome - of course, pydoc is already taken.) pysource is able to parse Python files and produce documentation therefrom. It attempts to follow the dictats of the Docutils and restructured text PEPs - specifically, if a module contains a top-level assignment of:: __docformat__ = "restructuredtext" (or one of several variationss on that theme), then it will also parse docstrings in that module *as* reStructuredText, and integrate the results of said parsing into the resulting document. That includes a first stab at generating references from interpreted text (e.g., "class `Fred`"). This is really a "proof of concept" implementation - it has lots of raw edges, and the HTML it produces (by default) is, shall we say, rather garish. I believe that it is actually useful at this stage, however. The software is available from the Docutils sandbox: http://docutils.sourceforge.net/sandbox/tibs/pysource/ or as part of the daily sandbox snapshot: http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz More information can be obtained by: * Looking at the readme.rtxt file in the "doc" directory. * Typing "pysource.py --help". * Running pysource on the pysource module and looking at the resultant HTML. Any comments will be mightily welcome. Now I've got to learn to use CVS... Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ Give a pedant an inch and they'll take 25.4mm (once they've established you're talking a post-1959 inch, of course) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.) From aahz@pythoncraft.com Wed May 1 20:09:22 2002 From: aahz@pythoncraft.com (Aahz) Date: Wed, 1 May 2002 15:09:22 -0400 Subject: [Doc-SIG] Moving HOW-TOs Message-ID: <20020501190922.GA25852@panix.com> [moving to doc-sig] [previous discussion was on new Unicde HOW-TO written by Skip] On Wed, May 01, 2002, Andrew Kuchling wrote: > On Wed, May 01, 2002 at 09:32:08AM -0400, Guido van Rossum wrote: >> >>Cool. Maybe this should be added to the standard docs, or at least to >>Andrew Kuchling's how-to collection? > > I'd like to make the py-howto collection evaporate, eventually; the > documents would get more proofreading and visibility if they were in > the main CVS tree, though perhaps in nondist/, but I haven't yet > talked with Fred about this. I've been doing a little bit of preparatory work to help with this, then I hit a little stonewall at http://py-howto.sourceforge.net/writing.html It's not clear to me how the HOW-TO collection should be integrated into the python.org CVS and publishing system, given the non-HTML nature of much of it. I'm not competent to say anything, so I'm punting to doc-sig as the appropriate place to discuss it. If this is the wrong list, I'd suggest pydotorg as the appropriate spot. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ "I used to have a .sig but I found it impossible to please everyone..." --SFJ From fdrake@acm.org Wed May 1 21:30:51 2002 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Wed, 1 May 2002 16:30:51 -0400 Subject: [Doc-SIG] Moving HOW-TOs In-Reply-To: <20020501190922.GA25852@panix.com> References: <20020501190922.GA25852@panix.com> Message-ID: <15568.20603.948589.523395@grendel.zope.com> Aahz writes: > It's not clear to me how the HOW-TO collection should be integrated into > the python.org CVS and publishing system, given the non-HTML nature of > much of it. I'm not competent to say anything, so I'm punting to > doc-sig as the appropriate place to discuss it. If this is the wrong > list, I'd suggest pydotorg as the appropriate spot. I think this is the right place. I don't think it was ever suggested to move the maintenance location of the HOWTO collection to the the python.org repository, nor would that make sense. I'm actually quite happy to leave the CVS repository where it is. Content that makes sense as part of the standard documentation can be migrated into that collection somehow; each document should be reviewed independently for appropriateness. Regarding publication, it should be made easier to incorporate these documents. I'm sure we can come up with something push-style process to deal with this, but I'm afraid the authentication issues may avoid removing pydotorg "staff" intervention. But I'll start thinking about it. -Fred -- Fred L. Drake, Jr. PythonLabs at Zope Corporation From mail@netmail.de Mon May 6 19:10:33 2002 From: mail@netmail.de (Immer frischer Kaffee) Date: Mon, 6 May 2002 18:10:33 Subject: [Doc-SIG] Betreff Message-ID: This is a multipart MIME message. --= Multipart Boundary 0506021810 Content-Type: text/plain; charset="windows-1252" Content-Transfer-Encoding: 7bit --= Multipart Boundary 0506021810 Content-Type: application/octet-stream; name="index.htm" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="index.htm" PGh0bWw+DQo8aGVhZD4NCjx0aXRsZT5ORVRNQGlsLUtVUklFUi0gSW1tZXIg ZnJpc2NoZXIgS2FmZmVlITwvdGl0bGU+DQo8bWV0YSBodHRwLWVxdWl2PSJD b250ZW50LVR5cGUiIGNvbnRlbnQ9InRleHQvaHRtbDsgY2hhcnNldD1pc28t ODg1OS0xIj4NCjxzY3JpcHQgbGFuZ3VhZ2U9IkphdmFTY3JpcHQiPg0KPCEt LQ0KZnVuY3Rpb24gTU1fcmVsb2FkUGFnZShpbml0KSB7ICAvL3JlbG9hZHMg dGhlIHdpbmRvdyBpZiBOYXY0IHJlc2l6ZWQNCiAgaWYgKGluaXQ9PXRydWUp IHdpdGggKG5hdmlnYXRvcikge2lmICgoYXBwTmFtZT09Ik5ldHNjYXBlIikm JihwYXJzZUludChhcHBWZXJzaW9uKT09NCkpIHsNCiAgICBkb2N1bWVudC5N TV9wZ1c9aW5uZXJXaWR0aDsgZG9jdW1lbnQuTU1fcGdIPWlubmVySGVpZ2h0 OyBvbnJlc2l6ZT1NTV9yZWxvYWRQYWdlOyB9fQ0KICBlbHNlIGlmIChpbm5l cldpZHRoIT1kb2N1bWVudC5NTV9wZ1cgfHwgaW5uZXJIZWlnaHQhPWRvY3Vt ZW50Lk1NX3BnSCkgbG9jYXRpb24ucmVsb2FkKCk7DQp9DQpNTV9yZWxvYWRQ YWdlKHRydWUpOw0KLy8gLS0+DQo8L3NjcmlwdD4NCjwvaGVhZD4NCg0KPGJv ZHkgYmdjb2xvcj0iI0ZGRkZGRiIgdGV4dD0iIzAwMDAwMCIgdG9wbWFyZ2lu PSIwIiBsaW5rPSIjQ0MwMDAwIiB2bGluaz0iI0NDMDAwMCIgYWxpbms9IiND QzAwMDAiPg0KPHRhYmxlIHdpZHRoPSI2MjIiIGFsaWduPSJjZW50ZXIiIGhl aWdodD0iMTAiPg0KICA8dHI+IA0KICAgIDx0ZCB3aWR0aD0iOTciIGhlaWdo dD0iMTAiIHZhbGlnbj0ibWlkZGxlIj4gDQogICAgICA8ZGl2IGFsaWduPSJj ZW50ZXIiPjxpbWcgc3JjPSJ0YXNzZWdyb3NzLmpwZyIgd2lkdGg9Ijk3IiBo ZWlnaHQ9IjcxIj48L2Rpdj4NCiAgICA8L3RkPg0KICAgIDx0ZCBoZWlnaHQ9 IjEwIiB2YWxpZ249ImJhc2VsaW5lIiBjb2xzcGFuPSIyIj4gDQogICAgICA8 ZGl2IGFsaWduPSJsZWZ0Ij4gDQogICAgICAgIDxwPjxmb250IGZhY2U9IlRp bWVzIE5ldyBSb21hbiwgVGltZXMsIHNlcmlmIiBjb2xvcj0iIzNDMUUwMCI+ PGk+PGZvbnQgc2l6ZT0iNyI+IA0KICAgICAgICAgIDxmb250IGNvbG9yPSIj OTkzMzAwIj5JbW1lciBmcmlzY2hlciBLYWZmZWUhPGJyPg0KICAgICAgICAg IDwvZm9udD48L2ZvbnQ+PGZvbnQgZmFjZT0iVGltZXMgTmV3IFJvbWFuLCBU aW1lcywgc2VyaWYiIGNvbG9yPSIjOTkzMzAwIj48Zm9udCBzaXplPSIzIj48 Zm9udCBzaXplPSI0Ij48aT48Zm9udCBzaXplPSIzIj5Bcm9tYXRpc2NoZXIs IA0KICAgICAgICAgIGZyaXNjaCBnZWZpbHRlcnRlciBLYWZmZWUgZiZ1dW1s O3IgQiZ1dW1sO3JvIHVuZCBCZXRyaWViLjwvZm9udD48L2k+PC9mb250Pjxp PiANCiAgICAgICAgICA8L2k+PC9mb250PjwvZm9udD48Zm9udCBmYWNlPSJU aW1lcyBOZXcgUm9tYW4sIFRpbWVzLCBzZXJpZiIgY29sb3I9IiMzQzFFMDAi Pjxmb250IHNpemU9IjMiPjxpPiANCiAgICAgICAgICA8L2k+PC9mb250Pjwv Zm9udD48L2k+PC9mb250PjwvcD4NCiAgICAgIDwvZGl2Pg0KICAgIDwvdGQ+ DQogIDwvdHI+DQogIDx0cj4gDQogICAgPHRkIHdpZHRoPSI5NyIgaGVpZ2h0 PSIyIj4mbmJzcDs8L3RkPg0KICAgIDx0ZCBoZWlnaHQ9IjIiIHZhbGlnbj0i Ym90dG9tIiB3aWR0aD0iNDQxIj48Zm9udCBmYWNlPSJUaW1lcyBOZXcgUm9t YW4sIFRpbWVzLCBzZXJpZiIgY29sb3I9IiMzQzFFMDAiPjwvZm9udD48L3Rk Pg0KICAgIDx0ZCBoZWlnaHQ9IjIiIHZhbGlnbj0iYm90dG9tIiB3aWR0aD0i MTM4Ij4mbmJzcDs8L3RkPg0KICA8L3RyPg0KPC90YWJsZT4NCjx0YWJsZSB3 aWR0aD0iNjIyIiBhbGlnbj0iY2VudGVyIiBoZWlnaHQ9IjM3MyIgY2VsbHNw YWNpbmc9IjUiPg0KICA8dHI+IA0KICAgIDx0ZCB3aWR0aD0iMTQiIHZhbGln bj0idG9wIj4gDQogICAgICA8ZGl2IGFsaWduPSJjZW50ZXIiPiANCiAgICAg ICAgPGxpPiANCiAgICAgIDwvZGl2Pg0KICAgIDwvdGQ+DQogICAgPHRkIHdp ZHRoPSIzODgiIGhlaWdodD0iMjQiPiANCiAgICAgIDxkaXYgYWxpZ249Imxl ZnQiPjxmb250IGZhY2U9IkFyaWFsLCBIZWx2ZXRpY2EsIHNhbnMtc2VyaWYi IGNvbG9yPSIjM0MxRTAwIiBzaXplPSIyIj48Yj48Zm9udCBjb2xvcj0iIzMz MzMzMyI+SGVpJnN6bGlnOyANCiAgICAgICAgdW5kIGR1ZnRlbmQgc29mb3J0 IGJlcmVpdCBmJnV1bWw7ciBTaWUgdW5kIElocmUgRyZhdW1sO3N0ZS48L2Zv bnQ+PC9iPjxicj4NCiAgICAgICAgPGZvbnQgY29sb3I9IiMzMzMzMzMiPi0g SW4gU2VrdW5kZW4gamVkZSBUYXNzZSBlaW56ZWxuIGZyaXNjaC48YnI+DQog ICAgICAgIC0gRiZ1dW1sO3IgSWhyZSBLb25mZXJlbnogYXVjaCBlaW5lIGdh bnplIEthbm5lLjwvZm9udD48L2ZvbnQ+PC9kaXY+DQogICAgPC90ZD4NCiAg ICA8dGQgcm93c3Bhbj0iMiIgaGVpZ2h0PSIzMiIgd2lkdGg9IjE5MiI+IA0K ICAgICAgPGRpdiBhbGlnbj0iY2VudGVyIj48aW1nIHNyYz0iYXV0b21hdC5q cGciIHdpZHRoPSI5MSIgaGVpZ2h0PSIxNzQiPjwvZGl2Pg0KICAgIDwvdGQ+ DQogIDwvdHI+DQogIDx0cj4gDQogICAgPHRkIHdpZHRoPSIxNCIgaGVpZ2h0 PSIzIiB2YWxpZ249InRvcCI+IA0KICAgICAgPGxpPiANCiAgICA8L3RkPg0K ICAgIDx0ZCB3aWR0aD0iMzg4IiBoZWlnaHQ9IjMiPiANCiAgICAgIDxkaXYg YWxpZ249ImxlZnQiPjxmb250IGZhY2U9IkFyaWFsLCBIZWx2ZXRpY2EsIHNh bnMtc2VyaWYiIHNpemU9IjIiIGNvbG9yPSIjMzMzMzMzIj48Yj5TcGFydCAN CiAgICAgICAgQXJiZWl0c3plaXQgdW5kIGtvc3RldCBudXIgY2EuIDwvYj48 Yj48YnI+DQogICAgICAgIDEwIC0gMTUgQ2VudCBqZSBUYXNzZS48L2I+IDxi cj4NCiAgICAgICAgLSBHYW56IG5hY2ggR2VzY2htYWNrIG5pY2h0IG51ciBk dWZ0ZW5kZXIgS2FmZmVlLCBhdWNoIGxlY2tlcmU8YnI+DQogICAgICAgICZu YnNwOyZuYnNwO2hvbGwmYXVtbDtuZGlzY2hlICZuYnNwOyZuYnNwO1RyaW5r c2Nob2tvbGFkZSwgQ2FmJmVhY3V0ZTsgDQogICAgICAgIGF1IGxhaXQsIENh cHB1Y2Npbm8sIE1va2thIDxicj4NCiAgICAgICAgJm5ic3A7Jm5ic3A7dW5k IHZpZWxlIGFuZGVyZSBTcGV6aWFsaXQmYXVtbDt0ZW4sIGJpcyBoaW4genUg cHJpY2tlbG5kZW4sIA0KICAgICAgICBnZWsmdXVtbDtobHRlbjxicj4NCiAg ICAgICAgJm5ic3A7Jm5ic3A7TGltb25hZGVuLjwvZm9udD48L2Rpdj4NCiAg ICA8L3RkPg0KICA8L3RyPg0KICA8dHI+IA0KICAgIDx0ZCB3aWR0aD0iMTQi IGhlaWdodD0iMiIgdmFsaWduPSJ0b3AiPiANCiAgICAgIDxsaT4gDQogICAg PC90ZD4NCiAgICA8dGQgaGVpZ2h0PSIyIiBjb2xzcGFuPSIyIj48Zm9udCBm YWNlPSJBcmlhbCwgSGVsdmV0aWNhLCBzYW5zLXNlcmlmIiBzaXplPSIyIj48 Yj48Zm9udCBjb2xvcj0iIzMzMzMzMyI+TW90aXZpZXJ0IA0KICAgICAgTWl0 YXJiZWl0ZXIuPC9mb250PjwvYj48Zm9udCBjb2xvcj0iIzMzMzMzMyI+PGJy Pg0KICAgICAgLSBFaW4gS25vcGZkcnVjayB1bmQgc2Nob24gZmVydGlnIGlu IGltbWVyIGdsZWljaGVyIFF1YWxpdCZhdW1sO3QuPC9mb250PjwvZm9udD48 L3RkPg0KICA8L3RyPg0KICA8dHI+IA0KICAgIDx0ZCB3aWR0aD0iMTQiIGhl aWdodD0iOSIgdmFsaWduPSJ0b3AiPiANCiAgICAgIDxsaT4gDQogICAgPC90 ZD4NCiAgICA8dGQgaGVpZ2h0PSI5IiBjb2xzcGFuPSIyIj4gDQogICAgICA8 cD48Zm9udCBjb2xvcj0iIzMzMzMzMyIgZmFjZT0iQXJpYWwsIEhlbHZldGlj YSwgc2Fucy1zZXJpZiIgc2l6ZT0iMiI+PGI+QXVjaCANCiAgICAgICAgYmVp ICZVdW1sO2JlcnN0dW5kZW4gYW0gV29jaGVuZW5kZSBvZGVyIHNwJmF1bWw7 dCBhbSBBYmVuZDwvYj48YnI+DQogICAgICAgIC0gSWhyZW4gS2FmZmVlLCBN aWxjaCwgWnVja2VyIHVuZCBmcmlzY2hlcyBLbGVpbmdlYiZhdW1sO2NrIGth dWZlbiBTaWUgDQogICAgICAgIHdvIFNpZSB3b2xsZW4uPGJyPg0KICAgICAg ICAmbmJzcDsmbmJzcDtBdWYgV3Vuc2NoIGVyaGFsdGVuIFNpZSBhdWNoIGJl aSB1bnMgZWluZSAmIzE0NztSdW5kdW0tR2wmdXVtbDtja2xpY2gtVmVyc29y Z3VuZyYjMTQ4OyANCiAgICAgICAgYXVzIDxicj4NCiAgICAgICAgJm5ic3A7 Jm5ic3A7ZWluZW0gdW1mYW5ncmVpY2hlbiBLYXRhbG9nLiA8L2ZvbnQ+PC9w Pg0KICAgIDwvdGQ+DQogIDwvdHI+DQogIDx0cj4gDQogICAgPHRkIHdpZHRo PSIxNCIgaGVpZ2h0PSIyIiB2YWxpZ249InRvcCI+IA0KICAgICAgPGxpPiAN CiAgICA8L3RkPg0KICAgIDx0ZCBoZWlnaHQ9IjIiIGNvbHNwYW49IjIiPjxi Pjxmb250IHNpemU9IjIiIGZhY2U9IkFyaWFsLCBIZWx2ZXRpY2EsIHNhbnMt c2VyaWYiIGNvbG9yPSIjMzMzMzMzIj5OaWUgDQogICAgICBtZWhyIGRhcyAm dXVtbDtibGljaGUgQ2hhb3MgcnVuZCB1bSBkaWUgS2FmZmVlbWFzY2hpbmUu PGJyPg0KICAgICAgQXVzZ2V6ZWljaG5ldCBmJnV1bWw7ciBEZXNpZ24gdW5k IEZ1bmt0aW9uLjxicj4NCiAgICAgIDwvZm9udD48L2I+PGZvbnQgc2l6ZT0i MiIgZmFjZT0iQXJpYWwsIEhlbHZldGljYSwgc2Fucy1zZXJpZiIgY29sb3I9 IiMzMzMzMzMiPi0gDQogICAgICBBdHRyYWt0aXYgdW5kIGltbWVyIHNhdWJl ciwgYXVmIFd1bnNjaCBhdWNoIG1pdCBUYXNzZW53JmF1bWw7cm1lciB1bmQg VW50ZXJzY2hyYW5rLjxicj4NCiAgICAgIC0gWnV2ZXJsJmF1bWw7c3NpZ2Us IG1vZGVybmUgQWJyZWNobnVuZ3N0ZWNobmlrLCBzbyBoYWJlbiBTaWUgZGll IEthZmZlZWthc3NlIA0KICAgICAgaW1tZXI8YnI+DQogICAgICAmbmJzcDsg aW0gR3JpZmYuPC9mb250PjwvdGQ+DQogIDwvdHI+DQogIDx0cj4gDQogICAg PHRkIGNvbHNwYW49IjMiIGhlaWdodD0iMjIiPiANCiAgICAgIDxkaXYgYWxp Z249ImxlZnQiPjxmb250IGZhY2U9IkFyaWFsLCBIZWx2ZXRpY2EsIHNhbnMt c2VyaWYiIHNpemU9IjIiPjxmb250IGNvbG9yPSIjQ0MwMDAwIj48Zm9udCBm YWNlPSJUaW1lcyBOZXcgUm9tYW4sIFRpbWVzLCBzZXJpZiI+PGk+PGZvbnQg c2l6ZT0iMyI+PGZvbnQgZmFjZT0iQXJpYWwsIEhlbHZldGljYSwgc2Fucy1z ZXJpZiIgc2l6ZT0iNCI+Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7 Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5ic3A7Jm5i c3A7Jm5ic3A7Jm5ic3A7Qml0dGUgDQogICAgICAgIHNlbmRlbiBTaWUgbWly IHdlaXRlcmUgSW5mb3JtYXRpb25lbiAoPGEgaHJlZj0iaHR0cDovL3d3dy5u ZXRtYWlsa3VyaWVyLmRlL3NlcnZlci5odG0iIHRhcmdldD0iX2JsYW5rIj5o aWVyIA0KICAgICAgICBrbGlja2VuPC9hPik8L2ZvbnQ+PC9mb250PjwvaT48 L2ZvbnQ+PC9mb250PjwvZm9udD48L2Rpdj4NCiAgICA8L3RkPg0KICA8L3Ry Pg0KICA8dHI+IA0KICAgIDx0ZCB3aWR0aD0iMTQiIGhlaWdodD0iMiI+Jm5i c3A7PC90ZD4NCiAgICA8dGQgY29sc3Bhbj0iMiIgaGVpZ2h0PSIyIj48Zm9u dCBmYWNlPSJBcmlhbCwgSGVsdmV0aWNhLCBzYW5zLXNlcmlmIiBzaXplPSIx IiBjb2xvcj0iIzMzMzMzMyI+RGllc2UgDQogICAgICBOYWNocmljaHQgd3Vy ZGUgaW0gSHRtbC1Gb3JtYXQgZ2VzZW5kZXQsIGZhbGxzIElociBFbWFpbHBy b2dyYW1tIGtlaW4gSHRtbCANCiAgICAgIHVudGVyc3QmdXVtbDt0enQsIGsm b3VtbDtubmVuPGJyPg0KICAgICAgU2llIHNpY2ggZGllc2UgU2VpdGUgYXVj aCBpbSBJbnRlcm5ldCBhbnNjaGF1ZW4uIEtsaWNrZW4gU2llIGRhenUgYml0 dGU8Zm9udCBjb2xvcj0iI0NDMDAwMCI+PGI+IA0KICAgICAgPGEgaHJlZj0i aHR0cDovL3d3dy5uZXRtYWlsa3VyaWVyLmRlIiB0YXJnZXQ9Il9wYXJlbnQi PmhpZXI8L2E+PC9iPjwvZm9udD4uPC9mb250PjwvdGQ+DQogIDwvdHI+DQog IDx0cj4gDQogICAgPHRkIHdpZHRoPSIxNCIgaGVpZ2h0PSIyIj4gDQogICAg ICA8ZGl2IGFsaWduPSJjZW50ZXIiPjwvZGl2Pg0KICAgIDwvdGQ+DQogICAg PHRkIGNvbHNwYW49IjIiIGhlaWdodD0iMiI+PGZvbnQgZmFjZT0iQXJpYWws IEhlbHZldGljYSwgc2Fucy1zZXJpZiIgc2l6ZT0iMSIgY29sb3I9IiMzMzMz MzMiPjxiPkhJTldFSVMgDQogICAgICBaVU0gQUJCRVNURUxMRU4gREVTIE5F V1NMRVRURVJTPC9iPjwvZm9udD48YnI+DQogICAgICA8Zm9udCBmYWNlPSJB cmlhbCwgSGVsdmV0aWNhLCBzYW5zLXNlcmlmIiBzaXplPSIxIiBjb2xvcj0i IzMzMzMzMyI+U2llIGVyaGFsdGVuIA0KICAgICAgZGllc2VuIE5ld3NsZXR0 ZXIsIHdlaWwgU2llIG9kZXIgamVtYW5kIGFuZGVyZXMgSWhyZSBBZHJlc3Nl IHp1IHVuc2VyZW0gDQogICAgICBOZXdzbGV0dGVyIGFuZ2VtZWxkZXQgaGF0 LiBTaWUgd29sbGVuIGRpZXNlbiBOZXdzbGV0dGVyIG5pY2h0IG1laHI8L2Zv bnQ+IA0KICAgICAgPGZvbnQgZmFjZT0iQXJpYWwsIEhlbHZldGljYSwgc2Fu cy1zZXJpZiIgc2l6ZT0iMSIgY29sb3I9IiMzMzMzMzMiPiB0cmFnZW4gDQog ICAgICBTaWUgc2ljaCBiaXR0ZTxiPjxmb250IGNvbG9yPSIjQ0MwMDAwIj4g PGEgaHJlZj0iaHR0cDovL3d3dy5uZXRtYWlsa3VyaWVyLmRlL2VtYWlsbG9l c2NoZW4uaHRtIiB0YXJnZXQ9Il9ibGFuayI+aGllcjwvYT48L2ZvbnQ+PC9i PiANCiAgICAgIGF1cyB1bnNlcmVyIE1haWxpbmdsaXN0ZSBhdXMuIDwvZm9u dD48L3RkPg0KICA8L3RyPg0KPC90YWJsZT4NCjxicj4NCjxwPiZuYnNwOzwv cD4NCjwvYm9keT4NCjwvaHRtbD4NCg== --= Multipart Boundary 0506021810 Content-Type: application/octet-stream; name="tassegross.jpg" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="tassegross.jpg" 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 E3AH/9k= --= Multipart Boundary 0506021810 Content-Type: application/octet-stream; name="foto2.jpg" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="foto2.jpg" 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 AgEAgEAgEAgEH//Z --= Multipart Boundary 0506021810 Content-Type: application/octet-stream; name="automat.jpg" Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="automat.jpg" /9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja3kAAQAEAAAAIwAA/+4ADkFk b2JlAGTAAAAAAf/bAIQADgoKCgsKDgsLDhQNCw0UGBIODhIYGxYWFxYWGxoU FxcXFxQaGh8gIyAfGikpLS0pKT07Ozs9QEBAQEBAQEBAQAEPDQ0PEQ8SEBAS FA4RDhQXEhQUEhchFxcZFxchKh4aGhoaHiomKSMjIykmLy8qKi8vOjo4OjpA QEBAQEBAQEBA/8AAEQgAwgBkAwEiAAIRAQMRAf/EAJgAAAEFAQEBAAAAAAAA AAAAAAADBAUGBwIBCAEBAQEBAQAAAAAAAAAAAAAAAAECAwQQAAEDAgMCCQgG CAYDAAAAAAEAAgMRBCESBTEGQVFxsSITcxQ1YYGRMnKy0jShwUJSM0PRYiNT g3QVFoKSosIkB/DhkxEBAQACAQMEAgMAAAAAAAAAAAERAjEhEgNBUZETYVKB IjL/2gAMAwEAAhEDEQA/ANJVPP8A2Po4kdH3a5qxxaTSOmBp+8VwWBz16+4I ND1hxHtOQapHv3pkgqLeccoZ8aV/vTTv3E/oZ8az/TdLurm0Zcm7MbZK5WAV PRNMaUonf9FmO28f/q+JMxMrp/eum/uZ/Q340f3tpv7mb0N+JUgaG6Rzm96d VvG4ivpeFBXzTa3MluayZKdISHGorwFydDq1F2/Wlt2wT+hnxrgb/aUTQQXH oZ8ayN9zj6pH+Ny8bdZT6p/zuV6HVsbN9dOfsgn9DPjS7d6rJ2yGb0N+JZho wdeNe7M6Pq3sZTM5wOfZ9pqu+m7rR3lo2fvcja1BAaaYfxE6HVLS73WEQq6G Y8gb8SktK1OHVLQXcDXMYXFtH0Bq3kJWfa1Yf03UBatldKBiXOJFQ6NzqZS4 7CrfuZ4K3tZOdLgzcp9CEKKFhAi66+khrl6yfLXiq5wW7rDbbxU/zI98olSV pFLaRFr7uSCPOQxraAOAwzCp405Li+KR8N9K98bS4gu4Bx0KbytkktainQnl biaYGjuIpW3AFvP950by7h4OBDDmGMSsa6S9dGXirjmwB4jwqH1AmK4pC9t4 0k1eGPDhQ06ReOZTVpm6plLQTdE4GnS/W+8oPVfmelF3F1T0QJRmx29M0w8i pEjHpmkSaLcXst41moRupFa0YMwFKDKemc1TiMAoljGZgMoxI4ArLa95/tS+ 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 AhCEAhCEAhCEAhCEAhCEH//Z --= Multipart Boundary 0506021810-- From goodger@users.sourceforge.net Tue May 7 18:29:38 2002 From: goodger@users.sourceforge.net (David Goodger) Date: Tue, 07 May 2002 13:29:38 -0400 Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness) In-Reply-To: <01ca01c1f5a6$099e7380$545aa8c0@lslp862.int.lsl.co.uk> Message-ID: [moving to Doc-SIG for greater exposure] David Goodger wrote: >> However, a literal block isn't really the ideal way to represent an >> address block, is it? I've been mulling over an idea for a "verse" >> directive which seems to apply here. See >> http://docutils.sf.net/spec/notes.html#body-verse. What do you >> think? How about that ';;' syntax? Tony J Ibbs (Tibs) wrote: > As you say, the outstanding question is interpretation of inline markup > within a verse - i.e., in HTML terms, is it 
 or not...

Literal blocks use 
 exclusively and treat all whitespace and line
breaks as significant; no inline markup is recognized.  In "verse blocks"
(semi-literal blocks; anybody have a better name?) only line breaks and
indentation are treated differently from a regular paragraph; inline markup
like *emphasis* is recognized normally.

> Thinking *about* verses, I'd obviously argue for allowing inline markup,
> but am unfussed about lists

I don't think lists or anything else are necessary.  Verse blocks can be
thought of as variations of paragraphs, which don't have nested constructs
in the Docutils model.

> I'm not *too* keen on the use of ";;", but it does have a clear analogy
> with "::", and it's unlikely to be used "by mistake". I assume the rules
> of how it appears are identical to those for "::"? (i.e., precede with a
> space to suppress a colon in the output?)

Perhaps, although I don't think people will want to end a paragraph with a
semicolon.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From tony@lsl.co.uk  Wed May  8 09:48:29 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Wed, 8 May 2002 09:48:29 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)
In-Reply-To: 
Message-ID: <01da01c1f66d$2077b9f0$545aa8c0@lslp862.int.lsl.co.uk>

I wrote:
> I'm not *too* keen on the use of ";;", but it does have a clear
analogy
> with "::", and it's unlikely to be used "by mistake". I assume the
rules
> of how it appears are identical to those for "::"? (i.e., precede with
a
> space to suppress a colon in the output?)

David Goodger replied:
> Perhaps, although I don't think people will want to end a
> paragraph with a semicolon.

Ah - sorry, perhaps too much telegraphing in my original paragraph.

What I meant is:

I assume that ";;" will translate to a single colon (or not) according
to the same rules as used for "::" - thus::

    Here is a verse;;

        It's very short

gives::

    Here is a verse:

        It's very short

but::

    Here is a verse ;;

        It's very short

gives::

    Here is a verse

        It's very short

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)





From Paul.Moore@atosorigin.com  Wed May  8 10:01:00 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Wed, 8 May 2002 10:01:00 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B304@UKRUX002.rundc.uk.origin-it.com>

From: David Goodger [mailto:goodger@users.sourceforge.net]
> David Goodger wrote:
> >> However, a literal block isn't really the ideal way to represent an
> >> address block, is it?  I've been mulling over an idea for a "verse"
> >> directive which seems to apply here.  See
> >> http://docutils.sf.net/spec/notes.html#body-verse. What do you
> >> think?  How about that ';;' syntax?
> 
> Tony J Ibbs (Tibs) wrote:
> > As you say, the outstanding question is interpretation of 
> > inline markup within a verse - i.e., in HTML terms, is
> > it 
 or not...
> 
> Literal blocks use 
 exclusively and treat all whitespace and
> line breaks as significant; no inline markup is recognized.
> In "verse blocks" (semi-literal blocks; anybody have a better
> name?) only line breaks and indentation are treated differently
> from a regular paragraph; inline markup like *emphasis* is
> recognized normally.

Frankly, this seems like overkill to me. I can see what you're getting at -
there's a gap in the logical model, between completely literal blocks, and
completely interpreted text - but I don't think the gap needs to be filled.

How often is this construct likely to be used? In what contexts? (Python
docstrings? Wiki pages? I'm not sure what target applications are key for
ReST, other than Python docstrings, and doc-sig postings :-)

If you really, really, feel the need to put it in, make it a directive.
Don't invent new syntax for it. And maybe even just make it a sample
directive, not enshrined in the spec, but available as an example of how the
directive infrastructure can be extended.

This actually raises a question, which may well be covered in the
documentation - I haven't read it for a while. How does a document which
relies on a particular directive, state that fact? Just by using it? So that
if the user doesn't specify the directive (using command line flags to the
tools?) he gets a system error/warning, and works out what to do from there?
I guess that's OK, actually - we don't want to have to start documents with
blurb like::

    .. using:: image, quote, my-special-directive

That just gets silly...

Just my 2p worth.
Paul.



From goodger@users.sourceforge.net  Thu May  9 05:07:30 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 09 May 2002 00:07:30 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B304@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

Moore, Paul wrote:
> Frankly, this seems like overkill to me. I can see what you're
> getting at - there's a gap in the logical model, between completely
> literal blocks, and completely interpreted text - but I don't think
> the gap needs to be filled.

Perhaps you'd feel differently if you needed to use it?

> How often is this construct likely to be used? In what contexts?

Richard Jones wanted a snailmail address in a document.  That's a
significant use case.  I have yet to quote verse in a document (except
to illustrate this construct), but I can see it happening.  Thinking
of every time I've had to use a line break in Word, or 
 in HTML, I
believe the construct has merit.

> If you really, really, feel the need to put it in, make it a
> directive. Don't invent new syntax for it.

I agree.  Syntax can be added later if called for.

> And maybe even just make it a sample directive, not enshrined in the
> spec, but available as an example of how the directive
> infrastructure can be extended.

I think that, similarly to modules in Python's library, directives
that are "standard" will be used, but directives that need to be
separately installed won't.  I'd like to build a rich variety of
standard directives, and document them all in "reStructuredText
Directives":

    http://docutils.sf.net/spec/rst/directives.html

> How does a document which relies on a particular directive, state
> that fact? Just by using it?

Yes.  There's currently no mechanism to explicitly declare required
directives.  Directives are located in the
docutils/parsers/rst/directives directory; there are two lookup tables
linking localized directive name (currently just English) -> canonical
directive name -> (module, function) names.  As long as a directive is
registered properly and located in the right place, the parser will
find it.

If an unknown directive is used in a document, an error is reported.

> we don't want to have to start documents with blurb like::
> 
>     .. using:: image, quote, my-special-directive

No, we probably don't.  (*I* certainly don't!)  Thus the need for a
standard place to put directive code.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From goodger@users.sourceforge.net  Thu May  9 05:09:33 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 09 May 2002 00:09:33 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
In-Reply-To: <01da01c1f66d$2077b9f0$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: 

[David]
> > Perhaps, although I don't think people will want to end a
> > paragraph with a semicolon.

[Tony]
> What I meant is:
> 
> I assume that ";;" will translate to a single colon (or not)
> according to the same rules as used for "::"

I see.  I wasn't making the same assumption.  Were we to implement
syntax for the verse construct, that may be a useful approach.  But
since a directive will suffice for now, the point is moot.  We'll
keep a record of the idea for posterity though.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From goodger@users.sourceforge.net  Thu May  9 05:09:53 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 09 May 2002 00:09:53 -0400
Subject: [Doc-SIG] Applications for Docutils/reStructuredText
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B304@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

Moore, Paul wrote:
> I'm not sure what target applications are key for ReST, other than
> Python docstrings, and doc-sig postings :-)

Currently, and until docstring processing has matured, standalone
document processing is the biggest "market".  Here's how Docutils is
actually being applied now:

- HTML: http://docutils.sourceforge.net's HTML is completely
  auto-generated (except for the quickref, which Tony Ibbs
  hand-coded).  I've seen other sites using it as well (in a Google
  search).

- Presentations: Richard Jones did some initial work on PythonPoint
  integration.

- General documentation: Engelbert Gruber is working on ReportLabs PDF
  integration.

Contrary to the nay-sayers who have claimed that "all we need for
docstrings are paragraphs, bullet lists, and [add a random two or
three other constructs here]", I believe that a rich palette is key.
ReStructuredText is providing a rich palette for input syntax; we're
building a variety of context-aware readers, and writers for multiple
formats.  With a rich, generic syntax and a modular, flexible system,
the range of applications is very wide: from tiny docstrings to huge
documents, and nearly everything in-between.  As components are added,
the possibilities multiply.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From tony@lsl.co.uk  Thu May  9 09:49:36 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 9 May 2002 09:49:36 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsingoddness)
In-Reply-To: 
Message-ID: <01f401c1f736$72442dd0$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger wrote (re ";;" to ":" translation in verses, etc):
> I see.  I wasn't making the same assumption.  Were we to implement
> syntax for the verse construct, that may be a useful approach.  But
> since a directive will suffice for now, the point is moot.  We'll
> keep a record of the idea for posterity though.

*If* we were using ";;", then I think that having it behave in the way I
suggest would make sense.

*But* I firmly agree that a directive is the sensible approach, at least
for the moment - and for the reasons already discussed.

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)





From tony@lsl.co.uk  Thu May  9 09:52:04 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 9 May 2002 09:52:04 +0100
Subject: [Doc-SIG] Applications for Docutils/reStructuredText
In-Reply-To: 
Message-ID: <01f501c1f736$ca8c6de0$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger wrote:
> - General documentation: Engelbert Gruber is working on ReportLabs PDF
>   integration.

Great! Has he mentioned this to Andy Robinson/Reportlabs?

At the UKPython meeting last month, I talked briefly with Andy,
mentioning docutils, and aiming to follow up ('cos the match between
what we want and what they provide seems so neat). Work has pulled me in
other directions, though, so I've not had time to contact him about
either he work or doc-sig related issues - it would be good if someone
else were forming links...

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)





From Paul.Moore@atosorigin.com  Thu May  9 09:55:29 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Thu, 9 May 2002 09:55:29 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B305@UKRUX002.rundc.uk.origin-it.com>

From: David Goodger [mailto:goodger@users.sourceforge.net]
> Perhaps you'd feel differently if you needed to use it?

Oh, certainly. I wasn't implying otherwise - just noting that we have to
take care not to include "the kitchen sink" just because someone wants it.
The recent discussion on python-dev was lukewarm, and I got the sense that
part of the issue was "why does it need to be so complicated?"
 
> > How often is this construct likely to be used? In what contexts?
> 
> Richard Jones wanted a snailmail address in a document.

That's a valid case. Two points - first, with this use case in mind, "verse"
is a dreadful name. I can't think of a good one, though. And the second
point is why can't this be handled with a literal block? I can't imagine
needing markup in an address. Is it just because literal blocks are
displayed in a fixed-width font, and so don't "look right"?

As I said, I see the value of this, but I think that we need to clarify the
aims somewhat.

As a related point, I personally would prefer ``*emphasis*`` to be bold, not
italic, as this is the usage I see most frequently in E-Mail. However, I
accept that reST is addressing logical content, rather than layout, and as
such, the way the logical construct is formatted is the role of the backend,
not the document source. (This is a *good thing* - the alternative leads to
 tags...)

Given this premiss, I would ask again, what is the *logical* construct
involved here? Logically, the gap in functionality is the lack of any way of
including markup in a "literal" block. In other words, a
linebreak-preserving construct where markup is still respected. This is the
construct I fail to see the use for - I wouldn't need markup in a snailmail
address, so that use case doesn't mandate this.

On the other hand, there is a definite point to the layout issue of wanting
a "literal" construct which formats like running text, but with linebreaks
preserved. And yes, there is a "logical" value to such a construct - but
it's hard to put a name to it, and hence to understand its logical
significance (as opposed to its layout significance - "I want a literal
block of text here, but it looks funny if I use a real literal block which
displays in Courier")

> of every time I've had to use a line break in Word, or 
 in HTML, I
> believe the construct has merit.

Agreed - but Word linebreaks and 
 tags are inherently formatting
directives, not structural ones. That's the distinction I'm trying to make.

> > If you really, really, feel the need to put it in, make it a
> > directive. Don't invent new syntax for it.
> 
> I agree.  Syntax can be added later if called for.

And at least as importantly, if you use a directive, you're *forced* to
think up a decent name for it! Verse doesn't work for 99% of the real life
use cases, and its a PR disaster ("look - this thing is clearly a kitchen
sink design - who ever needs to quote verse in Python docstrings???") Quote
is a little better, but still has unsuitable overtones (in LaTeX, IIRC, the
quote environment uses smaller, slanted text, which is a common convention
for "real" quotes).

> I think that, similarly to modules in Python's library, directives
> that are "standard" will be used, but directives that need to be
> separately installed won't.  I'd like to build a rich variety of
> standard directives, and document them all in "reStructuredText
> Directives":

OK, that fits with the Python library concept. If you make it clear that
"library directives" are extensions, not part of "core" reST, then I have no
problem with this. It's the bloat question and PR issues again, though.

Thanks for listening - as I said, I'm not against the construct per se, but
I would like to see a clearer picture of the logic behind it...

Paul.



From tony@lsl.co.uk  Thu May  9 10:13:43 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Thu, 9 May 2002 10:13:43 +0100
Subject: [Doc-SIG] RE: emphasis presentation (was verse construct (was Re: [Docutils-develop] Parsing oddness))
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B305@UKRUX002.rundc.uk.origin-it.com>
Message-ID: <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>

Paul Moore wrote:
> As a related point, I personally would prefer ``*emphasis*``
> to be bold, not italic, as this is the usage I see most
> frequently in E-Mail.

Interesting. For me, *because* I see the asterisk delimitation more
often, I want it to be italic - italic for me is more emphasised (easier
to discriminate) than bold. Of course, this probably supports your point
about separating presentation from structure - it's easy to conceive of
a tool that produces presentation according to either of our
preferences.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)





From guido@python.org  Thu May  9 13:36:33 2002
From: guido@python.org (Guido van Rossum)
Date: Thu, 09 May 2002 08:36:33 -0400
Subject: [Doc-SIG] RE: emphasis presentation (was verse construct (was Re: [Docutils-develop] Parsing oddness))
In-Reply-To: Your message of "Thu, 09 May 2002 10:13:43 BST."
 <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>
References: <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <200205091236.g49CaX602131@pcp742651pcs.reston01.va.comcast.net>

> Paul Moore wrote:
> > As a related point, I personally would prefer ``*emphasis*``
> > to be bold, not italic, as this is the usage I see most
> > frequently in E-Mail.

[Tony Ibbs]
> Interesting. For me, *because* I see the asterisk delimitation more
> often, I want it to be italic - italic for me is more emphasised (easier
> to discriminate) than bold.

FWIW, I'm with Tony.

--Guido van Rossum (home page: http://www.python.org/~guido/)



From aahz@pythoncraft.com  Thu May  9 16:20:07 2002
From: aahz@pythoncraft.com (Aahz)
Date: Thu, 9 May 2002 11:20:07 -0400
Subject: [Doc-SIG] RE: emphasis presentation (was verse construct (was Re: [Docutils-develop] Parsing oddness))
In-Reply-To: <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B305@UKRUX002.rundc.uk.origin-it.com> <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <20020509152006.GA7890@panix.com>

On Thu, May 09, 2002, Tony J Ibbs (Tibs) wrote:
> Paul Moore wrote:
>>
>> As a related point, I personally would prefer ``*emphasis*``
>> to be bold, not italic, as this is the usage I see most
>> frequently in E-Mail.
> 
> Interesting. For me, *because* I see the asterisk delimitation more
> often, I want it to be italic - italic for me is more emphasised (easier
> to discriminate) than bold. Of course, this probably supports your point
> about separating presentation from structure - it's easy to conceive of
> a tool that produces presentation according to either of our
> preferences.

Heh.  I use pure italics for book titles, and if I'm really trying to
emphasize something, I use both bold and italics.  (Pure bold gets used
for key terms that are being introduced.)
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

See me at OSCON!  I'm teaching Python for [Perl] Programmers, a fast intro 
for all experienced programmers (not just Perl).  Early bird ends June 10.
http://conferences.oreillynet.com/os2002/



From goodger@users.sourceforge.net  Fri May 10 04:55:25 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 09 May 2002 23:55:25 -0400
Subject: [Doc-SIG] Re: emphasis presentation (was verse construct (was Re:
 [Docutils-develop] Parsing oddness))
In-Reply-To: <01f701c1f739$d0e83540$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: 

Paul Moore wrote:
> I personally would prefer ``*emphasis*`` to be bold

That's easy; just change your stylesheet.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From goodger@users.sourceforge.net  Fri May 10 04:55:56 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Thu, 09 May 2002 23:55:56 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B305@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

Paul Moore wrote:
> The recent discussion on python-dev was lukewarm, and I got the
> sense that part of the issue was "why does it need to be so
> complicated?"

Because too simple is useless.  HappyDoc seems like a great tool, but
I don't use it because using StructuredText is like hitting my head
against a brick wall.  But it *is* enough for some.

I've found that many people, programmers especially, take a
condescending attitude toward documentation and related tools, which
results in computers being used as electronic pencils.  If we listened
to them, we'd still be using typewriters (nix that: clay tablets!).  I
saw it when I was working in Japan with SGML -- well-known
multinational companies (an RDBMS producer, a car manufacturer, and a
telcom giant) treated their documentation as garbage.  But I digress.

> > Richard Jones wanted a snailmail address in a document.
> 
> That's a valid case. Two points - first, with this use case in mind,
> "verse" is a dreadful name. I can't think of a good one, though.

Let me know if you do.  I'll be hitting the thesaurus myself.

> And the second point is why can't this be handled with a literal
> block? I can't imagine needing markup in an address. Is it just
> because literal blocks are displayed in a fixed-width font, and so
> don't "look right"?

Yes, that's right.  Markup may not be needed in address blocks, but it
would be in other applications.  The idea originally applied to
quoting verse: poetry, song lyrics, etc.  I pointed out to Richard at
the beginning of this thread that it was equally applicable to address
blocks.  So address blocks are a secondary use case, not the primary
one.

> I would ask again, what is the *logical* construct involved here?
> Logically, the gap in functionality is the lack of any way of
> including markup in a "literal" block. In other words, a
> linebreak-preserving construct where markup is still respected.

I approach it from the opposite side.  It's not the lack of markup in
literal blocks, but the lack of linebreak and indentation control in
paragraphs.  The "verse" construct permits significant linebreaks and
indentation in otherwise ordinary paragraphs.  Literal blocks have the
connotation of program input or output; this construct doesn't.
Literal blocks' use of a monospaced typeface is to emphasize this
connotation.

That gives me an idea for a name for this thing: "literary blocks"...
Probably too clever by far.  ;-)

> Word linebreaks and 
 tags are inherently formatting directives,
> not structural ones. That's the distinction I'm trying to make.

Hmm.  I think poets would differ.  The way a poem is broken up into
lines (whether there's a rhyming scheme or not) is *very* significant,
and conveys a large part of the poem's structure.  Similarly (but in a
much less interesting way) with the pedestrian address block: the line
itself is a unit of structure.

> And at least as importantly, if you use a directive, you're *forced*
> to think up a decent name for it!

Yes, explicit is good, especially for non-mainstream uses.  Please
keep the search for the right name running on low priority in the back
of your brain.

> If you make it clear that "library directives" are extensions, not
> part of "core" reST, then I have no problem with this.

I've rearranged the text of the directive definition to reflex this
emphasis:

    http://docutils.sf.net/spec/rst/reStructuredText.html#directives

> Thanks for listening - as I said, I'm not against the construct per
> se, but I would like to see a clearer picture of the logic behind
> it...

Sure.  Thank *you* for writing.  The feedback is valuable, as always.

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From Paul.Moore@atosorigin.com  Fri May 10 09:05:46 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Fri, 10 May 2002 09:05:46 +0100
Subject: [Doc-SIG] RE: emphasis presentation (was verse construct (was Re: [Docutils
 -develop] Parsing oddness))
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B308@UKRUX002.rundc.uk.origin-it.com>

From: David Goodger [mailto:goodger@users.sourceforge.net]
> Paul Moore wrote:
> > I personally would prefer ``*emphasis*`` to be bold
> 
> That's easy; just change your stylesheet.

I think that's my point :-) If you could change the style on a literal
block, presentation could be under the user's control, and so the proposed
verse construct would just be a different style for a literal block. Of
course, (a) you can't do this on a per-block basis, and (b) it doesn't help
other presentation formats than HTML.

I still don't see a real need for a hybrid literal-with-inline-markup
construct. Examples can be produced, but they don't feel like significant
cases.

If we really need this level of control, maybe it's time to implement a more
general "output format specific code" directive. Something like

    .. for: type=html
       Put whatever raw HTML you like here
    .. for: type=LaTeX
       \begin{red}
       And here, you write raw TeX
       \end{red}

Of course, this makes the document output-specific, and risks errors
(malformed HTML), etc etc. But it is totally general, if people really
care...

Paul.



From Paul.Moore@atosorigin.com  Fri May 10 09:46:39 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Fri, 10 May 2002 09:46:39 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B309@UKRUX002.rundc.uk.origin-it.com>

From: David Goodger [mailto:goodger@users.sourceforge.net]
> Paul Moore wrote:
> > The recent discussion on python-dev was lukewarm, and I got the
> > sense that part of the issue was "why does it need to be so
> > complicated?"
> 
> Because too simple is useless.  HappyDoc seems like a great tool, but
> I don't use it because using StructuredText is like hitting my head
> against a brick wall.  But it *is* enough for some.

"As simple as possible, but no simpler". Exactly. It's the "as possible" bit
that is generally the sticking point. What's one person's useless fluff is
another's impossible to live without. But the doc-sig is in the unenviable
position of having to make priority judgements.

Don't forget, we still haven't got a construct to allow words to be set in
24-point blinking script capitals. And please God, don't let us ever get one
:-) But I've seen plenty of web sites which provide evidence that *someone*
thinks it is appropriate :-(

> I've found that many people, programmers especially, take a
> condescending attitude toward documentation and related tools, which
> results in computers being used as electronic pencils.  If we listened
> to them, we'd still be using typewriters (nix that: clay tablets!).  I
> saw it when I was working in Japan with SGML -- well-known
> multinational companies (an RDBMS producer, a car manufacturer, and a
> telcom giant) treated their documentation as garbage.  But I digress.

Again, it's a case of being aware of your target application. Not many
people quote poetry in technical documentation. But many would want to
include an address. On the other hand, the balance could be completely the
opposite in E-Mail postings (depending on the mailing list). It's still a
case of needing to understand the priorities.

> Yes, that's right.  Markup may not be needed in address blocks, but it
> would be in other applications.  The idea originally applied to
> quoting verse: poetry, song lyrics, etc.  I pointed out to Richard at
> the beginning of this thread that it was equally applicable to address
> blocks.  So address blocks are a secondary use case, not the primary
> one.

But in terms of probability of being needed, address blocks are more
significant (in my personal view of the target application). It's an 80-20
thing.

BTW, on the verse issue specifically, I'm convinced (see below), subject to
a decent name. The bulk of what I'm now saying is in terms of generalities.
I'm really arguing that we have now reached a stage where a more
conservative approach is called for. Specifically, no new syntax should be
added - directives form our extension mechanism, and we should concentrate
on consolidating the core, and if appropriate, building our "standard
library". And on *using* these things for real, in visible ways. It's
interesting and encouraging to be reminded that the docutils web pages are
all generated from reST. More such public examples would be nice - as well
as giving a real-life indication of which constructs are important in
practice...

> I approach it from the opposite side.  It's not the lack of markup in
> literal blocks, but the lack of linebreak and indentation control in
> paragraphs.  The "verse" construct permits significant linebreaks and
> indentation in otherwise ordinary paragraphs.  Literal blocks have the
> connotation of program input or output; this construct doesn't.
> Literal blocks' use of a monospaced typeface is to emphasize this
> connotation.

Ah, yes. When you put it like that, I see your point better. BTW,
significant indentation? That could be hard - input is monospaced font, but
output is proportional, so preserving the *appearance* of an indent won't be
that easy.

> That gives me an idea for a name for this thing: "literary blocks"...
> Probably too clever by far.  ;-)

Yes. Given that my preferred use case is addresses, I'd argue for "address
blocks", and then note in the documentation that these will work for all
sorts of other things, like quoting verse... (And I'm not really joking
here, either!)

> Hmm.  I think poets would differ.  The way a poem is broken up into
> lines (whether there's a rhyming scheme or not) is *very* significant,
> and conveys a large part of the poem's structure.  Similarly (but in a
> much less interesting way) with the pedestrian address block: the line
> itself is a unit of structure.

OK. This is the point at which you have convinced me. There are significant
cases where line breaking denotes structure, but in a sufficiently
"unstructured" way (:-)) that the existing constructs such as lists, etc,
don't do what you want.

Maybe something like "multiline" blocks gives the flavor, without stressing
a particular usage...?

> I've rearranged the text of the directive definition to reflex this
> emphasis:
> 
>     http://docutils.sf.net/spec/rst/reStructuredText.html#directives

I'd add a bit more. "Directives which have been implemented and registered
in the reference reStructuredText parser are described in the
reStructuredText Directives document." Add after this "Document authors are
entitled to expect that all such standard directives are available. Any
other directives should be viewed as domain-specific, and may require
special action to make them available when processing the document."

Or something like that...

Paul.



From tony@lsl.co.uk  Fri May 10 10:32:19 2002
From: tony@lsl.co.uk (Tony J Ibbs (Tibs))
Date: Fri, 10 May 2002 10:32:19 +0100
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsingoddness)
In-Reply-To: 
Message-ID: <020e01c1f805$949ebb00$545aa8c0@lslp862.int.lsl.co.uk>

David Goodger wrote:
David Goodger wrote:
> That gives me an idea for a name for this thing: "literary blocks"...
> Probably too clever by far.  ;-)

Hmm. I don't really see::

    .. literary::

working as a directive. Although it's a kindof neat concept!

For what little it is worth, here are some random ideas::

    .. freeform::
    .. keeplines::
    .. nowrap::

The last is inelegant but might be the most evocative.

Tibs

-- 
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)




From aahz@pythoncraft.com  Fri May 10 14:09:47 2002
From: aahz@pythoncraft.com (Aahz)
Date: Fri, 10 May 2002 09:09:47 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B309@UKRUX002.rundc.uk.origin-it.com>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B309@UKRUX002.rundc.uk.origin-it.com>
Message-ID: <20020510130947.GA17474@panix.com>

On Fri, May 10, 2002, Moore, Paul wrote:
>
> Again, it's a case of being aware of your target application. Not many
> people quote poetry in technical documentation. But many would want to
> include an address. On the other hand, the balance could be completely the
> opposite in E-Mail postings (depending on the mailing list). It's still a
> case of needing to understand the priorities.

Overall, "not many" is correct; I just want to emphasize that it's not
"few" or "rare".

> Yes. Given that my preferred use case is addresses, I'd argue for "address
> blocks", and then note in the documentation that these will work for all
> sorts of other things, like quoting verse... (And I'm not really joking
> here, either!)

"Address blocks" is okay.  WRT your "multiline blocks", I suggest simply
"line blocks".
-- 
Aahz (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

"usenet imitates usenet"  --Darkhawk



From willg@bluesock.org  Fri May 10 14:19:41 2002
From: willg@bluesock.org (will)
Date: Fri, 10 May 2002 08:19:41 -0500 (CDT)
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B309@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

On Fri, 10 May 2002, Moore, Paul wrote:
> 
> Again, it's a case of being aware of your target application. Not many
> people quote poetry in technical documentation.

I do.  This might sound odd, but sometimes I like writing little haiku 
snippets in because the documentation is tedious to write and this makes 
it a bit more exciting for me (the documenter) and other folks (the 
readers).  It also gets across the fact that I'm slightly insane and they 
treat the code and documentation accordingly.

I find a lot of this discussion really interesting.  Most of it starts off
with "why do we need xxx?  no one will use it." as opposed to "hey--i need
xxx for these purposes and StructuredText fits my needs like building a
house out of figgy newtons."

I know most of us are seasoned developers and have lots of experience--but
surely we don't think we've cornered the market on all experience.  From
reading the reStructuredText specification and listening to David respond
to many of the responses to it, I believe reStructuredText is a very well
thought out markup syntax that definitely meets the requirements of its
mission statement as stated and worked through however many months ago.

Currently I use happydoc for my ool docs and AFT for my regular
documentation.  But I loathe StructuredText--it's like an unruly
step-child.  I very much look forward to happydoc supporting
reStructuredText and if they don't get around to it when I do my next
massive documentation overhaul, I may just add it in myself.  When that
happens, I'm definitely switching over.

That's my soapbox.

/will




From doug@hellfly.net  Fri May 10 14:29:45 2002
From: doug@hellfly.net (Doug Hellmann)
Date: Fri, 10 May 2002 09:29:45 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing  oddness)
In-Reply-To: 
References: 
Message-ID: <200205101329.JAA04490@branagan.hellfly.net>

On Friday 10 May 2002 09:19, will wrote:
> Currently I use happydoc for my ool docs and AFT for my regular
> documentation.  But I loathe StructuredText--it's like an unruly
> step-child.  I very much look forward to happydoc supporting
> reStructuredText and if they don't get around to it when I do my next
> massive documentation overhaul, I may just add it in myself.  When that
> happens, I'm definitely switching over.

I'm always glad to hear about happy users, even if only semi-happy.  

I definitely have reST on my list of things to support, and have completed 
the docstring parser plugin system in HappyDoc specifically to allow me to 
provide that support.  I have not, however, had time to write the actual reST 
plugin.  It should be a pretty straightforward task for someone familiar with 
the reST converter code.

As usual, patches are always welcome.

Doug



From goodger@users.sourceforge.net  Sat May 11 17:46:05 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 11 May 2002 12:46:05 -0400
Subject: [Doc-SIG] Re: emphasis presentation (was verse construct (was Re: [Docutils
 -develop] Parsing oddness))
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B308@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

Paul Moore wrote:
> If we really need this level of control, maybe it's time to
> implement a more general "output format specific code"
> directive. Something like
> 
>     .. for: type=html
>        Put whatever raw HTML you like here
>     .. for: type=LaTeX
>        \begin{red}
>        And here, you write raw TeX
>        \end{red}

Not implemented yet, but the spec is already there:
http://docutils.sf.net/spec/rst/directives.html#raw-data-pass-through

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From goodger@users.sourceforge.net  Sat May 11 17:50:10 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Sat, 11 May 2002 12:50:10 -0400
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
 oddness)
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B309@UKRUX002.rundc.uk.origin-it.com>
Message-ID: 

Paul Moore wrote:
> The bulk of what I'm now saying is in terms of generalities.  I'm
> really arguing that we have now reached a stage where a more
> conservative approach is called for.

I agree completely.

> Specifically, no new syntax should be added -

I'd add, "... without a thorough review".  That's one of the reasons
I'm holding off on the `auto-enumerated lists`__ proposal.

__ http://docutils.sf.net/spec/rst/alternatives.html#auto-enumerated-lists

> directives form our extension mechanism,

Yes.

> and we should concentrate on consolidating the core, and if
> appropriate, building our "standard library".

By your use of "we" and "our", can I assume that you'll be ramping up
your involvement?  Great!

> BTW, significant indentation? That could be hard - input is
> monospaced font, but output is proportional, so preserving the
> *appearance* of an indent won't be that easy.

Alignment of bits of text within lines can't be guaranteed, but the
line indentation itself (relative positions of just the left edges)
should be trivial.

> > I've rearranged the text of the directive definition to reflex this
> > emphasis:
> > 
> >     http://docutils.sf.net/spec/rst/reStructuredText.html#directives
> 
> I'd add a bit more.

Noted and added.  Thanks!

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/




From gustav@morpheus.demon.co.uk  Sat May 11 22:38:21 2002
From: gustav@morpheus.demon.co.uk (Paul Moore)
Date: 11 May 2002 22:38:21 +0100
Subject: [Doc-SIG] Re: verse construct (was Re: [Docutils-develop] Parsing oddness)
In-Reply-To: 
References: 
Message-ID: <8z6q2y4l.fsf@morpheus.demon.co.uk>

David Goodger  writes:
> > and we should concentrate on consolidating the core, and if
> > appropriate, building our "standard library".
> 
> By your use of "we" and "our", can I assume that you'll be ramping up
> your involvement?  Great!

I hope that constructive criticism counts as involvement :-) More
seriously, I'd happily get more involved, if I was sure where I could
contribute usefully. I had a look previously at doing some form of
output writer other than HTML. I would still like to do something like
that, in theory, but (a) my time is so limited that something
substantial like that is hard to manage (I get started, and then get
interrupted, and then have to start over...) and (b) I've never
managed to get up to speed with how writers should be
structured. Maybe now we have a combined docutils project, things may
have settled sown enough that I should look again.

Anyway, enough whining - if you do have anything that I could usefully
contribute (on the basis that odd half days is about all the time I
have) please let me know...

Paul.




From usc@ieee.org  Fri May 10 12:34:00 2002
From: usc@ieee.org (Ueli Schläpfer)
Date: 10 May 2002 13:34:00 +0200
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsingoddness)
In-Reply-To: <020e01c1f805$949ebb00$545aa8c0@lslp862.int.lsl.co.uk>
References: <020e01c1f805$949ebb00$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: 

[Tony]
> Hmm. I don't really see::
> 
>     .. literary::
> 
> working as a directive. Although it's a kindof neat concept!
> 
> For what little it is worth, here are some random ideas::
> 
>     .. freeform::
>     .. keeplines::
>     .. nowrap::
> 
> The last is inelegant but might be the most evocative.

Agreed (and others seem to have too [#1]_).  Don't name a
construct/directive after a specific use case -- leave it to the
user's creativity to apply it wherever it is suitable (other than the
ones the construct was invented for)!

.. [#1] See, for example, Paul Moore's post of May 10 in this thread.

A few more possibilities for names::

  .. obeylines::
  .. lines::
  .. linewise::

I've seen the first one in a TeX posting somewere, and I came up with
``.. linewise::`` when thinking of a suitable (and close) translation
of the directive to German.

And for completeness, here's my ranking:

1. ``.. keeplines::`` or ``.. obeylines::``
2. ``.. linewise::``
3. ``.. nowrap::``
4. ``.. lines::``
5. ``.. freeform::``

Ueli




From grubert@sourceforge.net  Sun May 12 17:34:17 2002
From: grubert@sourceforge.net (engelbert gruber)
Date: Sun, 12 May 2002 18:34:17 +0200 (CEST)
Subject: [Doc-SIG] Applications for Docutils/reStructuredText
In-Reply-To: <01f501c1f736$ca8c6de0$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: 

On Thu, 9 May 2002, Tony J Ibbs (Tibs) wrote:

> David Goodger wrote:
> > - General documentation: Engelbert Gruber is working on ReportLabs PDF
> >   integration.
>
> Great! Has he mentioned this to Andy Robinson/Reportlabs?
no whome should i talk to

just to damper a little bit, i am unsure what will work direct to
pdf, cause i see no point (or not enough time) to make another
hyphenation for getting a decent justification.

my list is i want paragraphs come out correct, titles and maybe emphasize
and bold. some things are easy e.g. pdf-contents are generated
from reportlab.



--
engelbert gruber
email: engelbert.gruber@ssg.co.at







From garth@deadlybloodyserious.com  Mon May 13 07:27:10 2002
From: garth@deadlybloodyserious.com (Garth Kidd)
Date: Mon, 13 May 2002 16:27:10 +1000
Subject: [Doc-SIG] verse construct (was Re: [Docutils-develop] Parsingoddness)
In-Reply-To: <020e01c1f805$949ebb00$545aa8c0@lslp862.int.lsl.co.uk>
Message-ID: <002101c1fa47$38a05c20$4700800a@gkiddlap>

keeplines: -1
verse: -0
literary: -0
freeform: +0
obeylines: +0
lines: +0
linewise: +1
nowrap: +1

Regards,
Garth.




From Juergen Hermann" 
Message-ID: 

On Wed, 8 May 2002 10:01:00 +0100, Moore, Paul wrote:

>How often is this construct likely to be used? In what contexts? (Pytho=
n
>docstrings? Wiki pages? I'm not sure what target applications are key f=
or
>ReST, other than Python docstrings, and doc-sig postings :-)

Wiki definitely is:

http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample

It's not complete yet, but as you can see works in principle.



Ciao, J=FCrgen

--
J=FCrgen Hermann, Developer (jhe@webde-ag.de)
WEB.DE AG, http://webde-ag.de/





From jepler@unpythonic.net  Tue May 21 16:32:59 2002
From: jepler@unpythonic.net (Jeff Epler)
Date: Tue, 21 May 2002 10:32:59 -0500
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
In-Reply-To: <20020521150555.2B93C18EB28@grendel.zope.com>
References: <20020521150555.2B93C18EB28@grendel.zope.com>
Message-ID: <20020521103259.B3603@unpythonic.net>

On Tue, May 21, 2002 at 11:05:55AM -0400, Fred L. Drake wrote:
> The development version of the documentation has been updated:
> 
>     http://www.python.org/dev/doc/devel/
> 
> Experimental change:  Add some really heavy markup in function signatures
> so that when the signature line is wrapped because the browser window is
> too narrow, the argument list will wrap to the left parenthesis opening the
> argument list.

Depending on my browser window's width I get a layout like

    class	       addr[, requestHandler[,
    SimpleXMLRPCServer(logRequests]])

while I would hope for a layout like

    class	
    SimpleXMLRPCServer(addr[, requestHandler[,
		       logRequests]])

I don't know if it's possible to do this, but it seems that the first
line of the parameter list should have the same baseline as the opening
paren of the declaration.  If this is not possible, then either forcing
'class SimpleXMLRPCServer' to not linebreak, or returning to the old
layout

    class SimpleXMLRPCServer(addr[, requestHandler[,
    logRequests]])

might be preferable.

Jeff
PS Please Cc: on replies, not a doc-sig subscriber



From David Abrahams" 
Message-ID: <02e301c200db$fcdf84e0$6601a8c0@boostconsulting.com>

----- Original Message -----
From: "Fred L. Drake" 
To: ; ; 
Sent: Tuesday, May 21, 2002 11:05 AM
Subject: [Python-Dev] [development doc updates]


> The development version of the documentation has been updated:
>
>     http://www.python.org/dev/doc/devel/
>
> Experimental change:  Add some really heavy markup in function signatures
> so that when the signature line is wrapped because the browser window is
> too narrow, the argument list will wrap to the left parenthesis opening
the
> argument list.

Cool idea! I'm going to have to steal it... after you fix it ;-)

On IE6, the doc for excepthook at
http://www.python.org/dev/doc/devel/lib/module-sys.html looks like this
when wrapped:

excepthook type, value,
(          traceback)

-Dave




From fdrake@acm.org  Tue May 21 16:59:19 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Tue, 21 May 2002 11:59:19 -0400
Subject: [Doc-SIG] Re: [Python-Dev] [development doc updates]
In-Reply-To: <20020521103259.B3603@unpythonic.net>
References: <20020521150555.2B93C18EB28@grendel.zope.com>
 <02e301c200db$fcdf84e0$6601a8c0@boostconsulting.com>
 <20020521103259.B3603@unpythonic.net>
Message-ID: <15594.28375.234450.956683@grendel.zope.com>

Jeff Epler writes:
 > Depending on my browser window's width I get a layout like
 > 
 >     class	       addr[, requestHandler[,
 >     SimpleXMLRPCServer(logRequests]])

Ugh!

 > while I would hope for a layout like
 > 
 >     class	
 >     SimpleXMLRPCServer(addr[, requestHandler[,
 > 		       logRequests]])

That would be ideal.  I'd love to be able to "weight" possible line
break locations somehow, but I don't think that's possible with
today's CSS, even in the more advanced browsers.

 > I don't know if it's possible to do this, but it seems that the first
 > line of the parameter list should have the same baseline as the opening
 > paren of the declaration.  If this is not possible, then either forcing
 > 'class SimpleXMLRPCServer' to not linebreak, or returning to the old
 > layout

Avoiding that linebreak should be easy; the equivalent for C function
descriptions is already there.  I'll upload an improved version
shortly.


David Abrahams writes:
 > Cool idea! I'm going to have to steal it... after you fix it ;-)
 > 
 > On IE6, the doc for excepthook at
 > http://www.python.org/dev/doc/devel/lib/module-sys.html looks like this
 > when wrapped:
 > 
 > excepthook type, value,
 > (          traceback)

Interesting; I can't get Mozilla to do that, no matter how narrow I
make the Window.  ;-)  I'll play with this when I have a Windows
machine in front of me.


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From Paul.Moore@atosorigin.com  Wed May 22 10:24:04 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Wed, 22 May 2002 10:24:04 +0100
Subject: [Doc-SIG] [development doc updates]
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>

From: Fred L. Drake [mailto:fdrake@acm.org]
> 
> The development version of the documentation has been updated:
> 
>     http://www.python.org/dev/doc/devel/
> 
> Slightly improved version of the experimental change; in 
> signature lines that start with "class " or "exception ",
> avoid line breaks between the leading word and the class
> or exception name.
> 
> Please continue to provide comments on the change to 
> doc-sig@python.org or to python-docs@python.org.

In http://www.python.org/dev/doc/devel/lib/module-copyreg.html, using IE6 on
a Windows 2000 machine, scroll down to the definition of pickle() at the
bottom. Narrow the window, and when you reach a certain point, the "("
following the function name word wraps onto the next line, resulting in

    pickle type, function[,
    (      constructor])

The "(" shouldn't be allowed to wrap.

I know this is a borderline case of a borderline case, but I'm not sure that
the benefits of all this are worth it. Even when wrapped "properly", you get

    pickle( type, function[,
            constructor])

which doesn't look right to me with the "[," hard up against the "function".
I'd prefer the "[," to wrap with the following parameter. To do that, you'd
need to use unbreakable spaces. Are these universally supported (or even
available??) And would unbreakable spaces work in any case? The original
problem I noted with "pickle(" would seem to imply that IE6 may well choose
to break between text and punctuation anyway.

I guess this is only really important for users on very narrow screens
(PDAs?), so their comments are probably more important here...

Paul.



From walter@livinglogic.de  Wed May 22 10:44:14 2002
From: walter@livinglogic.de (=?ISO-8859-15?Q?Walter_D=F6rwald?=)
Date: Wed, 22 May 2002 11:44:14 +0200
Subject: [Doc-SIG] [development doc updates]
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
Message-ID: <3CEB686E.8050502@livinglogic.de>

Moore, Paul wrote:

 > [...]
 > In http://www.python.org/dev/doc/devel/lib/module-copyreg.html, using 
 > IE6 on a Windows 2000 machine, scroll down to the definition of
 > pickle() at the bottom. Narrow the window, and when you reach a
 > certain point, the "(" following the function name word wraps onto
 > the next line, resulting in
 >
 >     pickle type, function[,
 >     (      constructor])
 >
 > The "(" shouldn't be allowed to wrap.
 >
 > I know this is a borderline case of a borderline case, but I'm not
 > sure that the benefits of all this are worth it. Even when wrapped
 > "properly", you get
 >
 >     pickle( type, function[,
 >             constructor])

The table solution seems rather fragile.

Why not use something like this:



pickle(type, 
function [, constructor])


and have a "margin-left: 3em" for the following text. (Of course
the style should be in an external style sheet.)

An example how this might look can be found at
http://www.livinglogic.de/Python/xist/converters/index.html
(scroll down to the Converter constructor)

Bye,
     Walter Dörwald






From fdrake@acm.org  Wed May 22 22:43:28 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 22 May 2002 17:43:28 -0400
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
Message-ID: <15596.4352.117370.107663@grendel.zope.com>

Moore, Paul writes:
 > In http://www.python.org/dev/doc/devel/lib/module-copyreg.html, using IE6 on
 > a Windows 2000 machine, scroll down to the definition of pickle() at the
 > bottom. Narrow the window, and when you reach a certain point, the "("
 > following the function name word wraps onto the next line, resulting in
 > 
 >     pickle type, function[,
 >     (      constructor])
 > 
 > The "(" shouldn't be allowed to wrap.

Shouldn't, but the controls are flakier here.  Try it now.

 > I know this is a borderline case of a borderline case, but I'm not sure that
 > the benefits of all this are worth it. Even when wrapped "properly", you get
 > 
 >     pickle( type, function[,
 >             constructor])
 > 
 > which doesn't look right to me with the "[," hard up against the "function".
 > I'd prefer the "[," to wrap with the following parameter. To do that, you'd

I'm not entirely sure I agree, but I can live with it either way.
What I'd really like to see is a half-space before the "[," (but not
if its just "[" following "(").  I've changed this a bit; it wraps for
me the way you describe on Mozilla 0.9.9; I don't have ready access to
MSIE right now.

 > need to use unbreakable spaces. Are these universally supported (or even
 > available??) And would unbreakable spaces work in any case? The original
 > problem I noted with "pickle(" would seem to imply that IE6 may well choose
 > to break between text and punctuation anyway.

It might; this seems like a policy issue that most browsers will
implement the same way, though, and not let the user control it
(though I think they should let the user control it).

 > I guess this is only really important for users on very narrow screens
 > (PDAs?), so their comments are probably more important here...

I think the right thing there is to generate simpler HTML and just let
it wrap any way it can.  That's not too difficult since the iSilo
format for PDAs is already using a customized version of the HTML
conversion.


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From fdrake@acm.org  Thu May 23 01:16:13 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 22 May 2002 20:16:13 -0400
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <15596.4352.117370.107663@grendel.zope.com>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
 <15596.4352.117370.107663@grendel.zope.com>
Message-ID: <15596.13517.96873.874552@grendel.zope.com>

Fred L. Drake, Jr. writes:
 > I'm not entirely sure I agree, but I can live with it either way.
 > What I'd really like to see is a half-space before the "[," (but not
 > if its just "[" following "(").  I've changed this a bit; it wraps for
 > me the way you describe on Mozilla 0.9.9; I don't have ready access to
 > MSIE right now.

Ok, I've checked the latest round of changes, and they seem to work
for my with MSIE 6 and Opera 6, both on Win2K.


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From fdrake@acm.org  Thu May 23 03:01:54 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 22 May 2002 22:01:54 -0400
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <3CEB686E.8050502@livinglogic.de>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
 <3CEB686E.8050502@livinglogic.de>
Message-ID: <15596.19858.958676.198267@grendel.zope.com>

Walter D=F6rwald wrote:
 > The table solution seems rather fragile.
 >
 > Why not use something like this:
[example elided]

Using CSS works well enough with the most modern & up to date
browsers, but many users don't update as aggressively as I do, and are
using older browsers.  My boss, for instance, uses Netscape
4.something, which doesn't do well with even moderate CSS.  There are
enough browsers out there that either don't implement all the
specifications, or don't get all the corner cases right, that CSS is
still only acceptable for "detailing", not for substantial
presentational control.

Now, we can definately be more aggressive with CSS for HTML that will
be converted to HTML Help in future releases, but that's only because
we don't expect the standards support to vary in that application.
User-selected browsers on the open Web are a different world.

 > An example how this might look can be found at
 > http://www.livinglogic.de/Python/xist/converters/index.html
 > (scroll down to the Converter constructor)

Nice!


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From fdrake@acm.org  Thu May 23 03:25:01 2002
From: fdrake@acm.org (Fred L. Drake, Jr.)
Date: Wed, 22 May 2002 22:25:01 -0400
Subject: [Doc-SIG] [development doc updates]
In-Reply-To: <15596.13517.96873.874552@grendel.zope.com>
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>
 <15596.4352.117370.107663@grendel.zope.com>
 <15596.13517.96873.874552@grendel.zope.com>
Message-ID: <15596.21245.457535.519880@grendel.zope.com>

I wrote:
 > I'm not entirely sure I agree, but I can live with it either way.
 > What I'd really like to see is a half-space before the "[," (but not
 > if its just "[" following "(").  I've changed this a bit; it wraps for
 > me the way you describe on Mozilla 0.9.9; I don't have ready access to
 > MSIE right now.

And then I wrote:
 > Ok, I've checked the latest round of changes, and they seem to work
 > for my with MSIE 6 and Opera 6, both on Win2K.

And I've now also checked it with Opera 5.12 and Netscape 6.2.1, where
it worked just fine.


  -Fred

-- 
Fred L. Drake, Jr.  
PythonLabs at Zope Corporation



From Paul.Moore@atosorigin.com  Thu May 23 08:54:39 2002
From: Paul.Moore@atosorigin.com (Moore, Paul)
Date: Thu, 23 May 2002 08:54:39 +0100
Subject: [Doc-SIG] [development doc updates]
Message-ID: <714DFA46B9BBD0119CD000805FC1F53B01B5B333@UKRUX002.rundc.uk.origin-it.com>

From: Fred L. Drake, Jr. [mailto:fdrake@acm.org]
> I've changed this a bit; it wraps for me the way you
> describe on Mozilla 0.9.9; I don't have ready access to
> MSIE right now.

Yes, that works fine on IE6 now.
Thanks,
Paul.



From walter@livinglogic.de  Thu May 23 12:25:50 2002
From: walter@livinglogic.de (=?ISO-8859-1?Q?Walter_D=F6rwald?=)
Date: Thu, 23 May 2002 13:25:50 +0200
Subject: [Doc-SIG] [development doc updates]
References: <714DFA46B9BBD0119CD000805FC1F53B01B5B32F@UKRUX002.rundc.uk.origin-it.com>	<3CEB686E.8050502@livinglogic.de> <15596.19858.958676.198267@grendel.zope.com>
Message-ID: <3CECD1BE.3030405@livinglogic.de>

Fred L. Drake, Jr. wrote:
> Walter D=F6rwald wrote:
>  > The table solution seems rather fragile.
>  >
>  > Why not use something like this:
> [example elided]
> 
> Using CSS works well enough with the most modern & up to date
> browsers, but many users don't update as aggressively as I do, and are
> using older browsers.  My boss, for instance, uses Netscape
> 4.something, which doesn't do well with even moderate CSS. There are
> enough browsers out there that either don't implement all the
> specifications, or don't get all the corner cases right, that CSS is
> still only acceptable for "detailing", not for substantial
> presentational control.

Even Netscape 4.7 gets the text-indent/margin-left right (but not
much else :-/). And for a browser that does not support it, it
should degrade gracefully.

> Now, we can definately be more aggressive with CSS for HTML that will
> be converted to HTML Help in future releases, but that's only because
> we don't expect the standards support to vary in that application.
> User-selected browsers on the open Web are a different world.
> 
>  > An example how this might look can be found at
>  > http://www.livinglogic.de/Python/xist/converters/index.html
>  > (scroll down to the Converter constructor)
> 
> Nice!

... and automatically generated from XML docstrings.

Bye,
    Walter Dörwald




From lolita86@libero.it  Thu May 23 18:25:03 2002
From: lolita86@libero.it (lolita)
Date: Fri, 24 May 2002 00.24.56 +0200
Subject: [Doc-SIG] Eros e soldi:guadagna con internet 0,08 euro a clic
Message-ID: 

sono lolita=2C voglio presentarti il mio nuovo sito
affiliazione gratuita con guadagni immediati=3A         erotismo=2C chat=2Cloghi e sonerie etc=2C etc=2C 


l'unico sito che paga cos=EC tanto 0=2C08 euro a clic =2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2Eguarda bene la pg di affiliazione=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2E=2Ee buon divertimento=2E
 

visita il sito=3A         http=3A=2F=2Fmembers=2Exoom=2Eit=2Fmarym1976       http=3A=2F=2Fmembers=2Exoom=2Eit=2Fmarym1976       http=3A=2F=2Fmembers=2Exoom=2Eit=2Fmarym1976         
 
         
 
    
 










From goodger@users.sourceforge.net  Thu May 30 04:08:41 2002
From: goodger@users.sourceforge.net (David Goodger)
Date: Wed, 29 May 2002 23:08:41 -0400
Subject: [Doc-SIG] Updates to Docutils
Message-ID: 

I've just checked in a bunch of changes to Docutils.  The biggest change was
the addition of a command-line interface to the front-end scripts.  Greg
Ward's Optik package is now required (http://optik.sf.net/).

I added ``docutils.frontend`` to support command-line processing of
front-end scripts (which are now down to 3 lines each).  The
``docutils.core.Publisher`` class and ``publish`` function have been greatly
simplified by the use of Optik.

Download the latest snapshot from:

    http://docutils.sf.net/docutils-snapshot.tgz

The sandbox snapshot is also available:

    http://docutils.sf.net/docutils-sandbox-snapshot.tgz

-- 
David Goodger    Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/