Mailman 3 August 2002 - Doc-SIG

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

Dec. 16, 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

ANN: New PEP Format: reStructuredText
by David Goodger Aug. 29, 2002

Aug. 29, 2002

With many thanks to Barry Warsaw for his help and patience, I am pleased to announce that a new format for PEPs (Python Enhancement Proposals) has been deployed. The new format is reStructuredText, a lightweight what-you-see-is-what-you-get plaintext markup syntax and parser component of the Docutils project. From the new PEP 12: ReStructuredText is offered as an alternative to plaintext PEPs, to allow PEP authors more functionality and expressivity, while maintaining easy readability in the source text. The processed HTML form makes the functionality accessible to readers: live hyperlinks, styled text, tables, images, and automatic tables of contents, among other advantages. The following PEPs have been marked up with reStructuredText: - PEP 12 -- Sample reStructuredText PEP Template (http://www.python.org/peps/pep-0012.html) - PEP 256 -- Docstring Processing System Framework (http://www.python.org/peps/pep-0256.html) - PEP 257 -- Docstring Conventions (http://www.python.org/peps/pep-0257.html) - PEP 258 -- Docutils Design Specification (http://www.python.org/peps/pep-0258.html) - PEP 287 -- reStructuredText Docstring Format (http://www.python.org/peps/pep-0287.html) - PEP 290 -- Code Migration and Modernization (http://www.python.org/peps/pep-0290.html) In addition, the text of PEP 1 and PEP 9 has been revised. Authors of new PEPs are invited to consider using the new format, and authors of existing PEPs are invited to convert their PEPs to reStructuredText to take advantage of the many enhancements over the plaintext format. I, along with the other Docutils developers and users, will be happy to assist. Please send questions to: docutils-users(a)lists.sourceforge.net The latest project snapshot can always be downloaded from: http://docutils.sourceforge.net/docutils-snapshot.tgz (This is required to process the PEP source into HTML. It requires at least Python 2.0; Python 2.1 or later is recommended.) Docutils and reStructuredText are under active development. Input is very welcome, especially HTML rendering/stylesheet issues with different browsers. We welcome new contributors. If you'd like to get involved, please visit: http://docutils.sourceforge.net/ -- 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

"The Docutils Document Tree"
by David Goodger Aug. 23, 2002

Aug. 23, 2002

There's been a lot of progress on "The Docutils Document Tree" lately. See http://docutils.sf.net/spec/doctree.html. There are 55 DTD elements left to describe; I'd appreciate any help I can get. Proofreading, editing, or writing; even one element section would be great! -- 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

enumerated list item parsing fixed
by David Goodger Aug. 15, 2002

Aug. 15, 2002

I've fixed the reStructuredText parser's handling of enumerated list items to deal with the following edge cases: - This text is parsed as a section title:: 1. This is the heading of section one ===================================== - This text is parsed as an ordinary paragraph: A. Einstein was a really smart dude. However, ambiguity cannot be avoided if the paragraph consists of only one line. This text is parsed as an enumerated list item:: A. Einstein was a really smart dude. If a single-line paragraph begins with text identical to an enumerator ("A.", "1.", "(b)", "I)", etc.), the first character will have to be escaped in order to have the line parsed as an ordinary paragraph:: \A. Einstein was a really smart dude. The code, spec, and test suite have been updated. The code change consists of checking the second line of each enumerated list item for validity, in the parser's new ``Body.is_enumerated_list_item`` method. Thanks to Jeremy Hylton and Dmitry Jemerov for their bug reports. In addition, I implemented the "line-block" and "parsed-literal" directives. See http://docutils.sf.net/tools/test.html#line-blocks for an example of the former; docs in http://docutils.sf.net/spec/rst/directives.html. The latest snapshot can always be downloaded from: 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/

1 0

Re[2]: [Doc-SIG] numbered headings in reST
by Dmitry Jemerov Aug. 12, 2002

Aug. 12, 2002

Hello David, Saturday, August 10, 2002, 8:37:22 AM, you wrote: >>> In the spec/notes.txt file there is this idea for a "sectnum" >>> directive: >>> >>> _`parts.sectnum` (automatic section numbering; add support to >>> the "contents" directive; could be cmdline option also) >>> >>> By this I'm thinking of an option to automatically number sections; >>> the user wouldn't have to write or maintain the numbering. Would >>> that be a better solution for you? >> >> How exactly would that look and work? Automatic section numbering >> would be a good thing for me. DG> Something like this:: DG> .. sectnum:: DG> Section One DG> =========== DG> Section Two DG> =========== DG> Subsection One DG> -------------- DG> When processed, the numbers "1", "2", and "2.1" would be prefixed to DG> the titles automatically. The directive name could be "sectnum" or DG> "section-numbers" or "section-numbering", perhaps with a ":global:" DG> attribute. OK. Docutils is still quite new to me, and I didn't understand at once that sectnum will be a global transform specified once in the document, and not in every section title. And after all, document transforms seemed easier to figure out than list parsing code, and so the patch implementing the sectnum directive is now at: http://sourceforge.net/tracker/index.php?func=detail&aid=593461&group_id=38… The directive doesn't have any attributes (should there be any? which?). Also, the auto-generated numbers are not added to the section IDs, and only to the title text visible in the document. A test-case is included with the patch. Please review the code and check it in if you consider it worthy. I don't give up on correct list parsing yet - I'll try to solve the list parsing problem tomorrow. DG> On a related note, in a 2001-07-10 post to Doc-SIG, I wrote: DG> I'm also toying with the idea of removing leading numbers from DG> implicit link names, so a section titled "3. Conclusion" can be DG> referred to by "Conclusion_" (i.e., without the "3."). DG> I've added it to the to-do list, but with a "?", so it's low-to-no DG> priority. I could fix this too if you like. This should be consistent with section auto-numbering, I think - either the section auto-numberer should add the numbers to link names, or the numbers specified in link names by the user should be removed. The second option looks better. -- Best regards, Dmitry mailto:yole@yole.ru

2 4

Re[2]: [Doc-SIG] numbered headings in reST
by Dmitry Jemerov Aug. 9, 2002

Aug. 9, 2002

Hello David, Friday, August 9, 2002, 5:02:30 AM, you wrote: >> Recently I decided to use reST to write the documentation for my >> (soon to be released) project. DG> Our first report from Russia. Cool. Are you using Docutils for Russian or DG> English text? English for now, but a Russian translation is planned for a later time. >> One of the first things I tried to write in my file was: >> >> 1. This is the heading of section one >> ===================================== >> >> However, this doesn't work, and the following error message is >> given: >> >> WARNING (level 2 system message) >> Enumerated list ends without a blank line; unexpected unindent at line 5. DG> Yes, the "1." is recognized as a list marker. I've had another similar bug DG> report recently; see http://docutils.sf.net/spec/notes.html#bugs (marked DG> with "@@@"). I'll be looking into it soon. It may be time to re-examine DG> the PELI (potential enumerated list item) idea; see the block quote in DG> http://docutils.sf.net/spec/rst/problems.html#enumerated-list-markup . In my opinion, it is not a good idea to require multiple adjacent list items. As far as I understand, this will cause the following not to be treated as a list: * List item one Here is a long list of considerations related to the list item one. * List item two And some more considerations. What I would prefer is a different form of lookahead: if the line following a potential list item is definitely not a list item (a heading marker, or the start of a table, or something like that), then the list is not created. >> I've seen no mention of numbered headings in the spec, but in my >> opinion, they are a very commonly used construct. Are you planning to >> support numbered headings in the future version of DocUtils? DG> In the spec/notes.txt file there is this idea for a "sectnum" directive: DG> _`parts.sectnum` (automatic section numbering; add support to DG> the "contents" directive; could be cmdline option also) DG> By this I'm thinking of an option to automatically number sections; the user DG> wouldn't have to write or maintain the numbering. Would that be a better DG> solution for you? How exactly would that look and work? Automatic section numbering would be a good thing for me. Another idea is to have section auto-numbering like proposed by Tony Ibbs (alternatives.txt, Auto-Enumerated Lists, item 4): #1. Section 1. ============== #1.#1. This is a subsection of section 1. ----------------------------------------- #1.#2. And another subsection ----------------------------- This looks more readable as plaintext than embedding some directives like _`parts.sectnum` in the section title. DG> In the meantime, you can backslash-escape the title to avoid it being DG> mistaken for a list marker:: DG> \1. This is the heading of section one DG> ====================================== DG> I know, it's ugly. OK, I'll use this if nothing else works. However, numbered headings are common enough to require a better solution. >> Maybe I could try to do a patch for numbered headings support myself? DG> If you'd like to give it a try, please go for it! But I think the correct DG> approach would be to fix the current naive parsing, rather than just allow DG> for special cases like numbered titles. Fixing the enumerated list parsing DG> would require some lookahead, as is done with definition lists and section DG> headers: the first line isn't acted upon until the second line is checked. OK, once we decide on the best solution, I'll try to do the implementation. -- Best regards, Dmitry mailto:yole@yole.ru

1 0

numbered headings in reST
by Dmitry Jemerov Aug. 8, 2002

Aug. 8, 2002

Hello David, Recently I decided to use reST to write the documentation for my (soon to be released) project. The formatting features provided by reST seem to match my needs pretty well, with one exception. One of the first things I tried to write in my file was: 1. This is the heading of section one ===================================== However, this doesn't work, and the following error message is given: WARNING (level 2 system message) Enumerated list ends without a blank line; unexpected unindent at line 5. I've seen no mention of numbered headings in the spec, but in my opinion, they are a very commonly used construct. Are you planning to support numbered headings in the future version of DocUtils? Maybe I could try to do a patch for numbered headings support myself? -- Best regards, Dmitry mailto:yole@yole.ru

2 1

Re: HTML Puzzle
by Dethe Elza Aug. 6, 2002

Aug. 6, 2002

I would check to see if the stylesheets are being served with the proper MIME types. Navigator tends to be sensitive to that sort of thing, while IE tends to ignore MIME types in favor of extension-mapping. --Dethe > I've been fiddling with the stylesheet for Docutils output, and I came > across something strange in Netscape 4.7 (MacOS). I've reduced it to one > variable: web server. I've copied the HTML and stylesheet for PEP 257 from > python.org to docutils.sf.net, so I'm looking at the exact same data, but > they render differently. Here are the two URLs: > > http://www.python.org/peps/pep-0257.html > http://docutils.sf.net/spec/pep0257.html > > (Note there's no "-"; that's so it doesn't clobber the locally-generated > file that does have a "-". Otherwise insignificant.) > > Specifically, the typeface and spacing of the RFC2822 headers and section > headers render differently. The python.org one comes out correctly, with > headers in a sans-serif font, but the sf.net one uses a serif font. In the > sf.net version, there's more space between the lines in the header. > > Can anyone reproduce or explain this?

1 0

HTML puzzle
by David Goodger Aug. 5, 2002

Aug. 5, 2002

I've been fiddling with the stylesheet for Docutils output, and I came across something strange in Netscape 4.7 (MacOS). I've reduced it to one variable: web server. I've copied the HTML and stylesheet for PEP 257 from python.org to docutils.sf.net, so I'm looking at the exact same data, but they render differently. Here are the two URLs: http://www.python.org/peps/pep-0257.html http://docutils.sf.net/spec/pep0257.html (Note there's no "-"; that's so it doesn't clobber the locally-generated file that does have a "-". Otherwise insignificant.) Specifically, the typeface and spacing of the RFC2822 headers and section headers render differently. The python.org one comes out correctly, with headers in a sans-serif font, but the sf.net one uses a serif font. In the sf.net version, there's more space between the lines in the header. Can anyone reproduce or explain this? -- 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/

2 2

docutils HTML contents generation and Netscape
by Pearu Peterson Aug. 3, 2002

Aug. 3, 2002

Hi, While viewing docutils generated html files with Netscape (4.77) I have noticed that links in Contents to document sections do not work at all (they work nicely with Mozilla though). It seems that Netscape does not understand HTML div tags well. Here follows my changes to docutils/writers/html4css1.py (in CVS) that make the links work for Netscape as well: diff -r1.32 html4css1.py 920,921c920,922 < self.body.append('<a class="toc-backref" href="#%s">' < % node['refid']) --- > node_id = nodes.make_id(node.astext()) > self.body.append('<a class="toc-backref" href="#%s" name="%s">' > % (node['refid'],node_id)) BTW, I just started to use docutils-0.2 for documenting the f2py project and I already find docutils quite usable despite its alpha nature that sometimes shows up. I'll try to report these glitches but without trying to fix them too hard if that's OK. Thanks, Pearu

3 4