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

Issues with 2.1 doc PDF files
by Dinu Gherman April 27, 2001

April 27, 2001

Hello, I've just noticed that there are considerable differences between the PDF files documenting Python 2.1 and those for 2.0. Basically, these are: - file sizes are much bigger for 2.1 (50-100%) - fonts are approximated with pixelized bitmaps As a result you get: - much longer page building times in PDF readers - considerable longer search times - much longer print times (probably - haven't checked) I've not verified this for each PDF file (it's prominently obvious for the tutorial, though), but I assume the same effects can be observed for all of them, when comparing with corresponding files from the previous release. So, I'm really curious what the reason for this phenomenon could be? If there isn't any, I suggest reproducing the files to no longer show the described effects as they will definitely distract people from reading the files online and simply lead to a bad overall impression about their generation process, if not even their content. Regards, Dinu -- Dinu C. Gherman ReportLab Consultant - http://www.reportlab.com ................................................................ "The only possible values [for quality] are 'excellent' and 'in- sanely excellent', depending on whether lives are at stake or not. Otherwise you don't enjoy your work, you don't work well, and the project goes down the drain." (Kent Beck, "Extreme Programming Explained")

6 18

Re: [Doc-SIG] Issues with 2.1 doc PDF files
by Michael Hudson April 26, 2001

April 26, 2001

Guido van Rossum <guido(a)digicool.com> writes: > I would surmise that for almost everybody, HTML wins big over PDF > onscreen, and PDF wins big over HTML for printing. Soon, I bet we > won't have to distribute PostScript any more, because everyone can use > PDF for printing. Well, if I were to print out the python docs anytime soon (I'm not) I'd definitely reach for the postscript. OTOH, I'd also probably build it locally. But as long as it's not much burden to have both, it's not that much of an issue. Cheers, M. -- I have a feeling that any simple problem can be made arbitrarily difficult by imposing a suitably heavy administrative process around the development. -- Joe Armstrong, comp.lang.functional

2 1

Re: [Doc-SIG] Issues with 2.1 doc PDF files
by Michael Hudson April 25, 2001

April 25, 2001

Guido van Rossum <guido(a)digicool.com> writes: > [me] > > > I would surmise that for almost everybody, HTML wins big over PDF > > > onscreen, and PDF wins big over HTML for printing. Soon, I bet we > > > won't have to distribute PostScript any more, because everyone can use > > > PDF for printing. > > [MH] > > Well, if I were to print out the python docs anytime soon (I'm not) > > I'd definitely reach for the postscript. > > Yeah, but you're lucky to have a PS capable printer. Heck, you're > probably on Linux. Most Windows and even many Mac users don't! PDF > can be printed from anywhere. Even if your printer talks PostScript, > on Windows it's a pain to figure out how to print a PS file! AcroRead > does it for you with PDF. Oh, I know, I know. But your comment I was replying to said "Soon, I bet we won't have to distribute PostScript any more...". > > OTOH, I'd also probably build it locally. > > Lucky you. This may be news for you, but most Python users don't know > how to use those tools any more, even if they have access. Wot, typing "make ps"? <wink> I'm aware I'm hardly a typical Python user. Cheers, M. -- Those who have deviant punctuation desires should take care of their own perverted needs. -- Erik Naggum, comp.lang.lisp

1 0

Structuring: a summary; and an attempt at EBNF..
by Edward D. Loper April 23, 2001

April 23, 2001

I figured I'd give a summary of all the structuring features that I think we've agreed on, so we can tentatively take those as a given. If anyone objects, please say so.. 1. Paragraphs are left-justified and separated by blank lines. 2. Literal blocks start with a paragraph that ends with "::" and continue to the next line whose indentation is equal to or less than that of the paragraph that started them. Literal blocks should be indented and separated by blank lines. 3. Doctest blocks start with ">>> " and continue to the next blank line. Doctest blocks should be indented and separated by blank lines. 4. Lists should be indented and separated by blank lines. List items within a list don't need to be separated by blank lines. List items start with bullets, which are either "-" or a single number followed by a period, like "1." or "12.". 5. The second and subsequent lines of a list item are indented. This includes list items with multiple paragraphs, sublists, etc. 6. Sections begin with headings, which are underlined with "=", "-", or "~" (for level 1, 2, or 3 headings, respectively). 7. Colorizing takes place entirely within paragraphs, and does not interact with structuring. In my mind, the major questions left to resolve are: 1. how to do colorizing? Two main proposals: like C{this} and like `this`/*this*. 2. how to do escaping? 3. do we need any other structuring constructs (e.g., fields, directives, footnotes, etc)? If so, which ones, and how should we add them? ===== Below is my first attempt at an EBNF-like formalism for these rules. You should probably pay more attention to the "one-minute summary" above than to the rules below -- I almost certainly didn't get the rules below quite right (although if you want to point out ways that I got it wrong, please do! :) ). IND and DED are indent and dedent (by a sinlge space); I use the notation IND[n] to mean n IND tokens. Note that the rule:: x = a IND[n] b DED[n] c is really just shorthand for:: x = a y c y = IND y DED | b However, I also use the foo[n] notation in one place where it can't be simplified. That's because in list items like: - this is a list item. Here's a second paragraph. there are crossing dependancies. In particular, the IND/DED need to match up, but assuming that we want "this is a list item" to be result of a "paragraph" production, they can't. Don't worry if you don't understand what I just said, I think it should still be relatively easy to understand the EBNF below. I assume that, as part of the preprocessing, all indents/dedents have been changed to IND/DED tokens. This process ignores blank lines, which are simply reduced to be empty. ================================================================ The top-level production:: # pytext = (BlankLine NL)* # IND[n] # (Para | List | Section | DocTestBlk) # ((COLON COLON NL LitBlk) | # (NL BlankLine NL (Para | List | Section | DocTestBlk)))* # DED[n] # (NL BlankLine)* (pytext is just a convenient name, we'll probably want another) This production assumes that the first-line-might-not-be-indented problem has already been taken care of. It says that a formatted docstring consists of any number of blank lines, followed by an indented section containing at least one paragraph, list, section, or doctest block, followed by zero or more literal blocks, paragraphs, lists, sections, or doctest blocks.. And there can be extra blank lines at the end. The productions "Para", "List", "Section", etc. generally do *not* include thier trailing NL, because that makes it easier to detect paragraphs that end with COLON COLON. Some useful types of lines are: - BlankLine: consists only of spaces. - TextLine: non-blank line. - StartLine: doesn't start with a Python prompt or a bullet - ContLine: anything - EndLine: doesn't end with "::"; doesn't include trailing spaces? - StartEndLine: doesn't start with PyPrompt or Bullet, and doesn't end with "::". We can define them as:: # BlankLine = (empty) # TextLine = [^ NL IND DED]+ # StartLine = (?! PyPrompt | Bullet) TextLine # EndLine = [^ NL IND DED]* [^ NL IND DED COLON] [^ NL IND DED] | # [^ NL IND DED]* [^ NL IND DED] [^ NL IND DED COLON] | # [^ NL IND DED] # StartEndLine = (?! PyPrompt | Bullet) EndLine As I said above, paragraphs don't include the trailing newline. Paragraphs ending in "::" don't include the "::".:: # SimplePara = StartLine (NL ContLine)* EndLine | # StartEndLine Lists are indented (n>1):: # List = IND[n] LI (BlankLine+ LI)* DED[n] We need special list-starting paragraphs. These don't include trailing newlines, either:: # LS_IndPara[n] = ContLine NL IND[n] ContLine (NL ContLine)* # LS_OneLinePara = EndLine There are 3 types of list item:: # LI = LI1 | LI2 | LI3 This production gives the contents of a list item, *after* its first paragraph:: # LI_Rest = ((COLON COLON NL LitBlk) | # (NL BlankLine NL (Para | List | DocTestBlk)))+ List Item, form 1: start with a one-line pagraph, then indentation, contents, and corresponding dedents. The indentation/contents/dedent is optional, so this also covers list items with just a one-line para (no indent):: # LI1 = Bullet LS_OneLinePara # (IND[n] # (BlankLine+ (Para | List | DocTestBlock | LitBlk))+ # DED[n])? List Item, form 2: start with a paragrpah containing indentation, then contents, then corresponding dedent:: # LI2 = Bullet IndPara[n] # (BlankLine+ (Para | List | DocTestBlock | LitBlk))+ # DED[n] List Item, form 3: this is used when the bullet's on a line by itself:: # LI3 = Bullet NL # (IND[n] # (BlankLine+ (Para | List | DocTestBlock | LitBlk))+ # DED[n])? Sections consist of a heading, followed by an indended section that can contain anything (i.e., epytext):: # Section = Heading NL epytext DocTestBlocks are terminated by blank lines. They must be indented:: # DocTestBlk = IND[n] PyPrompt (ContLine NL)+ DED[n] Literal blocks. Within the literal block, all indents/dedents must be matched:: # LitBlk = IND LitBlkContents DED # LitBlkContents = [^ IND DED]+ | IND LitBlkContents DED ================================================================ Anyway, I'm sure I didn't get that quite right, but it's a start, anyway. -Edward

4 12

RE: [Doc-SIG] Structuring: a summary; and an attempt at EBNF..
by Goodger, David April 23, 2001

April 23, 2001

[Edward D. Loper] > I figured I'd give a summary of all the structuring features that > I think we've agreed on, so we can tentatively take those as > a given. If anyone objects, please say so.. OK, I'll bite! > 3. Doctest blocks start with ">>> " and continue to the next blank > line. Doctest blocks should be indented and separated by blank > lines. Do Doctest blocks have to be preceeded by "::"? I.E, are Doctest blocks simply a special case of literal blocks, or are they detected by indentation & ">>> " alone? > 4. Lists should be indented and separated by blank lines. Why should lists be indented? What's wrong with - a list - like this? No indentation is necessary. I suggest that if there *is* indentation, an alternate interpretation is possible. > 7. Colorizing takes place entirely within paragraphs, and does not > interact with structuring. (As an aside: where does this term "colourizing" come from? It was first used on Doc-SIG by Tibs last November. I've otherwise never seen it used in this sense wrt markup. I have seen it used in the sense of syntax colouring (i.e. IDEs changing the colour of text in code). I believe the correct term here would be something like "inline markup" or "mixed markup".) /DG

3 4

[maintenance doc updates]
by fdrake＠beowolf.digicool.com April 22, 2001

April 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ Third attempt to push maintenance docs to the SourceForge site. Sheesh!

1 0

[maintenance doc updates]
by fdrake＠beowolf.digicool.com April 22, 2001

April 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ Second attempt to push maintenance docs to the SourceForge site.

1 0

[maintenance doc updates]
by fdrake＠beowolf.digicool.com April 22, 2001

April 22, 2001

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ First attempt to push maintenance docs to the SourceForge site.

1 0

Finding cannonical names for objects
by Edward D. Loper April 22, 2001

April 22, 2001

When writing a documentation tool, it would be nice to be able to figure out what the "parent" of an object, where by parent, I mean: - for a module in a package, its package - for a function or class, the module it was originally defined in - for a member function, its class Among other things, this is useful for trying to establish a unique "cannonical" name for something that we're documenting, so we can make sure that inter-documentation pointers are correct (e.g., if we're converting docs to HTML). However, it's not clear how to do this in several cases. The cases where it *is* stright-forward to do it are: - for non-builtin modules, extract the package information from the __name__ field. Will this work for built-in packages, too? What's an example of a built-in package? - for non-builtin classes, consult the __module__ field - for non-builtin member functions, consult the im_class field - built-in classes all seem to have a __module__ field (e.g., exception.Exception or sys.last_type). Is this always true? In the case of non-builtin functions, I can think of two ways to do it:: def find_function_module_1(func): for module in sys.modules.values(): if func.func_globals == module.__dict__: return module.__name__ raise ValueError("Couldn't find the module for this function") def find_function_module_2(func): from os.path import basename, splitext try: return splitext(basename(inspect.getabsfile(func)))[0] except: raise ValueError("Couldn't find the module for this func") Is one of these approaches preferable? Will they ever give different results? Is there a reason that non-builtin functions don't have a __module__ field, like classes do? (Or a reason that built-in methods *do* have the __module__ field?) The other difficult cases are built-in objects. In general, I don't see any way to get parents for built-in objects. The relevant built-in objects that I know of are: - built-in functions (e.g., len, min, sys.settrace) - built-in methods (e.g., [].append, file(...).read) - non-builtin methods with underlying builtin functions (e.g., Exception.__str__) Is there any way to get the "parents" for these objects? (It would be *nice* if doctools could process built-in objects as well as non-builtin ones.) Another possible approach to finding cannonical names for objects is to use their ids (as returned by the builtin function id()). This wouldn't be as nice, since it would result in basically arbitrary names, but at least everything we document could be given a unique, cannonical name (within a given session). But I'm somewhat confused about id(). In particular, it seems to return a value for integers.. But since the returned value is an integer, it seems like that implies that at least 2 *different* values will have the same id.. Am I missing something? Is there somewhere I can read about what guarantees are given about whether two values' ids will be different? (e.g., if a value is GC'ed, can its id be recycled? I assume yes..) -Edward p.s., Is there a reason that __builtins__.__name__ == '__builtin__' instead of '__builtins__'?

2 3