Release 0.4

We should get Docutils 0.4 out soon, but we shouldn't just cut a "frozen snapshot" release. Here's a list of features (achievable in the short term) to include:

• [DONE in rev. 3901] Move support files to docutils/writers/support.
• [DONE in rev. 4163] Convert docutils/writers/support/* into individual writer packages.
• [DONE in rev. 3901] Remove docutils.transforms.html.StylesheetCheck (no longer needed because of the above change).
• [DONE in rev. 3962] Incorporate new branch policy into the docs. ("Development strategy" thread on Docutils-develop)
• [DONE in rev. 4152] Added East-Asian double-width character support.
• [DONE in rev. 4156] Merge the S5 branch.

Anything else?

Once released,

• Tag it and create a maintenance branch (perhaps "maint-0-4").
• Declare that:
  • Docutils 0.4.x is the last version that will support Python 2.1 (and perhaps higher?)
  • Docutils 0.4.x is the last version that will support (make compromises for) Netscape Navigator 4

Minimum Requirements for Python Standard Library Candidacy

Below are action items that must be added and issues that must be addressed before Docutils can be considered suitable to be proposed for inclusion in the Python standard library.

• Support for document splitting. May require some major code rework.
• Support for subdocuments (see large documents).
• Object numbering and object references.
• Nested inline markup.
• Python Source Reader.
• The HTML writer needs to be rewritten (or a second HTML writer added) to allow for custom classes, and for arbitrary splitting (stack-based?).
• Documentation of the architecture. Other docs too.
• Plugin support.
• A LaTeX writer making use of (La)TeX's power, so that the rendering of the resulting documents is more easily customizable. (Similar to what you wrote about a new HTML Writer.)
• Suitability for Python module documentation.

General

• Allow different report levels for STDERR and system_messages inside the document?

• Change the docutils-update script (in sandbox/infrastructure), to support arbitrary branch snapshots.

• Add a generic "container" element, equivalent to "inline", to which a "class" attribute can be attached. Will require a reST directive also.

• Move some general-interest sandboxes out of individuals' directories, into subprojects?

• Add option for file (and URL) access restriction to make Docutils usable in Wikis and similar applications.

  2005-03-21: added file_insertion_enabled & raw_enabled settings. These partially solve the problem, allowing or disabling all file accesses, but not limited access.

• Configuration file handling needs discussion:

  • There should be some error checking on the contents of config files. How much checking should be done? How loudly should Docutils complain if it encounters an error/problem?
  • Docutils doesn't complain when it doesn't find a configuration file supplied with the --config option. Should it? (If yes, error or warning?)

• Internationalization:

  • I18n needs refactoring, the language dictionaries are difficult to maintain. Maybe have a look at gettext or similar tools.
  • Language modules: in accented languages it may be useful to have both accented and unaccented entries in the bibliographic_fields mapping for versatility.
  • Add a "--strict-language" option & setting: no English fallback for language-dependent features.
  • Add internationalization to footer boilerplate text (resulting from "--generator", "--source-link", and "--date" etc.), allowing translations.

• Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.

• In docutils.readers.get_reader_class (& parsers & writers too), should we be importing "standalone" or "docutils.readers.standalone"? (This would avoid importing top-level modules if the module name is not in docutils/readers. Potential nastiness.)

• Perhaps store a name-to-id mapping file? This could be stored permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?)

• Perhaps the Component.supports method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)?

• Add object numbering and object references (tables & figures). These would be the equivalent of DocBook's "formal" elements.

  We may need persistent sequences, such as chapter numbers. See OpenOffice.org XML "fields". Should the sequences be automatic or manual (user-specifyable)?

  We need to name the objects:

  • "name" option for the "figure" directive?

    .. figure:: image.png
       :name: image's name
    

    Same for the "table" directive:

    .. table:: optional title here
       :name: table's name
    
       =====  =====
         x    not x
       =====  =====
       True   False
       False  True
       =====  =====
    

    This would also allow other options to be set, like border styles. The same technique could be used for other objects.

    A preliminary "table" directive has been implemented, supporting table titles. Perhaps the name should derive from the title.

  • The object could also be done this way:

    .. _figure name:
    
    .. figure:: image.png
    

    This may be a more general solution, equally applicable to tables. However, explicit naming using an option seems simpler to users.

  • Perhaps the figure name could be incorporated into the figure definition, as an optional inline target part of the directive argument:

    .. figure:: _`figure name` image.png
    

    Maybe with a delimiter:

    .. figure:: _`figure name`: image.png
    

    Or some other, simpler syntax.

  We'll also need syntax for object references. See OpenOffice.org XML "reference fields":

  • Parameterized substitutions? For example:

    See |figure (figure name)| on |page (figure name)|.
    
    .. |figure (name)| figure-ref:: (name)
    .. |page (name)| page-ref:: (name)
    

    The result would be:

    See figure 3.11 on page 157.
    

    But this would require substitution directives to be processed at reference-time, not at definition-time as they are now. Or, perhaps the directives could just leave pending elements behind, and the transforms do the work? How to pass the data through? Too complicated.

  • An interpreted text approach is simpler and better:

    See :figure:`figure name` on :page:`figure name`.
    

    The "figure" and "page" roles could generate appropriate boilerplate text. The position of the role (prefix or suffix) could also be utilized.

    See Interpreted Text below.

  • We could leave the boilerplate text up to the document:

    See Figure :fig:`figure name` on page :pg:`figure name`.
    

  • Reference boilerplate could be specified in the document (defaulting to nothing):

    .. fignum::
       :prefix-ref: "Figure "
       :prefix-caption: "Fig. "
       :suffix-caption: :
    

• Think about large documents made up of multiple subdocument files. Issues: continuity (persistent sequences above), cross-references (name-to-id mapping file above and targets in other documents below), splitting (document splitting below).

  When writing a book, the author probably wants to split it up into files, perhaps one per chapter (but perhaps even more detailed). However, we'd like to be able to have references from one chapter to another, and have continuous numbering (pages and chapters, as applicable). Of course, none of this is implemented yet. There has been some thought put into some aspects; see the "include" directive and the Reference Merging transform below.

  When I was working with SGML in Japan, we had a system where there was a top-level coordinating file, book.sgml, which contained the top-level structure of a book: the <book> element, containing the book <title> and empty component elements (<preface>, <chapter>, <appendix>, etc.), each with filename attributes pointing to the actual source for the component. Something like this:

  <book id="bk01">
  <title>Title of the Book</title>
  <preface inrefid="pr01"></preface>
  <chapter inrefid="ch01"></chapter>
  <chapter inrefid="ch02"></chapter>
  <chapter inrefid="ch03"></chapter>
  <appendix inrefid="ap01"></appendix>
  </book>
  

  (The "inrefid" attribute stood for "insertion reference ID".)

  The processing system would process each component separately, but it would recognize and use the book file to coordinate chapter and page numbering, and keep a persistent ID to (title, page number) mapping database for cross-references. Docutils could use a similar system for large-scale, multipart documents.

  Aahz's idea:

  First the ToC:

  .. ToC-list::
      Introduction.txt
      Objects.txt
      Data.txt
      Control.txt
  

  Then a sample use:

  .. include:: ToC.txt
  
  As I said earlier in chapter :chapter:`Objects.txt`, the
  reference count gets increased every time a binding is made.
  

  Which produces:

  As I said earlier in chapter 2, the
  reference count gets increased every time a binding is made.
  

  The ToC in this form doesn't even need to be references to actual reST documents; I'm simply doing it that way for a minimum of future-proofing, in case I do want to add the ability to pick up references within external chapters.

  Perhaps, instead of ToC (which would overload the "contents" directive concept already in use), we could use "manifest". A "manifest" directive might associate local reference names with files:

  .. manifest::
     intro: Introduction.txt
     objects: Objects.txt
     data: Data.txt
     control: Control.txt
  

  Then the sample becomes:

  .. include:: manifest.txt
  
  As I said earlier in chapter :chapter:`objects`, the
  reference count gets increased every time a binding is made.
  

• Add support for multiple output files.

• Add testing for Docutils' front end tools?

• Publisher: "Ordinary setup" shouldn't requre specific ordering; at the very least, there ought to be error checking higher up in the call chain. [Aahz]

  Publisher.get_settings requires that all components be set up before it's called. Perhaps the I/O objects shouldn't be set, but I/O classes. Then options are set up (.set_options), and Publisher.set_io (or equivalent code) is called with source & destination paths, creating the I/O objects.

  Perhaps I/O objects shouldn't be instantiated until required. For split output, the Writer may be called multiple times, once for each doctree, and each doctree should have a separate Output object (with a different path). Is the "Builder" pattern applicable here?

• Perhaps I/O objects should become full-fledged components (i.e. subclasses of docutils.Component, as are Readers, Parsers, and Writers now), and thus have associated option/setting specs and transforms.

• Multiple file I/O suggestion from Michael Hudson: use a file-like object or something you can iterate over to get file-like objects.

• Add an "--input-language" option & setting? Specify a different language module for input (bibliographic fields, directives) than for output. The "--language" option would set both input & output languages.

• Auto-generate reference tables for language-dependent features? Could be generated from the source modules. A special command-line option could be added to Docutils front ends to do this. (Idea from Engelbert Gruber.)

• Enable feedback of some kind from internal decisions, such as reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output?

• Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.

• Merge docs/user/latex.txt info into tools.txt and config.txt.

• Add an "--include file" command-line option (config setting too?), equivalent to ".. include:: file" as the first line of the doc text? Especially useful for character entity sets, text transform specs, boilerplate, etc.

• Parameterize the Reporter object or class? See the 2004-02-18 "rest checking and source path" thread.

• Add a "disable_transforms" setting? And a dummy Writer subclass that does nothing when its .write() method is called? Would allow for easy syntax checking. See the 2004-02-18 "rest checking and source path" thread.

• Add a generic meta-stylesheet mechanism? An external file could associate style names ("class" attributes) with specific elements. Could be generalized to arbitrary output attributes; useful for HTML & XMLs. Aahz implemented something like this in sandbox/aahz/Effective/EffMap.py.

• William Dode suggested that table cells be assigned "class" attributes by columns, so that stylesheets can affect text alignment. Unfortunately, there doesn't seem to be a way (in HTML at least) to leverage the "colspec" elements (HTML "col" tags) by adding classes to them. The resulting HTML is very verbose:

  <td class="col1">111</td>
  <td class="col2">222</td>
  ...
  

  At the very least, it should be an option. People who don't use it shouldn't be penalized by increases in their HTML file sizes.

  Table rows could also be assigned classes (like odd/even). That would be easier to implement.

  How should it be implemented?

  • There could be writer options (column classes & row classes) with standard values.
  • The table directive could grow some options. Something like ":cell-classes: col1 col2 col3" (either must match the number of columns, or repeat to fill?) and ":row-classes: odd even" (repeat to fill; body rows only, or header rows too?).

  Probably per-table directive options are best. The "class" values could be used by any writer, and applying such classes to all tables in a document with writer options is too broad.

• Add file-specific settings support to config files, like:

  [file index.txt]
  compact-lists: no
  

  Is this even possible? Should the criterion be the name of the input file or the output file?

• The "validator" support added to OptionParser is very similar to "traits" in SciPy. Perhaps something could be done with them? (Had I known about traits when I was implementing docutils.frontend, I may have used them instead of rolling my own.)

• tools/buildhtml.py: Extend the --prune option ("prune" config setting) to accept file names (generic path) in addition to directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should not be converted to HTML).

• Add support for plugins.

• Config directories: Currently, ~/.docutils, ./docutils.conf/, & /etc/docutils.conf are read as configuration files. Proposal: allow ~/.docutils to be a a configuration directory, along with /etc/docutils/ and ./docutils.conf/. Within these directories, check for config.txt files. We can also have subdirectories here, for plugins, S5 themes, components (readers/writers/parsers) etc.

  Docutils will continue to support configuration files for backwards compatibility.

• Add support for document decorations other than headers & footers? For example, top/bottom/side navigation bars for web pages. Generic decorations?

  Seems like a bad idea as long as it isn't independent from the ouput format (for example, navigation bars are only useful for web pages).

• docutils_update: Check for a Makefile in a directory, and run make if found? This would allow for variant processing on specific source files, such as running rst2s5.py instead of rst2html.py.

• Add a "disable table of contents" setting? The S5 writer could set it as a default. Rationale:

  The contents (table of contents) directive must not be used [in S5/HTML documents]. It changes the CSS class of headings and they won't show up correctly in the screen presentation.

  —Easy Slide Shows With reStructuredText & S5

Documentation

Python Source Reader

General:

• Analyze Tony Ibbs' PySource code.
• Analyze Doug Hellmann's HappyDoc project.
• Investigate how POD handles literate programming.
• Take the best ideas and integrate them into Docutils.

Miscellaneous ideas:

• Ask Python-dev for opinions (GvR for a pronouncement) on special variables (__author__, __version__, etc.): convenience vs. namespace pollution. Ask opinions on whether or not Docutils should recognize & use them.

• If we can detect that a comment block begins with ##, a la JavaDoc, it might be useful to indicate interspersed section headers & explanatory text in a module. For example:

  """Module docstring."""
  
  ##
  # Constants
  # =========
  
  a = 1
  b = 2
  
  ##
  # Exception Classes
  # =================
  
  class MyException(Exception): pass
  
  # etc.
  

• Should standalone strings also become (module/class) docstrings? Under what conditions? We want to prevent arbitrary strings from becomming docstrings of prior attribute assignments etc. Assume that there must be no blank lines between attributes and attribute docstrings? (Use lineno of NEWLINE token.)

  Triple-quotes are sometimes used for multi-line comments (such as commenting out blocks of code). How to reconcile?

• HappyDoc's idea of using comment blocks when there's no docstring may be useful to get around the conflict between additional docstrings and from __future__ import for module docstrings. A module could begin like this:

  #!/usr/bin/env python
  # :Author: Me
  # :Copyright: whatever
  
  """This is the public module docstring (``__doc__``)."""
  
  # More docs, in comments.
  # All comments at the beginning of a module could be
  # accumulated as docstrings.
  # We can't have another docstring here, because of the
  # ``__future__`` statement.
  
  from __future__ import division
  

  Using the JavaDoc convention of a doc-comment block beginning with ## is useful though. It allows doc-comments and implementation comments.

• HappyDoc uses an initial comment block to set "parser configuration values". Do the same thing for Docutils, to set runtime settings on a per-module basis? I.e.:

  # Docutils:setting=value
  

  Could be used to turn on/off function parameter comment recognition & other marginal features. Could be used as a general mechanism to augment config files and command-line options (but which takes precedence?).

• Multi-file output should be divisible at arbitrary level.

• Support all forms of import statements:

  • import module: listed as "module"
  • import module as alias: "alias (module)"
  • from module import identifier: "identifier (from module)"
  • from module import identifier as alias: "alias (identifier from module)"
  • from module import *: "all identifiers (*) from module"

• Have links to colorized Python source files from API docs? And vice-versa: backlinks from the colorized source files to the API docs!

• In summaries, use the first sentence of a docstring if the first line is not followed by a blank line.

reStructuredText Parser

Also see the ... Or Not To Do? list.

• Treat enumerated lists that are not arabic and consist of only one item in a single line as ordinary paragraphs. See <http://article.gmane.org/gmane.text.docutils.user/2635>.

• The citation syntax could use some enhancements. See <http://thread.gmane.org/gmane.text.docutils.user/2499> and <http://thread.gmane.org/gmane.text.docutils.user/2443>.

• The current list-recognition logic has too many false positives, as in

  * Aorta
  * V. cava superior
  * V. cava inferior
  

  Here V. is recognized as an enumerator, which leads to confusion. We need to find a solution that resolves such problems without complicating the spec to much.

  See <http://thread.gmane.org/gmane.text.docutils.user/2524>.

• Add indirect links via citation references & footnote references. Example:

  `Goodger (2005)`_ is helpful.
  
  .. _Goodger (2005): [goodger2005]_
  .. [goodger2005] citation text
  

  See <http://thread.gmane.org/gmane.text.docutils.user/2499>.

• Allow multiple block quotes, only separated by attributions (http://article.gmane.org/gmane.text.docutils.devel/2985), e.g.:

  quote 1
  
  ---Attrib 1
  
  quote 2
  
  ---Attrib 2
  

• Change the specification so that more punctuation is allowed before/after inline markup start/end string (http://article.gmane.org/gmane.text.docutils.cvs/3824).

• Complain about bad URI characters (http://article.gmane.org/gmane.text.docutils.user/2046) and disallow internal whitespace (http://article.gmane.org/gmane.text.docutils.user/2214).

• Create info-level system messages for unnecessarily backslash-escaped characters (as in "\something", rendered as "something") to allow checking for errors which silently slipped through.

• Add (functional) tests for untested roles.

• Add test for ":figwidth: image" option of "figure" directive. (Test code needs to check if PIL is available on the system.)

• Add support for CJK double-width whitespace (indentation) & punctuation characters (markup; e.g. double-width "*", "-", "+")?

• Add motivation sections for constructs in spec.

• Support generic hyperlink references to targets in other documents? Not in an HTML-centric way, though (it's trivial to say http://www.example.com/doc#name, and useless in non-HTML contexts). XLink/XPointer? .. baseref::? See Doc-SIG 2001-08-10.

• In target URLs, it would be useful to not explicitly specify the file extension. If we're generating HTML, then ".html" is appropriate; if PDF, then ".pdf"; etc. How about using ".*" to indicate "choose the most appropriate filename extension"? For example:

  .. _Another Document: another.*
  

  What is to be done for output formats that don't have hyperlinks? For example, LaTeX targeted at print. Hyperlinks may be "called out", as footnotes with explicit URLs.

  But then there's also LaTeX targeted at PDFs, which can have links. Perhaps a runtime setting for "*" could explicitly provide the extension, defaulting to the output file's extension.

  Should the system check for existing files? No, not practical.

  Handle documents only, or objects (images, etc.) also?

  If this handles images also, how to differentiate between document and image links? Element context (within "image")? Which image extension to use for which document format? Again, a runtime setting would suffice.

  This may not be just a parser issue; it may need framework support.

  Mailing list threads: Images in both HTML and LaTeX (especially this summary of Felix's objections), more-universal links?, Output-format-sensitive link targets?

• Implement the header row separator modification to table.el. (Wrote to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting support for "=====" header rows. On 2001-08-17 he replied, saying he'd put it on his to-do list, but "don't hold your breath".)

• Fix the parser's indentation handling to conform with the stricter definition in the spec. (Explicit markup blocks should be strict or forgiving?)

• Make the parser modular. Allow syntax constructs to be added or disabled at run-time. Subclassing is probably not enough because it makes it difficult to apply multiple extensions.

• Generalize the "doctest block" construct (which is overly Python-centric) to other interactive sessions? "Doctest block" could be renamed to "I/O block" or "interactive block", and each of these could also be recognized as such by the parser:

  • Shell sessions:

    $ cat example1.txt
    A block beginning with a "$ " prompt is interpreted as a shell
    session interactive block.  As with Doctest blocks, the
    interactive block ends with the first blank line, and wouldn't
    have to be indented.
    

  • Root shell sessions:

    # cat example2.txt
    A block beginning with a "# " prompt is interpreted as a root
    shell session (the user is or has to be logged in as root)
    interactive block.  Again, the block ends with a blank line.
    

  Other standard (and unambiguous) interactive session prompts could easily be added (such as "> " for WinDOS).

  Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback").

• The "doctest" element should go away. The construct could simply be a front-end to generic literal blocks. We could immediately (in 0.4, or 0.5) remove the doctest node from the doctree, but leave the syntax in reST. The reST parser could represent doctest blocks as literal blocks with a class attribute. The syntax could be left in reST for a set period of time.

• Add support for pragma (syntax-altering) directives.

  Some pragma directives could be local-scope unless explicitly specified as global/pragma using ":global:" options.

• Support whitespace in angle-bracketed standalone URLs according to Appendix E ("Recommendations for Delimiting URI in Context") of RFC 2396.

• Use the vertical spacing of the source text to determine the corresponding vertical spacing of the output?

• [From Mark Nodine] For cells in simple tables that comprise a single line, the justification can be inferred according to the following rules:

  1. If the text begins at the leftmost column of the cell, then left justification, ELSE
  2. If the text begins at the rightmost column of the cell, then right justification, ELSE
  3. Center justification.

  The onus is on the author to make the text unambiguous by adding blank columns as necessary. There should be a parser setting to turn off justification-recognition (normally on would be fine).

  Decimal justification?

  All this shouldn't be done automatically. Only when it's requested by the user, e.g. with something like this:

  .. table::
     :auto-indent:
  
     (Table goes here.)
  

  Otherwise it will break existing documents.

• Generate a warning or info message for paragraphs which should have been lists, like this one:

  1. line one
  3. line two
  

• Generalize the "target-notes" directive into a command-line option somehow? See docutils-develop 2003-02-13.

• Allow a "::"-only paragraph (first line, actually) to introduce a literal block without a blank line? (Idea from Paul Moore.)

  ::
      This is a literal block
  

  Is indentation enough to make the separation between a paragraph which contains just a :: and the literal text unambiguous? (There's one problem with this concession: If one wants a definition list item which defines the term "::", we'd have to escape it.) It would only be reasonable to apply it to "::"-only paragraphs though. I think the blank line is visually necessary if there's text before the "::":

  The text in this paragraph needs separation
  from the literal block following::
      This doesn't look right.
  

• Add new syntax for nested inline markup? Or extend the parser to parse nested inline markup somehow? See the collected notes.

• Drop the backticks from embedded URIs with omitted reference text? Should the angle brackets be kept in the output or not?

  <file_name>_
  

  Probably not worth the trouble.

• Add math markup. We should try for a general solution, that's applicable to any output format. Using a standard, such as MathML, would be best. TeX (or itex) would be acceptable as a front-end to MathML. See the culmination of a relevant discussion.

  Both a directive and an interpreted text role will be necessary (for each markup). Directive example:

  .. itex::
     \alpha_t(i) = P(O_1, O_2, \dots O_t, q_t = S_i \lambda)
  

  The same thing inline:

  The equation in question is :itex:`\alpha_t(i) = P(O_1, O_2,
  \dots O_t, q_t = S_i \lambda)`.
  

• How about a syntax for alternative hyperlink behavior, such as "open in a new window" (as in HTML's <a target="_blank">)? Double angle brackets might work for inline targets:

  The `reference docs <<url>>`__ may be handy.
  

  But what about explicit targets?

  The MoinMoin wiki uses a caret ("^") at the beginning of the URL ("^" is not a legal URI character). That could work for both inline and explicit targets:

  The `reference docs <^url>`__ may be handy.
  
  .. _name: ^url
  

  This may be too specific to HTML. It hasn't been requested very often either.

• Add an option to add URI schemes at runtime.

• Segmented lists:

  : segment : segment : segment
  : segment : segment : very long
    segment
  : segment : segment : segment
  

  The initial colon (":") can be thought of as a type of bullet

  We could even have segment titles:

  :: title  : title   : title
  : segment : segment : segment
  : segment : segment : segment
  

  This would correspond well to DocBook's SegmentedList. Output could be tabular or "name: value" pairs, as described in DocBook's docs.

• Allow backslash-escaped colons in field names:

  :Case Study\: Event Handling: This chapter will be dropped.
  

• footnote spaces:

  When supplying the command line options --footnote-references=brackets and --use-latex-footnotes with the LaTeX writer (which might very well happen when using configuration files), the spaces in front of footnote references aren't trimmed.

• Enable grid tables inside XML comments, where "--" ends comments. I see three implementation possibilities:

  1. Make the table syntax characters into "table" directive options. This is the most flexible but most difficult, and we probably don't need that much flexibility.
  2. Substitute "~" for "-" with a specialized directive option (e.g. ":tildes:").
  3. Make the standard table syntax recognize "~" as well as "-", even without a directive option. Individual tables would have to be internally consistent.

  Directive options are preferable to configuration settings, because tables are document-specific. A pragma directive would be another approach, to set the syntax once for a whole document.

  In the meantime, the list-table directive is a good replacement for grid tables inside XML comments.

• Generalize docinfo contents (bibliographic fields): remove specific fields, and have only a single generic "field"?

Unimplemented Transforms

• Footnote & Citation Gathering

  Collect and move footnotes & citations to the end of a document. (Separate transforms.)

• Reference Merging

  When merging two or more subdocuments (such as docstrings), conflicting references may need to be resolved. There may be:

  • duplicate reference and/or substitution names that need to be made unique; and/or
  • duplicate footnote numbers that need to be renumbered.

  Should this be done before or after reference-resolving transforms are applied? What about references from within one subdocument to inside another?

• Document Splitting

  If the processed document is written to multiple files (possibly in a directory tree), it will need to be split up. Internal references will have to be adjusted.

  (HTML only? Initially, yes. Eventually, anything should be splittable.)

  Ideas:

  • Insert a "destination" attribute into the root element of each split-out document, containing the path/filename. The Output object or Writer will recognize this attribute and split out the files accordingly. Must allow for common headers & footers, prev/next, breadcrumbs, etc.

  • Transform a single-root document into a document containing multiple subdocuments, recursively. The content model of the "document" element would have to change to:

    <!ELEMENT document
        ( (title, subtitle?)?,
          decoration?,
          (docinfo, transition?)?,
          %structure.model;,
          document* )>
    

    (I.e., add the last line -- 0 or more document elements.)

    Let's look at the case of hierarchical (directories and files) HTML output. Each document element containing further document elements would correspond to a directory (with an index.html file for the content preceding the subdocuments). Each document element containing no subdocuments (i.e., structure model elements only) corresponds to a concrete file with no directory.

    The natural transform would be to map sections to subdocuments, but possibly only a given number of levels deep.

• Navigation

  If a document is split up, each segment will need navigation links: parent, children (small TOC), previous (preorder), next (preorder). Part of Document Splitting?

• List of System Messages

  The system_message elements are inserted into the document tree, adjacent to the problems themselves where possible. Some (those generated post-parse) are kept until later, in document.messages, and added as a special final section, "Docutils System Messages".

  Docutils could be made to generate hyperlinks to all known system_messages and add them to the document, perhaps to the end of the "Docutils System Messages" section.

  Fred L. Drake, Jr. wrote:

  I'd like to propose that both parse- and transformation-time messages are included in the "Docutils System Messages" section. If there are no objections, I can make the change.

  The advantage of the current way of doing things is that parse-time system messages don't require a transform; they're already in the document. This is valuable for testing (unit tests, tools/quicktest.py). So if we do decide to make a change, I think the insertion of parse-time system messages ought to remain as-is and the Messages transform ought to move all parse-time system messages (remove from their originally inserted positions, insert in System Messages section).

• Index Generation

HTML Writer

• Add support for multiple stylesheets. See <http://thread.gmane.org/gmane.text.docutils.cvs/4336>.

• Idea for field-list rendering: hanging indent:

  Field name (bold): First paragraph of field body begins
      with the field name inline.
  
      If the first item of a field body is not a paragraph,
      it would begin on the following line.
  

• Add more support for <link> elements, especially for navigation bars.

  The framework does not have a notion of document relationships, so probably raw.destination should be used.

  We'll have framework support for document relationships when support for multiple output files is added. The HTML writer could automatically generate <link> elements then.

• Base list compaction on the spacing of source list? Would require parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)

• Add a tool tip ("title" attribute?) to footnote back-links identifying them as such. Text in Docutils language module.

PEP/HTML Writer

• Remove the generic style information (duplicated from html4css1.css) from pep.css to avoid redundancy.

  We need support for multiple stylesheets first, though.

LaTeX writer

• Add an --embed-stylesheet (and --link-stylesheet) option.

HTML SlideShow Writer

Add a Writer for presentations, derivative of the HTML Writer. Given an input document containing one section per slide, the output would consist of a master document for the speaker, and a slide file (or set of filess, one (or more) for each slide). Each slide would contain the slide text (large, stylesheet-controlled) and images, plus "next" and "previous" links in consistent places. The speaker's master document would contain a small version of the slide text with speaker's notes interspersed. The master document could use target="whatever" to direct links to a separate window on a second monitor (e.g., a projector).

Ideas:

• Base the output on S⁵. I discovered S⁵ a few weeks before it appeared on Slashdot, after writing most of this section. It turns out that S⁵ does most of what I wanted.

  Chris Liechti has integrated S5 with the HTML writer.

Below, "[S5]" indicates that S⁵ already implements the feature or may implement all or part of the feature. "[S5 1.1]" indicates that S⁵ version 1.1 implements the feature (a preview of the 1.1 beta is available in the S5 testbed).

Features & issues:

• [S5 1.1] Incremental slides, where each slide adds to the one before (ticking off items in a list, delaying display of later items). The speaker's master document would list each transition in the TOC and provide links in the content.

  • Use transitions to separate stages. Problem with transitions is that they can't be used everywhere -- not, for example, within a list (see the example below).

  • Use a special directive to separate stages. Possible names: pause, delay, break, cut, continue, suspend, hold, stay, stop. Should the directive be available in all contexts (and ineffectual in all but SlideShow context), or added at runtime by the SlideShow Writer? Probably such a "pause" directive should only be available for slide shows; slide shows are too much of a special case to justify adding a directive (and node?) to the core.

    The directive could accept text content, which would be rendered while paused but would disappear when the slide is continued (the text could also be a link to the next slide). In the speaker's master document, the text "paused:" could appear, prefixed to the directive text.

  • Use a special directive or class to declare incremental content. This works best with the S5 ideas. For example:

    Slide Title
    ===========
    
    .. incremental::
    
       * item one
       * item two
       * item three
    

    Add an option to make all bullet lists implicitly incremental?

• Speaker's notes -- how to intersperse? Could use reST comments (".."), but make them visible in the speaker's master document. If structure is necessary, we could use a "comment" directive (to avoid nonsensical DTD changes, the "comment" directive could produce an untitled topic element).

  The speaker's notes could (should?) be separate from S5's handout content.

• The speaker's master document could use frames for easy navigation: TOC on the left, content on the right.

  • It would be nice if clicking in the TOC frame simultaneously linked to both the speaker's notes frame and to the slide window, synchronizing both. Needs JavaScript?
  • TOC would have to be tightly formatted -- minimal indentation.
  • TOC auto-generated, as in the PEP Reader. (What if there already is a "contents" directive in the document?)
  • There could be another frame on the left (top-left or bottom-left) containing a single "Next" link, always pointing to the next slide (synchronized, of course). Also "Previous" link? FF/Rew go to the beginning of the next/current parent section? First/Last also? Tape-player-style buttons like |<<  <<  <  >  >>  >>|?

• [S5] Need to support templating of some kind, for uniform slide layout. S5 handles this via CSS.

  Build in support for limited features? E.g., top/bottom or left/right banners, images on each page, background color and/or image, etc.

• [S5?] One layout for all slides, or allow some variation?

  While S5 seems to support only one style per HTML file, it's pretty easy to split a presentation in different files and insert a hyperlink to the last slide of the first part and load the second part by a click on it.

  —Chris Liechti

• For nested sections, do we show the section's ancestry on each slide? Optional? No -- leave the implementation to someone who wants it.

• [S5] Stylesheets for slides:

  • Tweaked for different resolutions, 1024x768 etc.
  • Some layout elements have fixed positions.
  • Text must be quite large.
  • Allow 10 lines of text per slide? 15?
  • Title styles vary by level, but not so much?

• [not required with S5.] Need a transform to number slides for output filenames?, and for hyperlinks?

• Directive to begin a new, untitled (blank) slide?

• Directive to begin a new slide, continuation, using the same title as the previous slide? (Unnecessary?)

• Have a timeout on incremental items, so the colour goes away after 1 second.

Here's an example that I was hoping to show at PyCon DC 2005:

========================
 The Docutils SlideShow
========================

Welcome To The Docutils SlideShow!
==================================

.. pause::

David Goodger

goodger@python.org

http://python.net/~goodger

.. (introduce yourself)

   Hi, I'm David Goodger from Montreal, Canada.

   I've been working on Docutils since 2000.
   Time flies!

.. pause::

Docutils

http://docutils.sourceforge.net

.. I also volunteer as a Python Enhancement Proposal (or PEP)
   editor.

.. SlideShow is a new feature of Docutils.  This presentation was
   written using the Docutils SlideShow system.  The slides you
   are seeing are HTML, rendered by a standard Mozilla Firefox
   browser.


The Docutils SlideShow System
=============================

.. The Docutils SlideShow System provides

Easy and open presentations.


Features
========

* reStructuredText-based input files.

  .. reStructuredText is a what-you-see-is-what-you-get
     plaintext format.  Easy to read & write, non-proprietary,
     editable in your favourite text editor.

  .. Parsers for other markup languages can be added to Docutils.
     In the future, I hope some are.

  .. pause:: ...

* Stylesheet-driven HTML output.

  .. The format of all elements of the output slides are
     controlled by CSS (cascading stylesheets).

  .. pause:: ...

* Works with any modern browser.

  .. that supports CSS, frames, and JavaScript.
     Tested with Mozilla Firefox.

  .. pause:: ...

* Works on any OS.


Etc.
====

That's as far as I got, but you get the idea...

Front-End Tools

• What about if we don't know which Reader and/or Writer we are going to use? If the Reader/Writer is specified on the command-line? (Will this ever happen?)

  Perhaps have different types of front ends:

  1. Fully qualified: Reader and Writer are hard-coded into the front end (e.g. pep2html [options], pysource2pdf [options]).
  2. Partially qualified: Reader is hard-coded, and the Writer is specified a sub-command (e.g. pep2 html [options], pysource2 pdf [options]). The Writer is known before option processing happens, allowing the OptionParser to be built dynamically. Alternatively, the Writer could be hard-coded and the Reader specified as a sub-command (e.g. htmlfrom pep [options]).
  3. Unqualified: Reader and Writer are specified as subcommands (e.g. publish pep html [options], publish pysource pdf [options]). A single front end would be sufficient, but probably only useful for testing purposes.
  4. Dynamic: Reader and/or Writer are specified by options, with defaults if unspecified (e.g. publish --writer pdf [options]). Is this possible? The option parser would have to be told about new options it needs to handle, on the fly. Component-specific options would have to be specified after the component-specifying option.

  Allow common options before subcommands, as in CVS? Or group all options together? In the case of the fully qualified front ends, all the options will have to be grouped together anyway, so there's no advantage (we can't use it to avoid conflicts) to splitting common and component-specific options apart.

• Parameterize help text & defaults somehow? Perhaps a callback? Or initialize settings_spec in __init__ or init_options?

• Disable common options that don't apply?

• Add --section-numbering command line option. The "sectnum" directive should override the --no-section-numbering command line option then.

• Create a single dynamic or unqualified front end that can be installed?