Mailman 3 June 2004 - Doc-SIG

Downloadable HTML from the trunk
by Fred L. Drake, Jr. June 18, 2004

June 18, 2004

I've changed the script I use to update the online version of the development docmentation so that when that's updated, a copy of the tarball is kept available for download. Both the online and downloadable forms of the development documentation are at: http://www.python.org/dev/doc/ -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

"csv-table" directive added
by David Goodger June 18, 2004

June 18, 2004

David Priest's "csv-table" directive has been added to the reStructuredText parser. Thanks David! Docs here: http://docutils.sf.net/docs/ref/rst/directives.html#csv-table Native speakers, please update the language files in docutils/parsers/rst/languages/. -- David Goodger <http://python.net/~goodger>

1 0

field-list-table better idea than list-table
by Beni Cherniavsky June 11, 2004

June 11, 2004

With reference to the `list-table`__ directive idea:: .. list-table:: * - Treat - Quantity - Description * - Albatross! - 299 - On a stick! * - Crunchy Frog! - 1499 - If we took the bones out, it wouldn't be crunchy, now would it? __ http://docutils.sourceforge.net/docs/dev/todo.html#body-list-table I think it's a sub-optimal idea because it tries to find an alternative representation for a table's *layout* instead of representing its *meaning*. I find this list completely unreadable - to see what's the meaning of "1499" I must note that it's the second field, go back to the top and find the second field there ("Quantity"). I things don't line up one under the other, some other reminder is necessary. There is a natural way in reST to provide such clues: field lists! I therefore propose a field-list-table directive. To separate the table lines one from the other (adjacent field lists would just be treated as one), the natural idea is making a bulleted list of field lists:: .. field-list-table:: :header: - :treat: Treat :quantity: Quantity :descr: Description - :treat: Albatross! :quantity: 299 :descr: On a stick! - :treat: Crunchy Frog! :quantity: 1499 :descr: If we took the bones out, it wouldn't be crunchy, now would it? Header rows ----------- Why have a separate header row? We cannot in general extract it from the used field names because a field name cannot contain everything one might put in a table cell (although we can offer the option for the simpler cases?). A separate header row also allows shorter field names and doesn't force one to rewrite the whole table when the header text changes. How it the header separated from the table? A transition (``-----``) would look good (I think) but is not allowed in this position by the current document parser (which is not entirely prohibitive - it's not a change to the document model because it will not be left in the document as a transition). I showed a ``:header:`` directive option which is simple but perhaps sub-optimal. Other ideas would be welcome. Why there is a bullet under ``:header:``? Recall that a table's header can consist of several rows. We can make it optional for the common case. How is column order determined? From the order of fields in the first header row. Field order in all other rows is ignored. As a side-effect, this allows trivial re-arrangement of columns. Spans ----- Column-spans are easy: just specify several field names together, separated by, say, a comma:: - :foo: abc :bar: def :baz: ghi - :foo, bar: quux :baz: qux In non-adjacent columns are specified in this way, we should either report an error or duplicate the value into each span of adjacent columns. I think I like the later more - a "logical span" approach. For big column-spans, it might be convenient to specify only the first and last fields:: - :foo-baz: quuux By using named fields, it becomes possible to omit fields in some rows without losing track of things, which is important if we want to allow row-spans (anybody who edited an HTML table with spans will know what I mean ;-). One possible syntax for row-spans is to simply treat any row where a field is missing as a row-span from the last row where it appeared. Leaving a field empty is still possible by writing a field with empty content. But perhaps this is too implicit. Another way would be to require an explicit continuation marker (``...``/``-"-``/``"``?) in all but the first row of a spanned field. If implemented, the same marker should also be supported in simple tables, which lack on row-spanning abilities. Header column idea ------------------ Another natural variant is to allow a description list with field lists as descriptions:: .. field-list-table:: :header: Treat :quantity: Quantity :descr: Description Albatross! :quantity: 299 :descr: On a stick! Crunchy Frog! :quantity: 1499 :descr: If we took the bones out, it wouldn't be crunchy, now would it? which would make the whole first column a header column. This has just as many rights to existance as a header row, but I don't think it should be introduced unless we find a syntax for it in ascii-art tables first... Besides, such syntax has drawbacks: it's limited to a single column and a single paragraph fitting on one source line. -- Beni Cherniavsky <cben(a)users.sf.net> Note that I can only read emails on week-ends.

4 6

objections to renaming "--exit" option / "exit_level" setting?
by David Goodger June 3, 2004

June 3, 2004

Does anybody use the "exit_level" setting ("--exit" option)? I'm thinking of changing the names to better reflect the function. From docs/config.txt: """ exit_level A system message level threshold; non-halting system messages at or above this level will produce a non-zero exit status at normal exit. Exit status is the maximum system message level plus 10 (11 for INFO, etc.). Default: disabled (5). Options: ``--exit``. """ I think the option originally suggested by Beni Cherniavsky, "--exit-status", is better. I'd also change the setting to "exit_status_level". I'm sending this message to gauge the impact; will this break a lot of people's systems? -- David Goodger <http://python.net/~goodger>

2 1

``invisible`` reST-directive
by Felix Wiemann June 3, 2004

June 3, 2004

I propose adding a new directive 'invisible' to the reST-syntax, which translates to the already existing doctree element 'comment'. Thus, comments could be written as:: Normal text. .. invisible:: This is a comment. This still belongs to the comment. Normal text again. IMO it's much more intuitive than the '..' syntax for comments. When the '.. invisible::' directive is available and when it is being used, we can start phasing out the present comment syntax. At first, old-style comments can issue an informational system message, so that one can start replacing old-style comments (with '..') by the 'invisible::' directive. After some moths, we can start issuing a warning on old-style comments. Again after some months, we can maybe change the warnings to errors (that doesn't have to be decided now) and start allowing directives with a single colon:: .. image: foo.png ... which is IMO much easier to write and a little bit better to read. (Of course, there is no need to drop support for the old syntax with two colons.) The new directive-syntax with one colon is only possible after having phased out the old comment-syntax -- see the second point in <http://docutils.sourceforge.net/spec/rst/alternatives.html#reworking-explic…>. IMO an invisible-directive would be a good way to get rid of the the unintuitive and difficult-to-explain comment-syntax *and* the double-colon directive-syntax. What do you think? -- When replying to my email address, ensure that the mail header contains 'Felix Wiemann'. Please don't send unrequested mails > 64 KB. <http://www.ososo.de/>

3 7

Re: changing comment & directive syntax
by Edward Loper June 1, 2004

June 1, 2004

Felix wrote: > Thus, comments could be written as:: > > Normal text. > > .. invisible:: This is a comment. > > This still belongs to the comment. > > Normal text again. I brought this up before, and I'm still +1 on it. I don't feel very strongly about the name. "comment::" makes the most sense to me, but I'd be ok with "invisible::" or "ignore::" or something like that, as well. How's this... 1. Add a new comment:: directive (or whatever you want to call it). 2. Change the docs to encourage people to use the new directive for comments. (I.e., under the ".." comment syntax, add a note that the prefered way to mark comments is with the directive.) 3. Put of the decision of whether to phase out the old ".." syntax for comments until later. I'm +1 for phasing it out eventually, but it's worth waiting to see if people like the new syntax and/or if people start editing their old documents to use the new syntax, before we make decisions about phasing out the old syntax. -Edward p.s., another good property of adding it as a directive instead of just "..": it gives people a keyword to search for, when they encounter it for the first time.

1 0

reStructuredText Cheat Sheet
by David Goodger June 1, 2004

June 1, 2004

I whipped together a cheat sheet for reStructuredText: 1 page for syntax, and a 1 page reference for directives and roles. Please take a look: <http://docutils.sf.net/docs/rst/cheatsheet.txt> (not meant to be converted to HTML; use the source text as-is). Feedback is welcome. -- David Goodger <http://python.net/~goodger>

1 0