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

epydoc 1.1 release
by Edward Loper Nov. 5, 2002

Nov. 5, 2002

I just released version 1.1 of epydoc. Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. <http://epydoc.sourceforge.net/> A lightweight markup language called epytext can be used to format docstrings, and to add information about specific fields, such as parameters and instance variables. For some examples of the documentation generated by epydoc, see: - The API documentation for epydoc. <http://epydoc.sourceforge.net/api/> - The API documentation for the Python 2.2 standard library. <http://epydoc.sourceforge.net/stdlib/> - The API documentation for NLTK, the natural langauge toolkit. <http://nltk.sourceforge.net/ref/> New features added since 1.0 include: - A frames-based table of contents - Documentation for builtin objects - Documentation for types - Improved navigation bars - Improved warning messages - Better documentation for variables - An identifier index - An improved graphical interface - Man pages A complete list of new features and the change log are available at: <http://sourceforge.net/project/shownotes.php?release_id=119576> -Edward

5 11

controlling sections levels
by Albert Ting Oct. 31, 2002

Oct. 31, 2002

How does one control the number of html levels to output? html.py defaults to 6, but if I use the core.publish_string() function, I'm only getting 3. Also, is there a way to auto number the titles/chapters/sections? In any case, this is a nice tool, I'm finding it more useful than the Zope:StructuredText Thanks, Albert Ting

3 6

A larger gold balance!
by Nobody Oct. 30, 2002

Oct. 30, 2002

1 0

Re: [Doc-SIG] simple use of docutils
by Michael Hudson Oct. 24, 2002

Oct. 24, 2002

David Goodger <goodger(a)users.sourceforge.net> writes: > ... I (still) haven't had time to fiddle with the library front end, but now I've had a chance to play with the backend, I'm impressed. I managed to adapt the html4css1 writer in what I thought would be complicated ways very easily. Nice one! I might package up the code I have -- maybe an example? -- but at the moment it's embarrassing. Cheers, M. -- MARVIN: What a depressingly stupid machine. -- The Hitch-Hikers Guide to the Galaxy, Episode 7

3 2

Docutils transforms overhauled
by David Goodger Oct. 24, 2002

Oct. 24, 2002

I just checked in a major change to the Docutils tranform handling mechanism. There's a new component, called "Transformer", which centralizes and simplifies the transform handling that used to be distributed between Reader and Writer objects. I brought PEP 258 up to date with this change and other recent changes. Transformer details can be found here: http://docutils.sf.net/spec/pep-0258.html#transformer http://docutils.sf.net/spec/transforms.html The change simplifies the project model considerably:: +---------------------------+ | Docutils: | | docutils.core.Publisher, | | docutils.core.publish_*() | +---------------------------+ / | \ / | \ 1,3,5 / 6 | \ 7 +--------+ +-------------+ +--------+ | READER | ----> | TRANSFORMER | ====> | WRITER | +--------+ +-------------+ +--------+ / \\ | / \\ | 2 / 4 \\ 8 | +-------+ +--------+ +--------+ | INPUT | | PARSER | | OUTPUT | +-------+ +--------+ +--------+ This change is internal and shouldn't have an impact on front ends or client code. If it breaks any code, please let me know. The latest snapshot is always available 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

More broken \ref links
by Neal Norwitz Oct. 22, 2002

Oct. 22, 2002

I guessed by replacing chop() with chomp() and this seemed to work. chop() removes the last char while chomp() removes whitespace. Is that correct? Is removing whitespace what was desired? clueless-ly y'rs, Neal

3 8

Re: [Doc-SIG] simple use of docutils
by Michael Hudson Oct. 18, 2002

Oct. 18, 2002

David Goodger <goodger(a)users.sourceforge.net> writes: > Michael Hudson wrote: > >>> WHY can't I just pass a filename or a file-like object in as > >>> destination? > >> > >> I'm trying to provide a uniform interface, no matter the input > >> source (string, single file, multiple files in directories, Python > >> module, Python package) and output destination (string, single > >> file, multiple files), not all of which are implemented yet. The > >> I/O classes store attributes of their data stores, such as paths > >> and encodings; the I/O classes handle the text decoding & encoding. > > > > I object (faintly :) to your invention of new classes for this. Why > > not use what's already there, i.e. the file interface? > > > > If you want strings, use a StringIO. The codecs.Stream{Reader,Writer} > > classes handle encodings. Etc. > ... > > It would be nice if you didn't *have* to learn a new set of classes > > to use docutils. The mantra "easy things should be easy, difficult > > things should be possible" is one I'm quite attached to. > > I can see your point, and I agree with what you say in the abstract. > The I/O classes may be a case of adding functionality before it's > required. However, I'm currently thinking about adding *more* > functionality to these classes. When you combine all the features > Docutils needs from its I/O, I'm not convinced that doing it piecemeal > is better: > > * Multiple input sources: single files, directory trees, Python > packages, strings. What's the interface going to be for these? Here's a suggestion: a file-like object or something you can iterate over to get file-like objects. That covers all the above rather easily. > * Multiple output destinations: single files, directory trees, > strings. single files & strings are easily handled by file-like objects. What interface do you suggest for outputting to multiple files? > * Transforms (& maybe command-line options) associated with the > source/destination type. For example, a "split a monolithic > document tree into multiple doctrees" transform for the directory > tree output destination. This is something we're currently > discussing on the docutils-develop list. Well, I don't know what this means, so I can't really comment. Sigh, another mailing list to join... > * Encoding support. This is what codes.Stream{Reader,Writer} are for. > The I/O classes are really just implementation details. Perhaps they > wouldn't be objectionable if better convenience functions existed? Perhaps. > ``docutils.core.publish()`` provides a dirt-simple interface for > file-to-file command-line processing (including stdin-to-stdout). > Would a ``publish_string`` convenience funcion (providing > string-to-string programmatic processing) appease you? Given that, > you could do your own I/O. True. > Of course, I'm open to convincing arguments. Or better yet, > convincing code. :-) Still no progress on this front, I'm afraid. Cheers, M. -- US elections For those of you fearing that the rest of the world might be making fun of the US because of this: Rest assured, we are. -- http://www.advogato.org/person/jameson/diary.html?start=12

2 1

broken \ref links
by Neal Norwitz Oct. 18, 2002

Oct. 18, 2002

The second oldest bug on SF is: http://python.org/sf/217195 \ref links are broken when there are multiple \refs on the same line. The problem seems to be in Doc/tools/node2label.pl around lines 47-57. I really don't know perl. I'm afraid to learn, :-) otherwise I'd suggest a fix. If someone has suggestions though, I will try them. Neal

3 5

Updates to Docutils
by David Goodger Oct. 18, 2002

Oct. 18, 2002

* Improved vertical whitespace issues with HTML output. This affects first and last elements in containers, and removes unnecessary top and bottom margins (resp.). For example, a literal block at the top of a table cell won't have a ridiculous top margin. * Changes to API details that affects client code: - Renamed transform method "transform" to "apply". - Renamed "options" to "settings" for runtime settings (as set by command-line options). Sometimes "option" (singular) became "settings" (plural). Some variations below: - document.options -> document.settings (stored in other objects as well) - option_spec -> settings_spec (not directives though) - OptionSpec -> SettingsSpec - cmdline_options -> settings_spec - relative_path_options -> relative_path_settings - option_default_overrides -> settings_default_overrides - core.Publisher.set_options -> core.Publisher.get_settings - Renamed core.publish() to core.publish_cmdline(), and added placeholders for new publish_string() and publish_file() convenience functions. Please make corresponding changes to client code. I'll be happy to help if it's non-trivial. I've updated many of the modules in the sandbox, but I may not have changed everything (or I may have changed too much). Individual authors, please test the updated code. Thanks. Gunnar, I wasn't able to update DocFactory. It seemed to be using "options" in different ways, doing its own config file parsing, and I didn't know which "options" to change to "settings". * Some bug fixes. -- 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