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

Re: [Doc-SIG] reStructuredText inline markup
by Ueli Schl�pfer Oct. 31, 2001

Oct. 31, 2001

Alan Jaffray <jaffray(a)pobox.com> writes: > In the current reStructuredText specification, inline markup can't be > nested and is not extensible. IMHO this is a problem. > > Nesting is needed in some very simple cases:: > > Most recent interpretation of the Second Amendment has been based > on `*USA vs. Miller* (1939)`__. > > __ http://caselaw.lp.findlaw.com/scripts/getcase.pl?court=us&vol=307&invol=174 > I'll keep out of this battle -- but you should find plenty of material in the archive. > Extensibility beyond the current "roles" mechanism is also necessary. > For example, one of my intended applications for rST currently has a > frequently-used tag to refer to another user of the system:: > > I had lunch with <lj user="tikva" text="Rachel"> today. > > It's a nice semantically meaningful output-format-neutral element. > I don't know how I'd do something equivalent in rST. If it weren't > inline, I'd use a directive, and if it didn't have an argument, I'd > use a role, but as it is, I think I'm stuck. [...] Doesn't the current spec_ cover your wishes better than you seem to think? The spec says clearly that the role may be prefix or postfix, and that the interpretation is domain-dependent. .. _spec: *reStructuredText Markup Specification*, CVS version 1.22 of 2001/10/27 So nothing should keep you from supplying your own handler for the ``lj`` role and write:: I had lunch with `text=Rachel user=tikva`:lj: today. That's not more obtrusive than your example, :: I had lunch with <lj user="tikva" text="Rachel"> today. or is it? And it would be entirely up to you to use some mail-header inspired quoting mechanism, i.e.:: I had lunch with `Rachel <tikva>`:lj: today. All that you'd need to do in this case is to write a layer that interfaces with the rfc822 module! (Actually, to me this looks like a nice solution for your case, but there are obvious limits as to how much data you can stuff inline without getting something very obtrusive.) > I had lunch with `Rachel`{lj user=tikva} today. > > My guess is that most non-markup uses for braces are in programming > language examples, and most of those will be in literal blocks or > inline literals or interpreted text, so stealing the braces won't > lead to too much extra escaping. > > The other problem is that lots of inline markup is obtrusive and ugly:: > > I had lunch with `Rachel`{lj user=tikva icon="badger.png"} today. > > If we think of these as inline directives, we can steal a play from > the hyperlink book, and drag the role out-of-line:: > > I had lunch with `Rachel`{_} today. > > .. _Rachel: {lj user=tikva icon="badger.png"} How about:: I had lunch with `Rachel`_ today. .. _Rachel: .. lj:: user=tikva icon="badger.png" I'm not sure about the idented directive -- I could find no explicit exclusion, so I assume that it is correct syntax. But is it necessary, or would this do as well (similar to multiple targets for a hyperlink):: I had lunch with `Rachel`_ today. .. _Rachel: .. lj:: user=tikva icon="badger.png" > There's even the possibility of:: > > I had lunch with `Rachel`{__} today. > > __ {lj user=tikva icon="badger.png"} > [...] Just my 2 cents, Ueli

5 6

[development doc updates]
by Fred L. Drake Oct. 30, 2001

Oct. 30, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Re-arranged the material in Chapter 2 (built-in things) to make it easier to start off with. Functions come before Types and Exceptions, and file objects are promoted one level in the outline, making them easier to find (they now appear in the table of contents instead of being hidden in the "Other Objects" category).

1 0

reStructuredText inline markup
by Alan Jaffray Oct. 29, 2001

Oct. 29, 2001

In the current reStructuredText specification, inline markup can't be nested and is not extensible. IMHO this is a problem. Nesting is needed in some very simple cases:: Most recent interpretation of the Second Amendment has been based on `*USA vs. Miller* (1939)`__. __ http://caselaw.lp.findlaw.com/scripts/getcase.pl?court=us&vol=307&invol=174 Extensibility beyond the current "roles" mechanism is also necessary. For example, one of my intended applications for rST currently has a frequently-used tag to refer to another user of the system:: I had lunch with <lj user="tikva" text="Rachel"> today. It's a nice semantically meaningful output-format-neutral element. I don't know how I'd do something equivalent in rST. If it weren't inline, I'd use a directive, and if it didn't have an argument, I'd use a role, but as it is, I think I'm stuck. The extensibility problem is relatively easy to address if you allow attributes or arguments in roles:: I had lunch with :lj user=tikva:`Rachel` today. But to me, that syntax looks confusing. I was never too fond of the `` :rolename:`text` `` syntax in the first place, and adding spaces makes it more confusing. I'd like to get something more block-looking to go around the rolename and arguments. I'd also like to require that it be postfix, both for simplicity, and to follow the general principle that the text should be primary and the way it's marked up should be an aside. :: I had lunch with `Rachel`{lj user=tikva} today. My guess is that most non-markup uses for braces are in programming language examples, and most of those will be in literal blocks or inline literals or interpreted text, so stealing the braces won't lead to too much extra escaping. The other problem is that lots of inline markup is obtrusive and ugly:: I had lunch with `Rachel`{lj user=tikva icon="badger.png"} today. If we think of these as inline directives, we can steal a play from the hyperlink book, and drag the role out-of-line:: I had lunch with `Rachel`{_} today. .. _Rachel: {lj user=tikva icon="badger.png"} There's even the possibility of:: I had lunch with `Rachel`{__} today. __ {lj user=tikva icon="badger.png"} I'm not sure about nesting. Some cases are easy, but any time you have two constructs that involve backquotes, problems will ensue because backquotes don't nest. But backquotes are a really nice unobtrusive delimiter for sections of text, and it'd be a shame to replace them with braces or angle brackets or something. I have some bad ideas. Anyone have some good ideas? Alan

1 0

font change in the development version of the docs
by Tavis Rudd Oct. 26, 2001

Oct. 26, 2001

Hi, I've just noticed that the font used to list module names, source snippets and method/function names has been changed in the devel version of the docs. IMHO, the old font was much more readable. Also, will this change affect the output from the mkhowto script? If it will there should be an option to use the original fonts. Cheers, Tavis

1 0

How to traverse a document object
by Paul Moore Oct. 26, 2001

Oct. 26, 2001

I don't know if I'm missing something stupidly obvious here... I want to traverse a document generated by a dps.parsers.restructuredtext.Parser instance. I can see no way of doing so short of a manual tree-walk with type checks all the way - you know:: if type(current_node) == section: # process a section, probably recursing on its children elif type(current_node) == paragraph: # process a paragraph # etc, ad nauseam. This *can't* be the correct way of doing this. The example code in the tools directory isn't any help, as it builds on the asdom() method, which does the trick "for free". I tried looking at the xml.dom module, but that didn't offer anything that immediately leapt out at me as a suitable "visitor" interface. But I'm not familiar with XML, so I'm probably missing something. But IMHO, there *must* be a simple way of traversing the document model. At the moment, I can't see it. Can someone enlighten me? (Or if there isn't one, surely it needs implementing - and as it may well need support from the classes in nodes.py, I'd imagine it needs adding sooner rather than later?) As I say, I'm convinced I've missed something fundamental here... Paul.

4 20

inline hyperlink targets
by David Goodger Oct. 26, 2001

Oct. 26, 2001

While working on the outline of doctree.txt_, I wanted to categorize the elements. My first try was with a nested list structure:: - Root element: document_ - Body elements: - General body elements: paragraph_, literal_block_, block_quote_, doctest_block_, table_, figure_, footnote_ - Lists: bullet_list_, enumerated_list_, definition_list_, field_list_, option_list_ But I wanted to be able to refer back to each item from other parts of the document. That made me change the structure to one of nested sections:: Root Element ============ document_ Body Elements ============= General Body Elements --------------------- paragraph_, literal_block_, block_quote_, doctest_block_, table_, figure_, footnote_ Lists ----- bullet_list_, enumerated_list_, definition_list_, field_list_, option_list_ This solution rankles. Why let the markup determine the structure of my writing? That's backwards. But the best I could do with the current syntax would be to include a bunch of hyperlink targets. And in order not to break up the list, the targets would have to be inside the list items:: - .. _root element: Root element: document_ - .. _body element: Body elements: - .. _general body elements: General body elements: paragraph_, literal_block_, block_quote_, doctest_block_, table_, figure_, footnote_ - .. _lists: Lists: bullet_list_, enumerated_list_, definition_list_, field_list_, option_list_ Very awkward. Then I came up with the idea of allowing explicit hyperlink targets as inline markup:: - _`Root element`: document_ - _`Body elements`: - _`General body elements`: paragraph_, literal_block_, block_quote_, doctest_block_, table_, figure_, footnote_ - _`Lists`: bullet_list_, enumerated_list_, definition_list_, field_list_, option_list_ This seems to work. It can be rationalized as a natural consequence of the rest of reStructuredText's hyperlink syntax. I have two concerns: - This markup seems a little too noisy at first. But that may be because it's coming at the beginning of a list item, and is followed by a colon (which is *not* part of the markup). An example in the middle of a paragraph helps to alleviate this concern:: The _`quick brown fox` jumped over the lazy dog. - Should the backquotes be required, even for single-word targets? Initially I'd say yes, because leading-underscore terms are so common in code, and in the documentation of said code as well. Trailing-underscore terms are much less common. -- 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

[development doc updates]
by Fred L. Drake Oct. 26, 2001

Oct. 26, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Yet another experimental change to the presentation -- ditch the proportional font for code since some displays (especially interactive sessions and tabular displays) get messed up with proportional fonts. We do try to use monospaced fonts that are less ugly than Courier. As before, feedback on the fonts is welcome at python-docs(a)python.org.

1 0

[development doc updates]
by Fred L. Drake Oct. 25, 2001

Oct. 25, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Experimental stylesheet changes -- code is now presented using proportional fonts (mostly since Guido really dislikes Courier). Please send comments on this change to me at python-docs(a)python.org.

1 0

Representation of Horizontal Rules
by David Goodger Oct. 25, 2001

Oct. 25, 2001

[Excerpted from the new file `DPS Document Tree Structure`__, which I've just begun. It will be on the web site once the snapshot is taken tonight. Not much in it yet though. __ http://docstring.sourceforge.net/spec/doctree.txt I'm leaning towards solution #2. Those of you working with the document tree, writing code or style sheets, please let me know if this will cause problems beyond minor revisions.] Having added the "horizontal rule" construct to the reStructuredText spec, a decision has to be made as to how to reflect the construct in the implementation of the document tree. Given this source:: Document ======== Paragraph -------- Paragraph The horizontal rule indicates a "transition" (in prose terms) or the start of a new "division". Before implementation, the parsed document tree would be:: <document> <section name="document"> <title> Document <paragraph> Paragraph -------- <--- error here <paragraph> Paragraph There are several possibilities for the implementation. 1. Implement horizontal rules as "divisions" or segments. A "division" is a title-less, non-hierarchical section. The first try at an implementation looked like this:: <document> <section name="document"> <title> Document <paragraph> Paragraph <division> <paragraph> Paragraph But the two paragraphs are really at the same level; they shouldn't appear to be at different levels. There's really an invisible "first division". The horizontal rule splits the document body into two segments, which should be treated uniformly. 2. Treating "divisions" uniformly brings us to the second possibility:: <document> <section name="document"> <title> Document <division> <paragraph> Paragraph <division> <paragraph> Paragraph With this change, documents and sections will directly contain divisions and sections, but not body elements. Only divisions will directly contain body elements. Even without a horizontal rule anywhere, the body elements of a document or section would be contained within a division element. This makes the document tree deeper. This is similar to the way HTML treats document contents: grouped within a <BODY> element. 3. Implement them as "transitions", empty elements:: <document> <section name="document"> <title> Document <paragraph> Paragraph <transition> <paragraph> Paragraph A transition would be a "point element", not containing anything, only identifying a point within the document structure. This keeps the document tree flatter, but the idea of a "point element" like "transition" smells bad. A transition isn't a thing itself, it's the space between [#]_ two divisions. .. [#] Cool song by Dave Matthews. First time I heard it, I thought it was Peter Gabriel. Matthews' voice on this song sounds uncannily like Gabriel's, and the style & lyrics wouldn't be out of place either. Totally off topic. -- 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 3