Mailman 3 July 2001 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

小泉内閣支持不支持緊急アンケート
by メールアンケート事務局 July 28, 2001

July 28, 2001

小泉内閣　支持・不支持　緊急アンケートお忙しいところ、ご迷惑をおかけしますが、下のURLをクリックして、アンケートにご協力お願いいたします。 http://211.9.37.210/koizumi/koizumi_an.asp?id=530263

1 0

usage docstrings and bibliographic field lists
by Garth Kidd July 27, 2001

July 27, 2001

I think we need to support field list option 3 (``reStructuredText.txt`` revision 1.1.1.1 line 478) to support PEP-0257 style usage docstrings in Python scripts without preventing script authors from specifying bibliographic field lists. Background: The reStructuredText spec supports field lists of RFC-822 style headers:: Special case: use unadorned RFC822_ for the very first or very last text block of a docstring:: """ Author: Me Version: 1 The rest of the docstring... """ Note that it says *docstring*, not *document*. :) Later, the spec says:: One special context is defined for field lists. A field list as the very first non-comment block, or the second non-comment block immediately after a title, is interpreted as document bibliographic data. No special syntax is required, just unadorned RFC822_. The first ... Making the least effort to eliminate ambiguity, I come up with: * When using reStructuredText in docstrings, you can have as many field lists as you like, in any docstring, so long as they're either the first or last block in the docstring. - In a document, you can have only two: one at the beginning, and one at the end. * A field list as the first non-comment block in a document becomes ``document bibliographic data``. - In docstrings, this becomes tricky. To me, it ends up saying that a field list at the top of the *first docstring* (the second if the first is a title) becomes bibliographic data for the file. PEP-0257 says:: The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function ... To cut a long story short, when these two lock horns it looks like we can't have reStructuredText bibliographic field lists in scripts because otherwise the script couldn't print its usage with a simple ``print __doc__``. If by this point you've already figured out how to resolve the issue by straightening out wording in the spec, not changing any code, please let me know. :) The simplest fix I can see is to accept the previously-rejected "option 3" of a ``fields`` directive:: .. fields:: If specified, it would signal to the parser that the next text block was a field list, not a paragraph. Furthermore; if it was the first field list in the document (ie there wasn't one at the top), the field list would be treated as bibliographic data. The ``fields`` directive would not be required for field lists at the beginning or end of a document or docstring. We might generate a warning. Regards, Garth. PS: The usage for many scripts looks like this:: """\ Usage: cvs [cvs-options] command [command-options-and-arguments] where ... """ Perhaps we should suppress recognition of bibliographic field lists without generating warnings if the first field name seems to be ``Usage``.

1 0

[development doc updates]
by Fred L. Drake July 23, 2001

July 23, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Various minor updates.

1 0

reStructuredText release 0.3 posted
by David Goodger July 23, 2001

July 23, 2001

Release 0.3 of the reStructuredText input parser (a component of the Python Docstring Processing System) has been posted to the web site, http://structuredtext.sourceforge.net. Quick link to the download: http://prdownloads.sourceforge.net/structuredtext/rst.0.3.tar.gz Most syntax constructs have been implemented, but there is no front-end yet. The project files are now accessible via CVS; I will be making regular checkins. Thanks to Garth Kidd for his pushing and prodding. If you would like to be added as a developer, please let me know. -- David Goodger dgoodger(a)bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

1 0

Docstring Processing System release 0.3 posted
by David Goodger July 23, 2001

July 23, 2001

Release 0.3 of the Python Docstring Processing System (DPS) has been posted to the web site, http://docstring.sourceforge.net. Quick link to the download: http://prdownloads.sourceforge.net/docstring/dps.0.3.tar.gz Lots of progress has been made, driven by the reStructuredText parser. The project files are now accessible via CVS; I will be making regular checkins. Thanks to Garth Kidd for his pushing and prodding. If you would like to be added as a developer, please let me know. -- David Goodger dgoodger(a)bigfoot.com Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net

1 0

Comments within lists
by Garth Kidd July 21, 2001

July 21, 2001

DISCLAIMER: I only just checked back and noticed that there was a particular DTD the output should conform to. Cool, but this message might be redundant when I finally read the DTD. Or maybe not. <laughter> It just occurred to me that we could well end up producing an "edge cases" appendix to the reStructuredText specification by pulling reStructuredText docstrings out of the unit tests for the parser. :) Anyway, on with the story. This input:: A paragraph. .. A comment with two paragraphs. Yep. Another paragraph. ... should render to XML as something like:: A paragraph. <comment> A comment with two paragraphs. Yep. </comment> Another paragraph. ... so a single-paragraph comment, for consistency:: <comment> A comment with two paragraphs. </comment> ... and a comment between two paragraphs in a list item:: <bullet_list> <list_item> The first paragraph of the list item. <comment> A comment with two paragraphs. Yep. </comment> Another paragraph. </list_item> </bullet_list> I'm asking because I wanted to drop a comment in the middle of a list, and it occurred to me that I didn't want to break the spec any more than I wanted to break the list. What I ended up with was a little odd: A paragraph. .. A comment between two paragraphs. Another paragraph. .. A comment between a paragraph and a list. 1. List item 1. .. A comment between list items 1 and 2. 2. List item 2. The second paragraph of list item 2. .. A comment between two paragraphs in list item 2. 3. List item 3. .. A comment between a list and a paragraph. The last paragraph. List item 2 is the scorcher. To be consistent with comments between paragraphs in column 0, comments within list items must be at the same indent level as the paragraphs (if any) around them. That implies that comments between list items must be at the same indent level as their tags or bullets, hence the above. Hmmm:: .. this is a comment this is the comment's second line How is that rendered? One ``<comment>`` tag containing two paragraphs? Two comment tags containing a paragraph each? One comment tag containing three lines of CDATA of which one is blank? Regards, Garth. PS: Something tells me I'm going to have a lot of fun writing test cases. :/

3 2

RE: reStructuredText
by Garth T Kidd July 21, 2001

July 21, 2001

>> Given that there's no parser yet, I suppose now is a good time to >> consider Wiki markup requirements and how they might be added as >> extensions or incorporated into the specification? > > I'm not a Wiki user, so I don't know what special Wiki > requirements might look like. Can you elaborate? See QuickWikiBackground_ below for a quick background on what the hell Wiki is. Skip to WikiModificationsToReStructuredText_ if you just want to find out what modifications might be required to the reStructuredText specification. Just for a play, I'm going to try writing this mail in reStructuredText. .. _QuickWikiBackground: QuickWikiBackground =================== Wiki fans, my apologies if any of this is a tad confrontational or bordering on flamebait [FlameFlame]_. I'm in a hurry. :/ A Wiki is a web-based content management system that makes buiding web sites as easy as tunnelling with a magic shovel. Three key reasons for this ease of use are: * Wiki is brower based, * Most of what you type in will display properly, and * You create links with WordsOfManyCapitalLetters [7]_. If I'd typed that into a Wiki, what I'd get when I hit the Submit would be some normal text, a bullet list, and a link called WordsOfManyCapitalLetters. If I clicked on it, I'd be fed the edit form for a newly created WordsOfManyCapitalLetters page. .. _[7]: Properly called WikiNames. .. _[8]: Purists might want blank lines between those, but I want this to be as close to copy-and-paste from email as I can get it. .. _[9]: I first noticed the need for automatic footnote numbering in footnote [1]_. Now I've finally hit the tangle. I've also just noticed that if I were rendering this for printing I'd want a different format for the explicit link to the footnote -- specifically, not a subscript. .. _[FlameFlame]: This document has so much markup and so many bloody footnotes [cough]_ it'll be a miracle if anyone manages to read far enough to find anything worth flaming. If I referred to DocstringProcessingSystem, that'd become a link, and if I clicked on it I'd be editing the DocstringProcessingSystem page. Creating a new Wiki has so little friction the process can become a non stop brain dump. I created 150+ pages on a ZWiki in spare time between meetings in a week. I'm sure others have done more. To have a play with a Python-based Wiki, check out MoinMoin_. My biggest problem with MoinMoin is that the default markup drives me nuts (sorry, Jurgen). I have some other issues (see BlogBlog_ [LameLame]_), but my biggest source of angst is probably the parser issue. MoinMoin supports plug-in parsers, but none of them grab me yet. See below. I'm slightly more comfortable with the markup used in ZWiki_, which is heavily based on StructuredText. StructuredText has its own problems, though. In short, it's bloody unpredictable. StructuredTextNG might fix it, and the BizarStructuredText plug-in contributed to MoinMoin by RichardJones [1]_ reStructuredText_ seems a lot cleaner to me than either StructuredText or WikiWiki markup. I have marginal concerns about how "normal" people will cope with the underscore suffix [2]_ for links, but my reading of the spec was pleasant enough. What I'd like to do is develop a reStructuredText plug-in parser for MoinMoin, also one for MoinWiki:BlogBlog [3]_ (which I've decided is going to pre-parse pages to XML for various reasons) .. _MoinMoin: http://moin.sourceforge.net/cgi-bin/moin/moin/ .. _BlogBlog: http://moin.sourceforge.net/cgi-bin/moin/moin/BlogBlog .. _ZWiki: http://zwiki.org/FrontPage .. _[LameLame]: I've been promising to finish work on a Wiki clone for years now. I did some work on ZWiki modifications (NooZWiki), which was fine until I got sick of a) edit conflict error handling in Zope, and b) the incredible costs of Zope posting at the time. I'm now caught between extending MoinMoin to suit my purposes -- it's really quite amazing -- or writing my own. I sympathise with anyone tempted to consider me a mere meddling troublemaker until I finally cough up some code. .. _NooZWiki: http://zwiki.org/NooZWiki .. _reStructuredText: http://structuredtext.sf.net .. _[1]: As you can see, automatically dropping in WikiNames is an easy habit to fall into -- you'll find yourself doing it accidentally in email. Whilst I'm in a reStructuredText footnote, however, surely they should be automatically numbered? [9]_ .. _[2]: The problem is that the underscore becomes a prefix when finally pointed. If it's confusing me, it's definitely going to confuse my users. They're going to have enough trouble just with .. `identifier`: URL. Is this another paragraph in the [2]_ footnote, or is this in the main text? .. _[3]: This is an example of an InterWiki_ link, a streamlined way of pointing to a particular page at another known Wiki. .. _InterWiki: http://moin.sourceforge.net/cgi-bin/moin/moin/InterWiki .. _WikiModificationsToReStructuredText: Pant. Wheeze. This is hard work. Especially the footnotes. WikiModificationsToReStructuredText [4]_ [5]_ =================================== Wiki would need the following from reStructuredText: * Suddenly, there's markup that doesn't look like punctuation. WikiName might well end up being a link. * As written, a reStructuredText document will always parse the same way. Once you introduce WikiNature, it'll parse differently depending on which other WikiNames are defined. [BlogBlogXML]_ [SickOfRememberingNumbers]_ [InternalWikiNames]_ * Square brackets are extremely useful in ZWiki markup to force a word that doesn't look like a WikiName to be treated as a link to a page of that name. For example, [David]. [10]_ * I dimly remember square brackets also being useful for an inline linking representation I don't recall from the reStructuredText markup. It's something like [here is some text: URL]. A more reStructuredText way of doing it would be something like `here is some text`:URL. [11]_ [12]_ * MoinMoin further overloads square brackets for an EXTREMELY [6a]_ useful macro system. .. _[BlogBlogXML]: ... which is why I want to preparse documents to XML in BlogBlog. <potentialWikiName>, here we come. That brings us back to predictable output, which I can then reparse to produce appropriate HTML. .. _[SickOfRememberingNumbers]: Bah! And now, I'm suddenly wondering whether underscored link destinations in reStructuredText specifically use square brackets to say "this is a footnote", or whether that's handled by the presence of non-URL text after the colon without an intervening newline. .. _[InternalWikiNames]: Wouldn't it be nice for other pages in the Wiki to be able to refer to this footnote as WhateverThisDocumentIsNamed.InternalWikiNames? .. _[4]: The `MoinMoin heading style`_ seems to have a lot to offer reStructuredText, which seems unable to do sub-headings. At least, having read the spec, I don't remember how to do it -- and the markup really has to be that simple, hence my problems with the underscores [1]_ [6]_. .. _[5]: Another confusion: should the equals signs extend all the way, or not? I hope not, otherwise users editing with proportional fonts are going to have an awful time. .. _[6]: Aha! Sometimes, you need [6a]_ to be able to explicitly target a previous footnote. Now I'm thinking "named, automatically numbered footnotes". .. _[6a]: Hang on, how do I embolden again? Suddenly, the StructuredText *embolden this* format looks lovely. `embolden this`*? *`embolden this`*? .. _`MoinMoin heading style`: http://moin.sourceforge.net/cgi-bin/moin/moin/HelpOnHeadlines .. _[10]: Some Wikis scan any word with an initial capital to see whether or not there's a page of that name, in which case you only need the square brackets to force a link to the uncreated page when you're first creating it. .. _[11]: I like the backquotes! .. _[12]: We need to also consider `here is some text`:WikiName. My brain hurts. This is harder than it looks. I should never [6a]_ have started with the footnotes. :) Regards, Garth. .. _[cough]: You are in a twisty maze of little passages, all alike.

5 15

Directive idea
by Garth T Kidd July 21, 2001

July 21, 2001

For content management systems in news organisations: .. pullquote:: This quote is so important it should be rendered nice and large somewhere near this point, but not necessarily immediately next to it. Drawing the user to the article is more important than to the specific text. Regards, Garth.

1 0

[development doc updates]
by Fred L. Drake July 20, 2001

July 20, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Some additional information for extension writers.

1 0