Mailman 3 July 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><p>body elements</p></li>" or "<li>just text</li>" or even "<li>text<p>and body elements</p>combined</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 <p> 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 <p> 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

RE: [Doc-SIG] Comments on "inline external targets" example texts
by Moore, Paul July 27, 2002

July 27, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > The second thing I noticed was how difficult to read the > inline versions are, especially the "Stuart Little" and > "wochenschau" texts: practically unreadable. The long and > complex URLs do a lot of damage, breaking the flow of text > unacceptably. The integrated syntax files (``*3.txt``) > are a bit more readable than the compromise syntax files > (``*1.txt``). The "Gimp Links" texts have much shorter > URLs that don't interfere nearly as much when reading the > plaintext. > > Clearly, the "inline external targets" feature should only > be used with short URLs, or with source files that are > *not* intended to be read in plaintext form. I agree entirely with this. I tried to read the "Stuart Little" text with inline links, and frankly I gave up. The text was simply unreadable. OK, so Simon's point is that I shouldn't be reading the plain text. Can I also point out, however, that if I were given the inline link form to *maintain*, I would not be able to do so, as I would find that the unreadability made it impossible for me to reasonably maintain. The first thing I would do, as a new maintainer, would be to convert to non-inline links... > Simon Budig wrote: > > > I already pointed out, that I currently care more for > > maintainability than for readability > > Our goals are in conflict. The above statement and the > "inline external targets" feature itself conflict so > strongly with reStructuredText's "Readable" goal (number > 1: "It should be as easily read in raw [plaintext] form as > in processed [HTML etc.] form") that I'm tempted to just > say "forget it." But read on... The insight I had in looking at these was that the *maintainer* needs to read the plaintext, even if no-one else does. And virtually nothing which gets published ends up with only one maintainer... > > However, in the third sample the readability and > > maintainability is both increased. > > Indeed, the "Gimp Links" example offers the only hope for > redemption for the feature. That style of "list of links" > document lends itself to inline external targets. A suggestion I made before, but badly, may be relevant here. If you can define a syntax specifically for "list of links" type of documents, could you not use a custom directive? For the Gimp example, suppose I write a link-list directive, which takes a series of entries, each of which contains a link, followed by '--', followed by free text, and formats it as a list of links, any way the directive writer prefers. Then the first sections look like:: Some things for the Gimp ======================== Gimp__ is the best image manipulation program for Unix-Computers. It is very easy to make extensions for it. Here are my pages and extensions: __ http://www.gimp.org Plugins ------- .. link-list: pagecurl.html -- A Plugin to create an pagecurl effect fsdither.html -- A Plugin to do a proper Floyd-Steinberg dithering. gimpbuttons.html -- A unuseable Plugin to provide a Buttonbar for the Gimp. Yes - I mean unuseable! quant.html -- A Plugin to reduce the number of colors Does this example make my suggestion any clearer? I may have some of the details wrong, as I've never really looked at custom directives. But basically, the idea is to abstract out the concept of a "list of links" and code it directly. I'd love to try coding the link-list directive myself, but I don't have the time right now... Hope this helps, Paul.

3 2

Summary of reference/target syntaxes
by David Goodger July 24, 2002

July 24, 2002

Here is a summary of the current and proposed hyperlink syntaxes, with concrete examples, and my current thinking. 1. Named hyperlinks (in current reStructuredText):: This is a named reference_ of one word ("reference"). Here is a `phrase reference`_. Phrase references may even cross `line boundaries`_. .. _reference: http://www.example.org/reference/ .. _phrase reference: http://www.example.org/phrase_reference/ .. _line boundaries: http://www.example.org/line_boundaries/ Advantages: - The plaintext is readable. - Each target may be reused multiple times (e.g., just write "reference_" again). - No syncronized ordering of references and targets is necessary. Disadvantages: - The reference text must be repeated as target names; could lead to mistakes. - The target URLs may be located far from the references, and hard to find in the plaintext. 2. Anonymous hyperlinks (in current reStructuredText):: This is a named reference__ of one word ("reference"). Here is a `phrase reference`__. Phrase references may even cross `line boundaries`__. __ http://www.example.org/reference/ __ http://www.example.org/phrase_reference/ __ http://www.example.org/line_boundaries/ Advantages: - The plaintext is readable. - The reference text does not have to be repeated. Disadvantages: - References and targets must be kept in sync. - Targets cannot be reused. - The target URLs may be located far from the references. 3. The proposed inline external target syntax:: This is a named reference__ __<http://www.example.org/ reference/> of one word ("reference"). Here is a `phrase reference`__ __<http://www.example.org/phrase_reference/>. Advantages: - The target is specified immediately adjacent to the reference, improving maintainability: - References and targets are easily kept in sync. - The reference text does not have to be repeated. Disadvantages: - Poor plaintext readability. - Targets cannot be reused (but see below). To alleviate the readability issue slightly, we could allow the target to appear later, such as after the end of the sentence:: This is a named reference__ of one word ("reference"). __<http://www.example.org/reference/> Here is a `phrase reference`__. __<http://www.example.org/phrase_reference/> This could only work for one reference at a time (reference/target pairs must be proximate [refA trgA refB trgB], not interleaved [refA refB trgA trgB] or nested [refA refB trgB trgA]). Perhaps this restriction is too onerous; then references and targets would have to be imediately adjacent. The above syntax is actually for "anonymous inline external targets", emphasized by the double underscores. It follows that single trailing & leading underscores would lead to implicitly named inline external targets. This would allow the reuse of targets by name. So after "reference_ _<target>", another "reference_" would point to the same target. 4. If it is best for references and inline external targets to be immediately adjacent, they might as well be integrated. Here's an alternative syntax embedding the target URL in the reference:: This is a named `reference <http://www.example.org/reference />`__ of one word ("reference"). Here is a `phrase reference <http://www.example.org/phrase_reference/>`__. Advantages and disadvantages are the same as in (3). Readability is still an issue, but the syntax is a bit less heavyweight. There's a problem with this syntax: how to refer to a title like "HTML Anchors: <a>" (ending with an HTML/SGML/XML tag)? We could either require more syntax on the target (like "`reference text __<http://example.com/>`__"), or require the odd conflicting title to be escaped (like "`HTML Anchors: \<a>`__"). The latter seems preferable. Similarly to (3) above, a single trailing underscore would convert the reference & inline external target from anonymous to implicitly named, allowing reuse of targets by name. 5. For comparison and historical background, StructuredText has two syntaxes for hyperlinks. First, ``"reference text":URL``:: This is a named "reference":http://www.example.org/reference/ of one word ("reference"). Here is a "phrase reference":http://www.example.org/phrase_reference/. Second, ``"reference text", http://example.com/absolute_URL``:: This is a named "reference", http://www.example.org/reference/ of one word ("reference"). Here is a "phrase reference", http://www.example.org/phrase_reference/. Advantages: - The target is specified immediately adjacent to the reference. Disadvantages: - Poor plaintext readability. - Targets cannot be reused. - Both syntaxes use double quotes, common in ordinary text. - In the first syntax, the URL and the last word are stuck together, exacerbating the line wrap problem. - The second syntax is too magical; text could easily be written that way by accident (although only absolute URLs are recognized here, perhaps because of the potential for ambiguity). With any kind of inline external target syntax it comes down to the conflict between maintainability and plaintext readability. I don't see a major problem with reStructuredText's maintainability, and I don't want to sacrifice plaintext readability to "improve" it. The proponents of inline external targets want them for easily maintainable web pages. The arguments go something like this: - Named hyperlinks are difficult to maintain because the reference text is duplicated as the target name. To which I said, "So use anonymous hyperlinks." - Anonymous hyperlinks are difficult to maintain becuase the references and targets have to be kept in sync. "So keep the targets close to the references, grouped after each paragraph. Maintenance is trivial." - But targets grouped after paragraphs break the flow of text. "Surely less than URLs embedded in the text! And if the intent is to produce web pages, not readable plaintext, then who cares about the flow of text?" As is probably obvious, I'm ambivalent/against the proposed "inline external targets". I value reStructuredText's readability very highly, and although it may add some convenience, the "inline external target" syntax(es) compromise that readability IMO. Unless something changes (better syntax, new & better arguments and/or use cases), the best result this proposal can hope for is inclusion as "experimental syntax" via a pragma directive. -- 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/

3 5

Updates to Docutils
by David Goodger July 20, 2002

July 20, 2002

Download the latest snapshot from: http://docutils.sf.net/docutils-snapshot.tgz The sandbox snapshot is also available: http://docutils.sf.net/docutils-sandbox-snapshot.tgz Lots of changes in the last few weeks: * Added support for configuration files. Config files (/etc/docutils.conf, ./docutils.conf, ~/.docutils) override application defaults, and command-line options override all. Documentation is pending. * Added "simple tables" to reStructuredText (spec and parser): ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== * Improved HTML output with many small changes. * Added PEP processing support: - tools/pep.py: Front-end for processing reStructuredText PEPs. - tools/pep2html.py: Based on the existing script (in CVS at python/nondist/peps); processes old-style *and* reStructuredText PEPs. - docutils/writers/pep_html.py: HTML Writer for PEPs (subclass of ``html4css1.Writer``). * Updated the PEPs: - A "Roadmap to the Docstring PEPs" section was added to PEP 256: http://docutils.sf.net/spec/pep-0256.html - PEP 258 has been reorganized and extensively updated: http://docutils.sf.net/spec/pep-0258.html - PEP 287: updated, renamed to "reStructuredText Docstring Format" and converted to reStructuredText format (provisionally, pending PythonLabs OK). Check out the processed PEP 287: http://docutils.sf.net/spec/pep-0287.html I also converted PEP 0 as a proof of concept because of its special processing: http://docutils.sf.net/spec/pep-0000.html Late breaking news: I just got a reply from Guido, in which he critiques some style issues, then says, "I'm sure you can fix all these things with a simple style sheet change, and then I'm all for allowing Docutils for PEPs." I'd appreciate more critiques on PEP formatting issues, no matter how small. Especially, please help with stylesheet issues with the various browsers, by comparing the reStructuredText PEPs above to the old-style versions: http://www.python.org/peps/pep-0287.html http://www.python.org/peps/pep-0000.html * Added Docutils-native XML output: - tools/docutils-xml.py: A front-end. - docutils/writers/docutils_xml.py: A Writer. * Unicode & encodings are working. I hope to release Docutils version 0.2 in a week or two, incorporating Swedish and German language patches I've received and *maybe* the "inline external targets" syntax in some form. After that, I plan to focus on Python autodocumentation: analyze Tony Ibbs' PySource code and Doug Hellman's HappyDoc project, take the best ideas and integrate them into Docutils 0.3. -- 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

Re: [Doc-SIG] References in the same line as the target text
by Simon Budig July 13, 2002

July 13, 2002

[sorry, this was intended to go to doc-sig as well] David Goodger (goodger(a)users.sourceforge.net) wrote: > Simon Budig wrote: > > I have now implemented reference__ __<uri> and `refe rence`__ > > __<uri>. they are analogous to anonymous links. > > Did you allow for long URIs split over lines? This would have to be > allowed:: > > reference__ __<http://this.is.the.beginning > .of.a.very.long.uri.com/index.html#and-here-is > -even-more> I implemented this now (I was not aware that this is possible). It does not yet generate a warning when there are additional spaces in the URL though. > > I also implemented reference_ _<uri> and `refe rence`_ _<uri> > > analogoes to named links, this is some kind of closure of the syntax > > (mathematically speaking... :-) > > Where the target name is implied. Yes, I suppose it follows. > > > I am currently not sure if the possibility to wrap before long URLs > > is worth the added line noise by doubling the underscores. I think > > reference_<uri> resp. reference__<uri> might be acceptable too. > > Without the spaces & matching underscores the syntax would be too > subtle I think. And allowing for line-wrapping is important. Hmm. Isn't the possibility to break URLs with a newline enough and would reduce the need for the additional space in the markup? You could do `long text followed by a long URL that might make it necessary`__<http:// to.break.the.URL.at/the/end/of/the#line> I think that the advantage of this definitely is that it would indicate the tight connection between the text and the argument. The separation with a space looks a bit as if this were two totally independant syntactic constructs (which it isn't because __<this.url> would not be recognized. If you think that reference_<uri> is to subtle, we could make it more explicit with_<<double angle brackets>>. I also thought about adding an additional underscore__<like/this> for named and three underscores___<like/this> for anonymous inline targets. However, this could lead to confusion because "__" would be used for anonymous links and named inline links. Could lead to confusion. Bye, Simon -- Simon.Budig(a)unix-ag.org http://www.home.unix-ag.org/simon/

4 10

RE: [Doc-SIG] Summary of reference/target syntaxes
by Moore, Paul July 12, 2002

July 12, 2002

From: David Goodger [mailto:goodger@users.sourceforge.net] > Here is a summary of the current and proposed hyperlink syntaxes, > with concrete examples, and my current thinking. Thanks for the summary of the current state of play. I believe that it's fair. For what it's worth, I agree with your arguments. Link-heavy [sections of] documents (which are basically what this proposal is addressing) are not, in general, common. Maybe there's a more specialised approach to take. As far as I can see, the type of link-heavy document sections which we are considering are generally some form of index (a HTML page of links, a table of references, or some such). I could be wrong, but *I* would find it hard reading such text if it wasn't somehow list-formatted. You can see where I'm headed... Why not, instead of inventing another (general) hyperlink format, use a directive. You could have something like (completely untested, off the top of my head, and probably irrational) .. link-list:: First link -- http://www.example.com/wherever Second link -- relative_link.html I can't think of an example where I would want to have frequent hypertext links in *running* text. And for the occasional one or two links per paragraph, relative links located between paragraphs would be fine. To be honest, the longer a paragraph is, the less I would want to see interleaved URLs (unless the URLs themselves were the link text, a case which is already covered by standalone hyperlinks). Maybe this is worth noting as a separate alternative - don't bother with a general construct, but implement a directive to handle the specific case you are trying to deal with. Paul

2 1

Cleaning up HTML output (part 1 - 'name' and numerical ids)
by fantasai July 11, 2002

July 11, 2002

David Goodger wrote: > fantasai wrote: > > And numerical id's aren't very use-friendly. > > Docutils actually uses names wherever possible. I don't know that it > could be improved much, but if you do, please let me know. Well, let's take an example from your test.txt output: | <div class="section" id="structural-elements" name="structural-elements"> | <h1><a href="#id21">Structural Elements</a></h1> 'name' is not a valid attribute for <div>, <li>, or most of the other elements in HTML. It's used in forms, and it's used in the anchor tag. The above code should be written one of three ways: <div class="section" id="structural-elements"> <h1>Structural Elements</h1> <div class="section"> <h1><a id="structural-elements" name="structural-elements">Structural Elements</a></h1> <div class="section"> <h1><a name="structural-elements">Structural Elements</a></h1> The first only works in browsers that support the 'id' attribute for targets, but it is a cleaner syntax. The second is redundant. The third is not ideal, but it works in every HTML browser I have ever come across. You use the numerical ids to have headings refer back to their respective section entries in the table of contents. I don't see that this is a particularly necessary behavior to have--you can just link back to the table of contents as a whole, if you really want to. Ideally, you'd put in a <link> to the table of contents in the <head>: <link rel="toc" href="#table-of-contents" title="Table of Contents"> and leave it at that. Unfortunatly, most browsers don't support <link>. If linking back to the corresponding toc entry is important to you, then identify the entries with the section's id preceded by 'toc-'. For example: <li id="toc-structural-elements"><a href="#structural-elements">Structural Elements</a></li> or <li><a href="#structural-elements" name="toc-structural-elements">Structural Elements</a></li> IMO, having the headers as links is distracting. But that's just my opinion. ~fantasai

2 3

Re: [Doc-SIG] Older Python Documentation
by Guido van Rossum July 9, 2002

July 9, 2002

> Older releases didn't publish the HTML (you'd have to run latex2html > yourself). Note that the most complete collection of Python > downloadables is at http://www.python.org/ftp/python/src/ -- the 1.2 > and 1.3 source releases are there and they contain the .tex files. Actually, the 1.2 and 1.3 HTML at least have been preserved: ftp://www.python.org/pub/python/doc/1.2/ ftp://www.python.org/pub/python/doc/1.3/ --Guido van Rossum (home page: http://www.python.org/~guido/)

1 0

Older Python Documentation
by Grant Harris July 9, 2002

July 9, 2002

Hello, I'm working on a web site (http://www.webdocs.org) that hosts the current and older releases of the official Python documentation, along with some other Python-related docs. I currently have Python documentation from as far back as version 1.4 on the site, but nothing older. If possible, I'd like to include as many releases of the Python documentation as I can find (if not all of them). However, I can't seem to find anything prior to Python 1.4. (I did happen to find some tex files for a couple older versions, but no html files.) Also, I'm relatively new to Python (less than a year), so I don't even know which older versions were officially released. For instance, I know that there was a version 1.3 and a 1.2 released, but was there ever a version 1.2.1 or 1.3.1? My guess is that no one today would even care about documentation from that far back. But personally I think it's cool to be able to see how Python has evolved over the years. If anyone knows where I can get documentation for versions of Python older than 1.4, please let me know. Regards, -Grant

3 2

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