Mailman 3 February 2002 - 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

docutils teaser
by David Goodger March 6, 2002

March 6, 2002

I've made a lot of progress on my HTML Writer. Everything works, if crudely at times. I don't have time to check in the files to CVS right now, but here's a teaser. Check out these documents: - http://structuredtext.sourceforge.net/spec/test.html (published from source at http://structuredtext.sourceforge.net/tools/test.txt) - http://structuredtext.sourceforge.net/spec/reStructuredText.html (published from source at http://structuredtext.sourceforge.net/spec/reStructuredText.txt) They're temporary, so don't bother linking to them. There will be permanent versions soon. -- 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

2 1

some ideas for reStructuredText & document model
by David Goodger March 4, 2002

March 4, 2002

Looking at the recent HTML output, I've had some ideas regarding changes to the reStructuredText syntax and the Docutils document model. Please comment on any or all. Thanks. - Change footnote syntax from ``.. [1]`` to ``_[1]``? Has this been discussed before? Rationale: The footnote is the only explicit markup construct that directly translates to a visible body element. I've always been a little bit uncomfortable with the ``.. `` marker for footnotes because of this (we once said that ``.. `` implied "hidden"; it would be nice if that were uniformly true). And the leading underscore syntax (dropped because ``.. _[1]`` was verbose) is a useful reminder that it's a kind of hyperlink target. Time for another break from StructuredText? Example, current syntax:: .. [GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ Proposed new syntax:: _[GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ Note that the body of the footnote need not be indented. - Differentiate author-date "citations" (``[GVR2002]``) from numbered footnotes? Create a new set of DTD elements: "citation" and "citation_reference"? Citations could be treated differently from footnotes. Footnotes could be rendered something like this:: | 1. This is a footnote. The brackets could be dropped | from the label, and a vertical bar could set them | off from the rest of the document in the HTML. If | converted to endnotes (by a directive/transform), | a horizontal half-line might be used instead. | Page-oriented output formats would retain the | horizontal line. And citations would look like this:: [GVR2001] Python Documentation; van Rossum, Drake, et al.; http://www.python.org/doc/ - Render footnote references as superscripts without "[]"? (But only if we differentiate numerical footnotes from textual citations.) - Make footnotes two-way, GNU-style? What if there are multiple references to a single footnote? - Directive ideas: TOC (GNU-style two-way), endnotes *here*, citations *here*. - Add a list of pending transforms to the document node, generated by directives? Or add an element, "pending" perhaps, which encapsulates the transform, the point at which to apply it, and any data required. - Add a "sidebar" element to the DTD? Like a generic admonition or floating mini-section. Useful for TOC, system messages section, abstract, etc. - Add character processing? For example: - "--" -> em-dash (or "--" -> en-dash, and "---" -> em-dash) - convert quotes to curly quote entities - various forms of ":-)" to smily icons - others? How to represent entities in the text though? Unicode? -- 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

3 6

Field lists for directive attributes?
by David Goodger Feb. 28, 2002

Feb. 28, 2002

reStructuredText's image and figure directives currently use a specialized "[name=value]" attribute specification syntax:: .. image:: picture.png [height=100 width=200 scale=50 alt="alternate text"] There's a mini-parser called "dps.utils.parseattributes". It does a decent job, but it can't handle complex stuff like:: [alt="Joe \"Bulldog\" O'Roarke"] I'm thinking of replacing the "[name=value]" syntax with field lists for attributes:: .. image:: picture.png :height: 100 :width: 200 :scale: 50 :alt: alternate text Advantages: standard syntax (less to remember), easier implementation, more straightforward, more robust, more flexible, emphasizes role of field lists as "extension/specialized syntax" (as currently used in bibliographic field lists and the "meta" directive). Disadvantage: more verbose. It seems useful to standardize on a single syntax, which may be used in other directives in the future. Throwing away the current system and reusing field lists appeals to me on minimalistic principles. Any objections or alternate ideas? -- 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

2 2

Support for translators
by Fred L. Drake, Jr. Feb. 8, 2002

Feb. 8, 2002

There have been a number of attempts to create mailing lists for translators, and organize translation efforts. At least some lists have disappeared as people change jobs and their old employers drop support for the mailing lists run on their servers. Knowing what efforts are active can also be difficult. I'd like to hear if translators think having a stable list hosted on python.org would help. We can set up either a single list for organizing translation efforts or lists for languages with many translators, if needed. (Large, organized efforts may be better served by SourceForge projects.) I'd also like to find a volunteer interested in maintaining an up-to-date list of translation efforts, whether the efforts are individual or organized group efforts. If you're interested in volunteering, please send email to python-docs(a)python.org. Suggestions for alternative approaches or additional ways to help should be sent to the Doc-SIG mailing list. Please feel free to forward this message to people you feel may be interested in helping out who are not on the Doc-SIG mailing list! Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

Support for non-English-speaking users
by Fred L. Drake, Jr. Feb. 8, 2002

Feb. 8, 2002

Currently, there is a single Web page at python.org which provides links to non-English resources: http://www.python.org/doc/NonEnglish.html This page includes entries for 18 different languages (at the moment), including many which aren't served well by the default Latin-1 encoding for the Web page containing the list. We've gotten by so far because most of the descriptions are written in English, which doesn't make a lot of sense for the target audience. What I'd like to do is get a group of voluteers to maintain a set of pages, one for each language, written in the same language as the resources being described. Each page could use the most appropriate character set, and the page at the current URL would be replaced with the index the language-specific pages. I'd like one volunteer to help coordinate the effort and make the actual changes to the site. This person would have write-access to the CVS repository which contains the python.org pages. [I proposed something similar a couple of years ago, but the matter was somewhat less pressing at the time, and I was better able to manage the current list of translations myself. There are now more pressures on my time and it has become easier to support volunteers to help maintain python.org.] If you're interested in volunteering, please send email to python-docs(a)python.org. Suggestions for alternative approaches or additional ways to help should be sent to the Doc-SIG mailing list. Please feel free to forward this message to people you feel may be interested in helping out who are not on the Doc-SIG mailing list! Thanks! -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

DPS & reStructuredText updated
by David Goodger Feb. 6, 2002

Feb. 6, 2002

I've been adding features lately. Latest snapshots available in 90 minutes from: http://docstring.sourceforge.net/dps-snapshot.tgz http://structuredtext.sourceforge.net/rst-snapshot.tgz New: - A "Visitor" pattern to the doctree (dps/nodes.py). - Functional "Reader" (dps/readers/standalone.py; thanks Ueli!). - Minimal "Writer" (dps/writers/pprint.py). - Reworked system_warning/Reporter mechanism with log4j influence. - A bunch of transforms (dps/transforms/). I'd like to add a bit more functionality (such as access from tools/quicktest.py or some other front-end, plus a simple HTML writer) and update the PEPs, then I'll make and announce new releases (v0.4 of each). Following this, I'll merge the parser into the DPS project; there's too much duplication in the test code now. The project will be renamed to "docutils" as well. -- 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