Mailman 3 December 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

Docbook "user exit"?
by Ng Pheng Siong Dec. 31, 2001

Dec. 31, 2001

Hi, I'm writing my second Python programming HOWTO in Docbook. Naturally, my Docbook file contains fragments of Python code. There exist neat Python code colourisers and I want to use one of these on my docu to produce prettier output. Is there a "user exit" mechanism in Docbook to allow me to call said code colouriser? I'm invoking Jade thusly: jade -V nochunks -d /.../html/docbook.dsl f.docbook > f.html TIA. Cheers. (I'm not subscribed to either list. Please cc replies. Thanks.) -- Ng Pheng Siong <ngps(a)netmemetic.com> * http://www.netmemetic.com

3 6

Re: support for translations in reStructuredText
by David Goodger Dec. 30, 2001

Dec. 30, 2001

thomas(a)co-buero.de recently wrote to me: > Hello, > > I'm thinking about multilingual texts, where the source for every language > will be in one source file. I would like to know, wether > there exist some type of > markup in reStructuredText, which could support something like this (which I > would love to have for example in MoinMoin to support > multilanguage Wikis). > > To explain, what I mean, take a look at this example: > > ----------- > > :lang:en > > Headline > {de}Überschrift > =============== > > This is the first line of the first paragraph. > {de} Dies ist die erste Zeile des ersten Paragraphen. > {sp} .... > > {de} Diese Zeile gibt es nur auf Deutsch > > {en} This line exists only in english language. > > ---- > > For output this text should be rendered according to user preferences, > showing only the language best matching the users skills. > > > I'm sorry in case this is not the right place to discuss this topic and in > this case would be glad to know about the right one. > Thank You, > Thomas Kalka Hi Thomas, Doc-SIG is the best place to discuss this topic. I don't think anybody has addressed multilingual texts in reStructuredText yet, so the field is wide open. I don't see any reason why it cannot be done, with a little bit of work. When I worked for an SGML data processing company in Tokyo, I dealt with multilingual documents. We would receive a document in one language (typically English) and prepare it for translation (by professional translators) into one or more other languages. The solution we came up with involved marked sections. I wrote a program (in my Perl days) which was fed the document and a description of the translation unit granularity (typically, paragraph-equivalent elements). Given an original text like:: This is a paragraph in English The program would produce something like this (may be syntax errors):: <![ %english; [ This is a paragraph in English ]]> <![ %chinese; [ ]]> The translators would fill in the "%chinese;" section, using & rearranging any inline tags present. When processing, we would set the "english" parameter entity to "INCLUDE" to get the English version, or set "chinese" to "INCLUDE" to get the Chinese version (default for parameter entities was "IGNORE"). This data-level approach was moderately successful. There wasn't time or budget for any kind of tool-level support. I don't know what the state of the art in multilingual applications of XML/SGML is now, but I could imagine a similar approach for a reStructuredText document. A directive would do the trick:: .. language:: en This section of the document is in English. .. language:: fr Ceci est en francais. A bunch of pre-defined language directives would also do fine: ".. en::", ".. fr::", ".. de::", ".. jp::", etc. These directives would act on all following text up to the next such directive: simply keep the text if it's the desired language, or discard it if not. You would have to choose the granularity level to suit your data & application. I think a paragraph-level translation unit is appropriate for most cases. I wouldn't want to interleave sentences of different languages in a single paragraph: too confusing. Section-level granularity might be better for some documents, or document-level granularity (the entire English version, followed by the entire German version, etc.). Some kind of editor-level support could also be very useful. Perhaps a minor mode for the hypothetical emacs reStructuredText mode? There hasn't been any progress with reStructuredText/DPS/DocUtils of late, due to a convergence of factors (busy at work; busy at home; holidays). But I do intend to get back to them soon. The projects are hibernating temporarily, and will be revived shortly. -- David Goodger goodger(a)users.sourceforge.net 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

[development doc updates]
by Fred L. Drake Dec. 28, 2001

Dec. 28, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ A variety of updates made since Python 2.2 was released.

1 0

[development doc updates]
by Fred L. Drake Dec. 28, 2001

Dec. 28, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ The "maintenance version" of the Python documentation on the Python development site at SourceForge has been updated to show the docs being developed for Python 2.2.1.

1 0

Documentation for Python 2.2.1
by Fred L. Drake, Jr. Dec. 28, 2001

Dec. 28, 2001

I've brought the docs in Python's release22-maint branch up to date with the corrections that have been made on the trunk. I'll be checking in relevant additions to this branch as well as the trunk when I make the trunk changes. When anyone else makes a change on the trunk which should also be made on the 2.2 maintenance branch, feel free to check it in in both places, or add a note to the checkin message noting that it should be made on the branch as well, and I'll try to make sure that gets done. The 2.2 maintenance branch has replaced the 2.1 maintenance branch as the "maintenance version" at http://python.sourceforge.net/; if anyone thinks we should continue to offer the 2.1 maintenance docs there, please let me know. I don't think we have a Patch Czar for 2.2.1 yet; if anyone would like to take that duty for the documentation tree, I'd certainly appreciate the help! Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

(no subject)
by thomas＠co-buero.de Dec. 24, 2001

Dec. 24, 2001

1 0

[development doc updates]
by Fred L. Drake Dec. 18, 2001

Dec. 18, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Added documentation for pydoc. Misc. other fixes.

1 0

[development doc updates]
by Fred L. Drake Dec. 15, 2001

Dec. 15, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Miscellaneous minor updates/fixes post 2.2c1.

1 0

[maintenance doc updates]
by fdrake＠beowolf.digicool.com Dec. 15, 2001

Dec. 15, 2001

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

1 0