Mailman 3 September 2002 - Doc-SIG

compact HTML output from Docutils
by David Goodger Dec. 17, 2002

Dec. 17, 2002

I've tweaked Docutils' HTML writer to produce more visually compact HTML (less vertical whitespace). HTML's mixed content models allow list items to contain "<li>body elements</li>" or "<li>just text</li>" or even "<li>textand body elementscombined</li>", each with different effects. I'd prefer to stick with strict body elements in list items, but they affect vertical spacing in browsers (although they really shouldn't). Does anybody know of a good discussion of vertical space issues for HTML and/or CSS? After trying various algorithms, I've settled on a hybrid: - Check for and omit tags in "simple" lists: list items contain either a single paragraph, a nested simple list, or a paragraph followed by a nested simple list. This means that this list can be compact: - Item 1. - Item 2. But this list cannot be compact: - Item 1. This second paragraph forces space between list items. - Item 2. - In non-list contexts, omit tags on a paragraph if that paragraph is the only child of its parent (footnotes & citations are allowed a label first). - Regardless of the above, in definitions, table cells, field bodies, option descriptions, and list items, mark the first child with 'class="first"' if it is a paragraph. The stylesheet sets the top margin to 0 for these paragraphs. I'd appreciate feedback, especially from people using different browsers (I've checked IE and Mozilla on both MacOS & Win2K, and Netscape 4 & 6 on MacOS). Please browse the following files: - http://docutils.sf.net/tools/test.html - http://docutils.sf.net/spec/pep-0287.html - http://docutils.sf.net/spec/pep-0000.html Is the above approach correct? Does the generated HTML come out right? Should the compact output be optional (i.e. should there be an option to turn it off)? Any suggestions? Get your snapshots here: http://docutils.sf.net/docutils-snapshot.tgz -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

4 3

Docstring Standards
by Mahrt, Dallas Oct. 2, 2002

Oct. 2, 2002

Background: I am in the process of defining some internal programming standards for my company. One aspect we are keenly interested in is defining the docstring syntax such that we can facilitate documentation generation (similar to Doxygen or JavaDoc which we use currently) I have read about the docutils project and feel it is probably the best fit (in the long term) for our needs, however I have a question. 1) Method signatures. In Doxygen and JavaDoc, there is an explicit ''@param'' syntax for defining the documentation related to a parameter. There are similar constructs for ''@exception'' and ''@return''. The only thing similar I have found in docutils documentations is the use of explicit roles. Ex. def foo(bar): """This is foo. :parameter"`foo` - This is a foo """ Is this the *standard* way of documenting parameters? If not is there a standard? If so is there a similar concept for raised exceptions and return values? The only thing I've noticed in practice are English descriptions with literal references. Ex. def foo(bar): """This is foo. Passes `foo` which is a foo. """ This seems to be more difficult to extract the description from the identifier for a more tabular representation (like JavaDoc) --- Dallas S. Mahrt dallasm(a)aiinet.com Software Engineer Applied Innovation Inc.

3 3

epydoc 1.0 release
by Edward Loper Sept. 27, 2002

Sept. 27, 2002

I just released version 1.0 of epydoc. Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. <http://epydoc.sourceforge.net/> It uses a markup language that is similar in some ways to reST, but simpler (and I would say cleaner :) ). It produces output similar to javadoc; for an example of its output, see the API documentation for epydoc itself: <http://epydoc.sourceforge.net/api/epydoc.html> For a more extensive example (and a different stylesheet), see the API documentation for NLTK (the natural language toolkit): <http://nltk.sourceforge.net/ref/nltk.html> Epydoc is now fairly mature, and I don't plan to do much more work on it in the near future. But if/when docutils becomes The Standard Framework for docstring tools, I will look into integrating epydoc into the docutils framework (as a reader/parser and a writer/formatter). I've been pretty happy with epydoc's markup langauge (epytext), and hopefully if it gets integrated with docutils, other people will find it useful too. Below is a description of how the epytext markup language relates to reST (the current standard markup language for docutils), for anyone who's interested. If you're interested in the epytext markup language itself, but don't care how it relates to reST, then see the epytext manual <http://epydoc.sourceforge.net/epytext.html>. If you're not interested at all, then go read the rest of your email. :) -Edward ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ First of all, let me note that epytext and reST have very different goals: reST is a very general-purpose markup language, that is good for PEPs, webpages, etc. Epytext is intended only for API documentation generation. Both epytext and reST markup can be divided into "block structure" (paragraphs, lists, etc) and "inline markup" (italics, hyperlinks, etc). I'll discuss them separately. Block structure =============== Epytext's block structure is basically a "light" version of reST, that's somewhat less leniant (e.g., underline length must match heading length). In particular, it supports the following block structure constructs using basically the same syntax that reST uses: - paragraphs - unordered lists (bullet must be "-") - ordered lists (bullets must match "(\d+[.])+", like "12." or "3.2.") - literal blocks - doctest blocks - sections (underlines only, heading underline characters restricted to '=', '-', and '~'.) It also defines "field lists," which are like reST field lists, but have a different syntax -- bullets have the form "@\w+:" or "@\w+ \w+:", like "@return:" or "@param x:" Inline markup ============= Epytext inline markup is fairly different from reST inline markup. All epytext inline markup has the form "x{...}", where "x" is a single capital letter. This makes markup easy to spot, and makes nesting obvious. A matching pair of curly braces is only interpreted as inline markup if the left brace is immediately preceeded by a capital letter. So in most cases, you can use curly braces in your text without any form of escaping. However, you do need to escape curly braces when: - You want to include a single (un-matched) curly brace. - You want to preceed a matched pair of curly braces with a capital letter. I grepped through a pretty large number of docstrings, and both of these cases seem pretty rare. Note that there is no valid Python expression where a pair of matched curly braces is immediately preceeded by a capital letter (except within string literals). In particular, you never need to escape braces when writing Python dictionaries. I think that reST uses too many different inline markup constructs, that can interact with each other in weird and non-intuitive ways. A couple of them may have some value as "intuitive". In particular, *emphasis* is widely used (though it's not obvious to me whether that should be bold or italics). But constructs like ``this`` and #this# and `this`_ seem significantly less obvious to me. I prefer a single unified inline markup syntax, that almost never requires any escaping. For a more detailed description of the epytext markup language, see the epytext manual on the epydoc homepage: <http://epydoc.sourceforge.net/epytext.html>

2 2

converting tex? use of docbook?
by Ian Atkin Sept. 26, 2002

Sept. 26, 2002

hello, python newbie very interested in tech writing while learning python i'm focusing on doc systems, tool-chains etc comming from a java/xml/xslt/docbook background and want to dive in to python's doc platform here's my views (to prevent flames, not provoke :-) - structured markup is a Good Thing - xml's simplicity outweighs sgml's power (in the end) - tool-chains are a mess, so whatever works... - authoring is in a state, so whatever syntax folks are prepared to use is sound - docbook is a beast, but a beautiful one :-) here's my questions:- - is there any motivation to move python's doc format to xml docbook? can i contrib/promote in any way? (i read a mention of a "python doc project" like the ldp) - what "types" of document are most commonly used/wanted in the python distro/apps and do these require unique markup? - are there any open tools (or chains) around to convert tex source into xml (xslt scripts can do the rest)? i've got loads of other questions and ideas, but need to fathom the world of python doc tools (docutils, happydoc, etc) in order not to appear more stupid than i am, expect more mails...

3 3

table with border="0"
by Uwe Hentzschel Sept. 25, 2002

Sept. 25, 2002

Is it possible to provide a table with border="0" ? uhe

2 1

Relax the 4-character minimum on section title underlines?
by David Goodger Sept. 20, 2002

Sept. 20, 2002

I am considering relaxing the 4-character minimum requirement for reStructuredText section title underlines, and would like to determine the best course of action. The spec states: An underline/overline is a single repeated punctuation character that begins in column 1 and forms a line extending at least as far as the right edge of the title text. ... An underline/overline must be at least 4 characters long (to avoid mistaking ellipses ["..."] for overlines). (http://docutils.sf.net/spec/rst/reStructuredText.html#sections) The 4-character minimum on transition markers will remain, regardless. Sometimes a title is less than 4 characters long, and it's natural to want to use an underline of exactly the same length. I've noticed such cases in others' documents, and in my own. In my own document, I used a 3-character underline; the title was parsed as an ordinary paragraph and it took some time to discover the problem and fix it, because the parser produced no warning. Here's the current entry in the "Bugs" section of the "To Do" list: Section headers must have underlines at least 4 characters long. But when the section title is only 3 characters long, it's natural to underline with "===" (I just did). The parser should produce a warning in such cases. Or should the parser simply recognize such short underlines? A zero-tolerance policy might work: over/underlines of 3 or fewer characters which are shorter than the "title" text are not recognized as titles, and should generate an "info" message. There has also been a bug report submitted on the issue (by Jeremy Hylton): http://sf.net/tracker/?func=detail&atid=422030&aid=608108&group_id=38414 There's no problem with the typical case, where the over/underlines are at least as long as the title text:: ABC === --- DEF --- But what to do when the over/underline is too short? Ellipsis ("...") and m-dash (commonly written "---") both use 3 repeated punctuation characters; this ambiguity is what the 4-character minimum avoided. For example:: Is This Supposed To Be A Title? --- This, surely, is not ... In these cases, I'm thinking of inserting INFO (level 1) system messages that say, "Possible title underline, too short for the title text. Treating it as ordinary text because it's so short." INFO system messages are not normally visible (shown only if the -v/--verbose option is used). In other words, short underlines (<= 3 characters) are recognized as title adornments if they're long enough for the title text, but if they're too short they're just wrapped text plus a normally-invisible system message. I think this is the right balance of precision (unambiguous, unsurprising) and "do what I say" (intuitive). How about these cases, of overlines? Unless stated otherwise, the short overlines would each be treated as ordinary text and an INFO system message inserted:: ... This is not a title; perhaps an excerpt from a quote. .. This is interpreted as a comment start immediately followed by a paragraph. Triggers a "no blank line; unexpected unindent" warning. == These lines would not be interpreted as a title. == --- The three dashes above might represent an m-dash. == Would this become a definition list? == And what about this? A definition list item followed by a paragraph and a "no blank line; unexpected unindent" warning. == And when section titles are not expected/allowed:: Ordinary paragraph. This title should trigger a SEVERE error (sections not allowed inside block quotes), as currently happens with longer titles: ABC === This title should trigger an INFO message and be treated as an ordinary paragraph, since the underline is too short for the title: ABC == Does all of this seem reasonable? Any gotchas I'm missing? -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 1

ANN: DocFactory wxPython app for Docutils
by David Goodger Sept. 15, 2002

Sept. 15, 2002

Gunnar Schwant has contributed DocFactory, a wxPython GUI application for Docutils. It is in the preliminary stages. For details, please see http://docutils.sf.net/sandbox/gschwant/docfactory/README.html I have begun a "To Do" list: http://docutils.sf.net/sandbox/gschwant/docfactory/NOTES.html The code is available via CVS or snapshot: http://docutils.sf.net/docutils-sandbox-snapshot.tgz Please try it out. Feedback is welcome: bug reports, patches, feature ideas, etc. -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 0

Field arguments dropped (was Re: Forcing line breaks)
by David Goodger Sept. 11, 2002

Sept. 11, 2002

I wrote: > Or perhaps we just drop the idea of field arguments altogether, and > rely on the application code to parse the field name as it likes. And now it's implemented. Field lists are now freely usable as generic document constructs. Field names may have multiple words, although restrictions may be imposed by (and the interpretation depends on) application code. Short form: field lists are more general-purpose now, with no problems anticipated. -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 0

FW: [Docutils-develop] Forcing line breaks
by David Goodger Sept. 7, 2002

Sept. 7, 2002

(Forwarding to the Doc-SIG to solicit opinions.) [Adam] >>> Is there any way to force line breaks? Example of usage:: >>> >>> :Name: Adam Chodorowski >>> :Address: The Street >>> 11111 The Town >>> The Country >>> :Phone: +11-111111 [David] >> If you're using a recent snapshot, it's already taken care of for >> you. The "Address" field should produce the equivalent of a >> line_block element, which is exactly what you describe. [Adam] > I'm guessing that is only valid for a bibliographic fields... Yes. Special processing in a specific context, which cannot be assumed anywhere else. >> - You shouldn't really be using field lists in the first place. >> They're for extension syntax (docinfo & directive options). I'll >> make this more explicit in the docs. Perhaps a table or a >> definition list would be better? > > I disagree strongly on this. Why on earth shouldn't fields lists be > usable as a construct of their own? On April 25, I clarified the spec to say this about field lists: "They are not intended to be an alternative to definition lists or tables." I made this admonition stronger yesterday: "Field lists should only be used when and where application code specifically expects them; they should *not* be used as arbitrary constructs in documents." Before you begin your reply, please read to the end. (It's one of my thinking-an-issue-through-to-the-end essays.) > Definition lists do fit *conceptually*, but unfortunately not with > regard to presentation. When you specify contact information or > similar data, you almost always do it like this:: > > Name: Adam Chodorowski > Address: The Street 42 > 11111 The City > Country: Sweden > Phone: +46-8-1111111 Actually, I would write it like this:: Adam Chodorowski The Street 42 11111 The City Sweden phone +46-8-1111111 Most of the labels are redundant; people know how to read addresses from context. > Having definition lists is *not* intuitive for the reader ... > nobody excepts contact information to be presented that way. I wouldn't expect contact information to be presented the "field list" way either. Are conventions so different in Sweden? Do you really need to label everything? (But this is avoiding the real issue.) > Field lists are IMHO perfect for "single vertical table rows". Just > what the doctor ordered. ;-) This may a case of abusing markup because it gives the desired results. In DocBook terms, it's like a doc writer using <emphasis> instead of <glossterm>, because they want italics in the output. A *side effect* of <glossterm> may be italics, but the main effect may be quite different (hyperlinking all glossterms to a glossary, for example). But I do see Adam's point. I've been moving towards thinking about field lists purely as an extension syntax, not as a generic construct. Partly this is due to outside influence, the incessant "reStructuredText is too complex!" from certain parties. So we have to choose: 1. Field lists shall be restricted to extension syntax use (directive options, docinfo) only. 2. Field lists shall also be available to authors as a generic two-column table/list construct. There are consequences. If we choose #1, we should remove field list support from writers; it would be an error for an unprocessed field list to remain in the document tree. If we choose #2, we should ask ourselves, are field lists generic *enough*? The current field list syntax (geared toward extension syntax use, choice #1) was modeled after RFC 2822's fields and JavaDoc's "@tags". It limits field names to single (possibly compound) words. Anything after whitespace is taken to be field arguments, which are semantically and presentationally separate from field names. Field arguments allow the equivalent of a JavaDoc "@param name description" tag. In Adam's contact info block above, there's a "phone" field. What if he wants to differentiate between phone numbers (home, cell, pager)? Let's assume that in Swedish we cannot rework the field names into single words; we *have* to use multiple words. We'd want this as output:: Home Phone: +46-8-1111111 Cell Phone: +46-8-2222222 Pager Number: +46-8-3333333 The closest we could get with current field lists would be like this:: :Home-Phone: +46-8-1111111 :Cell-Phone: +46-8-2222222 :Pager-Number: +46-8-3333333 (Underscores could be used instead of hyphens.) I doubt that this would be acceptable to most document authors, and the output (with hyphens intact) would look strange to readers. The alternative is to redefine field lists to allow multi-word field names, and use a different syntax for field arguments. Perhaps something like this:: :Field name <field arguments>: Field body Or perhaps we just drop the idea of field arguments altogether, and rely on the application code to parse the field name as it likes. Apart from the test suite, the only place where field arguments are used is in the "meta" directive, which produces <meta> tags. This is from tools/test.txt:: .. meta:: :keywords: reStructuredText, test, parser :description lang=en: A test document, containing at least one example of each reStructuredText construct. The "meta" directive code would have no problem extracting the "lang=en" argument from the field name. The "meta" directive would specify that the first word of the field name would be taken as the "name" attribute, and the rest should be "attname=value" attribute definitions. I'm beginning to like this change. If we drop the notion of "field arguments", field lists become simpler and fully generic. Then I'd drop my objection to their use as a generic document construct. Any objections to this change? -- David Goodger <goodger(a)users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/

1 0

Documentation inconsistency in re
by list-python＠ccraig.org Sept. 6, 2002

Sept. 6, 2002

>From the Library Reference (2.2.1): \b Matches the empty string, but only at the beginning or end of a word. A word is defined as a sequence of alphanumeric characters, so the end of a word is indicated by whitespace or a non-alphanumeric character. Inside a character range, \b represents the backspace character, for compatibility with Python's string literals. Now reality: Python 2.2.1 (#2, Apr 22 2002, 17:53:10) [GCC 2.95.4 20011002 (Debian prerelease)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import re >>> t = re.compile(r'\bbag\b') >>> t.search('test bag') <_sre.SRE_Match object at 0x812aad0> >>> t.search('test+bag') <_sre.SRE_Match object at 0x815d528> >>> t.search('test_bag') >>> [ chr(i) for i in xrange(256) if not t.search('test' + chr(i) + 'bag') ] ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '_', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'] >>> So the implementation appears to define a word as a sequence of alphanumeric characters or underscores, which means either the documentation, or the library is wrong. Now it happens that this was found while a friend of mine and I were looking to get the exact behavior that is implemented, so I'd prefer it if the documentation were updated to meet the implementation <.8 wink>. -- Christopher A. Craig <list-python(a)ccraig.org> I develop for Linux for a living, I used to develop for DOS. Going from DOS to Linux is like trading a glider for an F117. - Lawrence Foard

3 2