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

In-line hyperlink alternatives
by Benja Fallenstein Nov. 16, 2002

Nov. 16, 2002

Hi, I'm new to this list but read the recent discussion about embedded hyperlinks in the archives. I find this issue quite important for plain-text readability: While for long URIs, putting them after a paragraph is good, for short URIs, it seems quite unnatural. (Short URIs include references to the root of a web site as well as most relative URIs-- both common cases for hyperlinks.) To give an example [see example.html], I often refer to web sites like this [http://example.com/]. Giving the example__ like this__ seems much less natural, and actually sometimes makes me not put in hyperlinks where I would normally put them (or if they're absolute, put them in like above, which reST renders by showing the URI). __ example.html __ http://example.com/ Of course, things like this_@_http://example.com would not help me with my problem in the least ;-) The 'most obvious' syntax extension to reST would, for me, be having the URI-in-square-brackets trap the last word, or last `backquoted phrase`, like the underscore put right after the word/phrase does. Obviously this doesn't work, since reST already interprets these differently. I have come up with an only slightly different possible syntax that doesn't seem to have been discussed before. The first goes like this: This is an example [-> http://www.example.com] of `embedded links` [-> http://www.example.com/links/]. I find it especially comfortable with relative URIs: To learn more about Foo [-> foo.html], go to the `class documentation` [-> class-foo.html]. Or go back to the index [-> ../index.html]. I really like the plain-text readability of this syntax. It does not use the underscores that usually indicate links within reST and is therefore inconsistent; I don't see this as a major problem, because I find the syntax quite indicative of its meaning, but if this is seen as a problem, another possibility is: This is an example [__ http://www.example.com]. However, I find that less readable. Both syntaxes share the problem that the markup that makes a word/a backquoted phrase into a hyperlink is not directly connected to the word/phrase itself. However, they are still unambiguous, and especially the first jumps clearly out to my eye. My personal feeling is that some conceptional purity should be sacrificed for plain-text readability here. Thanks for listening! - Benja

4 9

Update to Docutils
by David Goodger Nov. 16, 2002

Nov. 16, 2002

As always, the latest CVS snapshot can be had from http://docutils.sf.net/docutils-snapshot.tgz Embedded URIs in Hyperlink References ===================================== Back in June, Simon Budig proposed a new syntax for reStructuredText hyperlinks, to allow target URIs/URLs to be specified inline with the reference in the text. I was initially ambivalent/against the proposal (a similar mechanism was one of the flaws I found in my analysis of StructuredText!). One of the core values of reStructuredText is its readability, and although the proposed syntax offers convenience, I wasn't sure if the convenience was worth the cost. After a great deal of thought and much input from users, I've decided that there are reasonable use cases for such a construct, and we've settled on a reasonable syntax. The following syntax will be used:: See the `Python home page <http://www.python.org>`_ for info. This is exactly equivalent to:: See the `Python home page`_ for info. .. _Python home page: http://www.python.org As with the non-embedded reference forms, a single trailing underscore means "named", and you can use the same name to reference the same target URI again. Two trailing underscores means "anonymous"; the target URI cannot be referenced again. Full details can be found in the spec: http://docutils.sf.net/spec/rst/reStructuredText.html#embedded-uris Details of the issues considered and alternatives weighed can be found here: http://docutils.sf.net/spec/rst/alternatives.html#inline-external-targets Recognition of Schemeless Email Addresses in Targets ==================================================== The parser has always recognized bare standalone email addresses in text, like "Send email to jdoe(a)example.com", automatically prefixing a "mailto:" URI scheme. I noticed some cases of schemeless email addresses in explicit targets, like this:: .. _mail me: me(a)example.org Such targets were *not* getting a "mailto:" scheme prefix, resulting in bad hyperlinks. That's been fixed now, in explicit targets and in the new embedded URIs. French & Slovak Language Support ================================ New language modules have been contributed to Docutils: Slovak from Miroslav Vasko, and French from Stefane Fermigier. Already supported are German, Swedish, and English. New language modules are always welcome. They're easy to make; they're just translations of a couple dozen terms. See the newly expanded "Docutils Internationalization" for instructions: http://docutils.sf.net/spec/howto/i18n.html -- David Goodger <goodger(a)python.org> 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 1

Re: [Python-Dev] [maintenance doc updates]
by Patrick K. O'Brien Nov. 16, 2002

Nov. 16, 2002

On Friday 15 November 2002 06:59 pm, Fred L. Drake wrote: > The maintenance version of the documentation has been updated: > > http://www.python.org/dev/doc/maint22/ > > Small updates. > Add embarrassing note about sneaky feeping creaturism: > The "chars" argument to str.strip(), .lstrip(), and .rstrip(), as > well as the str.zfill() method, were all added in Python 2.2.2! > Woe to over-eager backporters! The string module docstrings for lstrip and rstrip need updating as well then. It looks like only strip has been updated so far. And it would be good if this argument was called the same thing in the string type as in the string module. The one calls it `sep` and the other `chars`. In fact, the docstring for string.strip mixes the two: def strip(s, chars=None): """strip(s [,chars]) -> string Return a copy of the string s with leading and trailing whitespace removed. If chars is given and not None, remove characters in sep instead. If chars is unicode, S will be converted to unicode before stripping. """ return s.strip(chars) The docstring for the type still calls it `sep`, as does lstrip and rstrip: PyDoc_STRVAR(strip__doc__, "S.strip([sep]) -> string or unicode\n\ \n\ Return a copy of the string S with leading and trailing\n\ whitespace removed.\n\ If sep is given and not None, remove characters in sep instead.\n\ If sep is unicode, S will be converted to unicode before stripping"); It looks like the documentation is consistent in calling it `chars`, but the implementation is lagging behind. -- Patrick K. O'Brien Orbtech http://www.orbtech.com/web/pobrien ----------------------------------------------- "Your source for Python programming expertise." -----------------------------------------------

1 0

RE: [Doc-SIG] In-line hyperlink alternatives
by Moore, Paul Nov. 15, 2002

Nov. 15, 2002

From: Benja Fallenstein [mailto:b.fallenstein@gmx.de] > I've come up with a third variation that doesn't break the _ > convention as much as the other two: > > An `example hyperlink` <http://example.com>_. [...] > Relative links are nice this way: > > > The `specification` <spec.html>_ is explicit about this: > no `identifier` <terms/identifier.html>_ may appear outside > the `correct context` <#context>_. I like this one! I'll leave implementation and consistency issues to David, but otherwise I'd say go for this. Paul.

1 0

in-line hyperlinks
by Brett Cannon Nov. 15, 2002

Nov. 15, 2002

Since this is my first post to the list I should probably introduce myself. My name is Brett Cannon and I write the python-dev Summary. That is also where my use of Docutils and reST stems from. This is also why I would love to see a way to do inline hyperlinks. David gave me the current front-runner for the syntax (`phrase reference <http://www.example.org/phrase_reference/>`__). I basically agree with the points made at http://docutils.sourceforge.net/spec/rst/alternatives.html#inline-external-… about it. I can only think of two possible alternatives that do not necessarily deal with all the points, but my at least aesthetically work. One is something along the lines of `phrase reference`->http://www.example.org/phrase_reference/ . I personally think it is a little less noisy then the front-runner, although I just realized that ambiguity with the ending of the hyperlink and possible punctuation might be an issue. I also realize that single word references probably will still require the back-ticks. The second possibility I thought of was `phrase reference`@http://www.example.org/phrase_reference/ . I think this also reads well since if you read it as a statement; "phrase statement at http..." . One possible problem is that it looks a little cluttered. So alternatives are `phrase reference`__ @http://www.example.org/phrase_reference/ or `phrase reference`_@_http://www.example.org/phrase_reference/ . There are also other ways to play with it such as changing the spacer to `_@ http... or ` @_http... to make sure that there is no chance of ambiguity. And all the variations that have a space deal with the issue of the hyperlink being tied to the last part of the phrase and thus creating a wrapping issue. Anyway, these are just some suggestions I came up with. I am willing to do my part to get in-line hyperlinks into reST if a reasonable syntax can be agreed upon. -Brett C.

3 4

Docutils Update: statemachine.ViewList
by David Goodger Nov. 8, 2002

Nov. 8, 2002

I've just checked in code for ViewList and StringList classes to docutils/statemachine.py. StringList objects are now used inside the state machine (the guts of the parser) instead of standard Python lists. The change should be internal-only, with no outside effects, but outside code should be tested. Please let me know if there are any problems. Here's the ViewList class docstring: List with extended functionality: slices of ViewList objects are child lists, linked to their parents. Changes made to a child list also affect the parent list. A child list is effectively a "view" (in the SQL sense) of the parent list. Changes to parent lists, however, do *not* affect active child lists. If a parent list is changed, any active child lists should be recreated. The start and end of the slice can be trimmed using the `trim_start()` and `trim_end()` methods, without affecting the parent list. The link between child and parent lists can be broken by calling `disconnect()` on the child list. Also, ViewList objects keep track of the source & offset of each item. This information is accessible via the `source()`, `offset()`, and `info()` methods. BTW, this solves the "include" directive problems brought up by Brett Porter last week. (A long way to go to fix a small problem! But it should pay off in the long term.) -- David Goodger <goodger(a)python.org> 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/ ------------------------------------------------------- This sf.net email is sponsored by: See the NEW Palm Tungsten T handheld. Power & Color in a compact size! http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0001en _______________________________________________ Docutils-develop mailing list Docutils-develop(a)lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/docutils-develop

1 0

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