path: root/docs/dev/todo.txt

======================
 Docutils_ To Do List
======================

:Author: David Goodger (with input from many); open to all Docutils
         developers
:Contact: goodger@python.org
:Date: $Date$
:Revision: $Revision$
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/

.. contents::


Priority items are marked with "@" symbols.  The more @s, the higher
the priority.  Items in question form (containing "?") are ideas which
require more thought and debate; they are potential to-do's.

Many of these items are awaiting champions.  If you see something
you'd like to tackle, please do!  If there's something you'd like to
see done but are unable to implement it yourself, please consider
donating to Docutils: |donate|

.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
   :target: http://sourceforge.net/donate/index.php?group_id=38414
   :align: middle
   :width: 88
   :height: 32
   :alt: Support the Docutils project!

Please see also the Bugs_ document for a list of bugs in Docutils.

.. _bugs: ../../BUGS.html


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
  <http://docutils.sf.net/sandbox/README.html#documenting-python>`_.


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: :

  .. _OpenOffice.org XML: http://xml.openoffice.org/

* 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.

  __ ../ref/rst/directives.html#including-an-external-document-fragment

  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.

  .. _2004-02-18 "rest checking and source path":
     http://thread.gmane.org/gmane.text.docutils.user/1112

* 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.

* .. _classes for table cells:

  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.)

  .. _traits: http://code.enthought.com/traits/
  .. _SciPy: http://www.scipy.org/

* 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
      <../user/slide-shows.html>`_


Documentation
=============

User Docs
---------

* Add a FAQ entry about using Docutils (with reStructuredText) on a
  server and that it's terribly slow.  See the first paragraphs in
  <http://article.gmane.org/gmane.text.docutils.user/1584>.

* Add document about what Docutils has previously been used for
  (web/use-cases.txt?).


Developer Docs
--------------

* Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.

* Improve the internal module documentation (docstrings in the code).
  Specific deficiencies listed below.

  - docutils.parsers.rst.states.State.build_table: data structure
    required (including StringList).

  - docutils.parsers.rst.states: more complete documentation of parser
    internals.

* docs/ref/doctree.txt: DTD element structural relationships,
  semantics, and attributes.  In progress; element descriptions to be
  completed.

* Document the ``pending`` elements, how they're generated and what
  they do.

* Document the transforms (perhaps in docstrings?): how they're used,
  what they do, dependencies & order considerations.

* Document the HTML classes used by html4css1.py.

* Write an overview of the Docutils architecture, as an introduction
  for developers.  What connects to what, why, and how.  Either update
  PEP 258 (see PEPs_ below) or as a separate doc.

* Give information about unit tests.  Maybe as a howto?

* Document the docutils.nodes APIs.

* Complete the docs/api/publisher.txt docs.


How-Tos
-------

* Creating Docutils Writers

* Creating Docutils Readers

* Creating Docutils Transforms

* Creating Docutils Parsers

* Using Docutils as a Library


PEPs
----

* Complete PEP 258 Docutils Design Specification.

  - Fill in the blanks in API details.

  - Specify the nodes.py internal data structure implementation?

        [Tibs:] Eventually we need to have direct documentation in
        there on how it all hangs together - the DTD is not enough
        (indeed, is it still meant to be correct?  [Yes, it is.
        --DG]).

* Rework PEP 257, separating style from spec from tools, wrt Docutils?
  See Doc-SIG from 2001-06-19/20.


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.

  .. _additional docstrings:
     ../peps/pep-0258.html#additional-docstrings

* 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.

__ rst/alternatives.html#or-not-to-do

* 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.

* .. _adaptable file extensions:

  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?`__

  __ http://thread.gmane.org/gmane.text.docutils.user/1239
  __ http://article.gmane.org/gmane.text.docutils.user/1278
  __ http://thread.gmane.org/gmane.text.docutils.user/1915
  __ http://thread.gmane.org/gmane.text.docutils.user/2438

* 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?)

  .. XXX What does this mean?  Can you elaborate, David?

* 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`_.

  .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt

* 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
  <rst/alternatives.html#nested-inline-markup>`__.

* 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
  <http://article.gmane.org/gmane.text.docutils.user/118>`__.

  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)`.

  .. _MathML: http://www.w3.org/TR/MathML2/
  .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html

* 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.

  .. _list-table: ../ref/rst/directives.html#list-table

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


Directives
----------

Directives below are often referred to as "module.directive", the
directive function.  The "module." is not part of the directive name
when used in a document.

* Make the _`directive interface` object-oriented
  (http://article.gmane.org/gmane.text.docutils.user/1871).

* Allow for field lists in list tables.  See
  <http://thread.gmane.org/gmane.text.docutils.devel/3392>.

* .. _unify tables:

  Unify table implementations and unify options of table directives
  (http://article.gmane.org/gmane.text.docutils.user/1857).

* Allow directives to be added at run-time?

* Use the language module for directive option names?

* Add "substitution_only" and "substitution_ok" function attributes,
  and automate context checking?

* Change directive functions to directive classes?  Superclass'
  ``__init__()`` could handle all the bookkeeping.

* Implement options or features on existing directives:

  - Add a "name" option to directives, to set an author-supplied
    identifier?

  - All directives that produce titled elements should grow implicit
    reference names based on the titles.

  - Allow the _`:trim:` option for all directives when they occur in a
    substitution definition, not only the unicode_ directive.

    .. _unicode: ../ref/rst/directives.html#unicode-character-codes

  - _`images.figure`: "title" and "number", to indicate a formal
    figure?

  - _`parts.sectnum`: "local"?, "refnum"

    A "local" option could enable numbering for sections from a
    certain point down, and sections in the rest of the document are
    not numbered.  For example, a reference section of a manual might
    be numbered, but not the rest.  OTOH, an all-or-nothing approach
    would probably be enough.

    The "sectnum" directive should be usable multiple times in a
    single document.  For example, in a long document with "chapter"
    and "appendix" sections, there could be a second "sectnum" before
    the first appendix, changing the sequence used (from 1,2,3... to
    A,B,C...).  This is where the "local" concept comes in.  This part
    of the implementation can be left for later.

    A "refnum" option (better name?) would insert reference names
    (targets) consisting of the reference number.  Then a URL could be
    of the form ``http://host/document.html#2.5`` (or "2-5"?).  Allow
    internal references by number?  Allow name-based *and*
    number-based ids at the same time, or only one or the other (which
    would the table of contents use)?  Usage issue: altering the
    section structure of a document could render hyperlinks invalid.

  - _`parts.contents`: Add a "suppress" or "prune" option?  It would
    suppress contents display for sections in a branch from that point
    down.  Or a new directive, like "prune-contents"?

    Add an option to include topics in the TOC?  Another for sidebars?
    The "topic" directive could have a "contents" option, or the
    "contents" directive" could have an "include-topics" option.  See
    docutils-develop 2003-01-29.

  - _`parts.header` & _`parts.footer`: Support multiple, named headers
    & footers?  For example, separate headers & footers for odd, even,
    and the first page of a document.

    This may be too specific to output formats which have a notion of
    "pages".

  - _`misc.class`:

    - Add a ``:parent:`` option for setting the parent's class
      (http://article.gmane.org/gmane.text.docutils.devel/3165).

  - _`misc.include`:

    - Option to select a range of lines?

    - Option to label lines?

    - How about an environment variable, say RSTINCLUDEPATH or
      RSTPATH, for standard includes (as in ``.. include:: <name>``)?
      This could be combined with a setting/option to allow
      user-defined include directories.

    - Add support for inclusion by URL? ::

          .. include::
             :url: http://www.example.org/inclusion.txt

  - _`misc.raw`: add a "destination" option to the "raw" directive? ::

        .. raw:: html
           :destination: head

           <link ...>

    It needs thought & discussion though, to come up with a consistent
    set of destination labels and consistent behavior.

    And placing HTML code inside the <head> element of an HTML
    document is rather the job of a templating system.

  - _`body.sidebar`: Allow internal section structure?  Adornment
    styles would be independent of the main document.

    That is really complicated, however, and the document model
    greatly benefits from its simplicity.

* Implement directives.  Each of the list items below begins with an
  identifier of the form, "module_name.directive_function_name".  The
  directive name itself could be the same as the
  directive_function_name, or it could differ.

  - _`html.imagemap`

    It has the disadvantage that it's only easily implementable for
    HTML, so it's specific to one output format.

    (For non-HTML writers, the imagemap would have to be replaced with
    the image only.)

  - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.

  - _`parts.citations`: See `Footnote & Citation Gathering`_.

  - _`misc.language`: Specify (= change) the language of a document at
    parse time.

  - _`misc.settings`: Set any(?) Docutils runtime setting from within
    a document?  Needs much thought and discussion.

  - _`misc.gather`: Gather (move, or copy) all instances of a specific
    element.  A generalization of the "endnotes" & "citations" ideas.

  - Add a custom "directive" directive, equivalent to "role"?  For
    example::

        .. directive:: incr

           .. class:: incremental

        .. incr::

        "``.. incr::``" above is equivalent to "``.. class:: incremental``".

    Another example::

        .. directive:: printed-links

           .. topic:: Links
              :class: print-block

              .. target-notes::
                 :class: print-inline

    This acts like macros.  The directive contents will have to be
    evaluated when referenced, not when defined.  

    * Needs a better name?  "Macro", "substitution"?
    * What to do with directive arguments & options when the
      macro/directive is referenced?

  - .. _conditional directives:

    Docutils already has the ability to say "use this content for
    Writer X" (via the "raw" directive), but it doesn't have the
    ability to say "use this content for any Writer other than X".  It
    wouldn't be difficult to add this ability though.

    My first idea would be to add a set of conditional directives.
    Let's call them "writer-is" and "writer-is-not" for discussion
    purposes (don't worry about implemention details).  We might
    have::

         .. writer-is:: text-only

            ::

                +----------+
                |   SNMP   |
                +----------+
                |   UDP    |
                +----------+
                |    IP    |
                +----------+
                | Ethernet |
                +----------+

         .. writer-is:: pdf

            .. figure:: protocol_stack.eps

         .. writer-is-not:: text-only pdf

            .. figure:: protocol_stack.png

    This could be an interface to the Filter transform
    (docutils.transforms.components.Filter).

    The ideas in `adaptable file extensions`_ above may also be
    applicable here.

    SVG's "switch" statement may provide inspiration.

    Here's an example of a directive that could produce multiple
    outputs (*both* raw troff pass-through *and* a GIF, for example)
    and allow the Writer to select. ::

        .. eqn::

           .EQ
           delim %%
           .EN
           %sum from i=o to inf c sup i~=~lim from {m -> inf}
           sum from i=0 to m sup i%
           .EQ
           delim off
           .EN

  - _`body.example`: Examples; suggested by Simon Hefti.  Semantics as
    per Docbook's "example"; admonition-style, numbered, reference,
    with a caption/title.

  - _`body.index`: Index targets.

    See `Index Entries & Indexes
    <./rst/alternatives.html#index-entries-indexes>`__.

  - _`body.literal`: Literal block, possibly "formal" (see `object
    numbering and object references`_ above).  Possible options:

    - "highlight" a range of lines

    - include only a specified range of lines

    - "number" or "line-numbers"

    - "styled" could indicate that the directive should check for
      style comments at the end of lines to indicate styling or
      markup.

      Specific derivatives (i.e., a "python-interactive" directive)
      could interpret style based on cues, like the ">>> " prompt and
      "input()"/"raw_input()" calls.

    See docutils-users 2003-03-03.

  - _`body.listing`: Code listing with title (to be numbered
    eventually), equivalent of "figure" and "table" directives.

  - _`colorize.python`: Colorize Python code.  Fine for HTML output,
    but what about other formats?  Revert to a literal block?  Do we
    need some kind of "alternate" mechanism?  Perhaps use a "pending"
    transform, which could switch its output based on the "format" in
    use.  Use a factory function "transformFF()" which returns either
    "HTMLTransform()" instance or "GenericTransform" instance?

    If we take a Python-to-HTML pretty-printer and make it output a
    Docutils internal doctree (as per nodes.py) instead of HTML, then
    each output format's stylesheet (or equivalent) mechanism could
    take care of the rest.  The pretty-printer code could turn this
    doctree fragment::

         <literal_block xml:space="preserve">
         print 'This is Python code.'
         for i in range(10):
             print i
         </literal_block>

    into something like this ("</>" is end-tag shorthand)::

         <literal_block xml:space="preserve" class="python">
         <keyword>print</> <string>'This is Python code.'</>
         <keyword>for</> <identifier>i</> <keyword
         >in</> <expression>range(10)</>:
             <keyword>print</> <expression>i</>
         </literal_block>

    But I'm leaning toward adding a single new general-purpose
    element, "phrase", equivalent to HTML's <span>.  Here's the
    example rewritten using the generic "phrase"::

        <literal_block xml:space="preserve" class="python">
        <phrase class="keyword">print</> <phrase
         class="string">'This is Python code.'</>
        <phrase class="keyword">for</> <phrase
         class="identifier">i</> <phrase class="keyword">in</> <phrase
         class="expression">range(10)</>:
            <phrase class="keyword">print</> <phrase
             class="expression">i</>
        </literal_block>

    It's more verbose but more easily extensible and more appropriate
    for the case at hand.  It allows us to edit style sheets to add
    support for new formats, not the Docutils code itself.

    Perhaps a single directive with a format parameter would be
    better::

        .. colorize:: python

           print 'This is Python code.'
           for i in range(10):
               print i

    But directives can have synonyms for convenience.  "format::
    python" was suggested, but "format" seems too generic.

  - _`pysource.usage`: Extract a usage message from the program,
    either by running it at the command line with a ``--help`` option
    or through an exposed API.  [Suggestion for Optik.]


Interpreted Text
----------------

Interpreted text is entirely a reStructuredText markup construct, a
way to get around built-in limitations of the medium.  Some roles are
intended to introduce new doctree elements, such as "title-reference".
Others are merely convenience features, like "RFC".

All supported interpreted text roles must already be known to the
Parser when they are encountered in a document.  Whether pre-defined
in core/client code, or in the document, doesn't matter; the roles
just need to have already been declared.  Adding a new role may
involve adding a new element to the DTD and may require extensive
support, therefore such additions should be well thought-out.  There
should be a limited number of roles.

The only place where no limit is placed on variation is at the start,
at the Reader/Parser interface.  Transforms are inserted by the Reader
into the Transformer's queue, where non-standard elements are
converted.  Once past the Transformer, no variation from the standard
Docutils doctree is possible.

An example is the Python Source Reader, which will use interpreted
text extensively.  The default role will be "Python identifier", which
will be further interpreted by namespace context into <class>,
<method>, <module>, <attribute>, etc. elements (see pysource.dtd),
which will be transformed into standard hyperlink references, which
will be processed by the various Writers.  No Writer will need to have
any knowledge of the Python-Reader origin of these elements.

* Add explicit interpreted text roles for the rest of the implicit
  inline markup constructs: named-reference, anonymous-reference,
  footnote-reference, citation-reference, substitution-reference,
  target, uri-reference (& synonyms).

* Add directives for each role as well?  This would allow indirect
  nested markup::

      This text contains |nested inline markup|.

      .. |nested inline markup| emphasis::

         nested ``inline`` markup

* Implement roles:

  - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
    around role contents.

    For example, the following reStructuredText source ... ::

        .. role:: red(raw-formatting)
           :prefix:
               :html: <font color="red">
               :latex: {\color{red}
           :suffix:
               :html: </font>
               :latex: }

        colored :red:`text`

    ... will yield the following document fragment::

        <paragraph>
            colored
            <inline classes="red">
                <raw format="html">
                    <font color="red">
                <raw format="latex">
                    {\color{red}
                <inline classes="red">
                    text
                <raw format="html">
                    </font>
                <raw format="latex">
                    }

    Possibly without the intermediate "inline" node.

  - "acronym" and "abbreviation": Associate the full text with a short
    form.  Jason Diamond's description:

        I want to translate ```reST`:acronym:`` into ``<acronym
        title='reStructuredText'>reST</acronym>``.  The value of the
        title attribute has to be defined out-of-band since you can't
        parameterize interpreted text.  Right now I have them in a
        separate file but I'm experimenting with creating a directive
        that will use some form of reST syntax to let you define them.

    Should Docutils complain about undefined acronyms or
    abbreviations?

    What to do if there are multiple definitions?  How to
    differentiate between CSS (Content Scrambling System) and CSS
    (Cascading Style Sheets) in a single document?  David Priest
    responds,

        The short answer is: you don't.  Anyone who did such a thing
        would be writing very poor documentation indeed.  (Though I
        note that `somewhere else in the docs`__, there's mention of
        allowing replacement text to be associated with the
        abbreviation.  That takes care of the duplicate
        acronyms/abbreviations problem, though a writer would be
        foolish to ever need it.)

        __ `inline parameter syntax`_

    How to define the full text?  Possibilities:

    1. With a directive and a definition list? ::

           .. acronyms::

              reST
                  reStructuredText
              DPS
                  Docstring Processing System

       Would this list remain in the document as a glossary, or would
       it simply build an internal lookup table?  A "glossary"
       directive could be used to make the intention clear.
       Acronyms/abbreviations and glossaries could work together.

       Then again, a glossary could be formed by gathering individual
       definitions from around the document.

    2. Some kind of `inline parameter syntax`_? ::

           `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
           see is what you get>`:acronym: plaintext markup.

       .. _inline parameter syntax:
          rst/alternatives.html#parameterized-interpreted-text

    3. A combination of 1 & 2?

       The multiple definitions issue could be handled by establishing
       rules of priority.  For example, directive-based lookup tables
       have highest priority, followed by the first inline definition.
       Multiple definitions in directive-based lookup tables would
       trigger warnings, similar to the rules of `implicit hyperlink
       targets`__.

       __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets

    4. Using substitutions? ::

           .. |reST| acronym:: reST
              :text: reStructuredText

    What do we do for other formats than HTML which do not support
    tool tips?  Put the full text in parentheses?

  - "figure", "table", "listing", "chapter", "page", etc: See `object
    numbering and object references`_ above.

  - "glossary-term": This would establish a link to a glossary.  It
    would require an associated "glossary-entry" directive, whose
    contents could be a definition list::

        .. glossary-entry::

           term1
               definition1
           term2
               definition2

    This would allow entries to be defined anywhere in the document,
    and collected (via a "glossary" directive perhaps) at one point.


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.

  .. _raw.destination: misc.raw_

* 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 |S5|_.  I discovered |S5| a few weeks before it
  appeared on Slashdot, after writing most of this section.  It turns
  out that |S5| does most of what I wanted.

  Chris Liechti has `integrated S5 with the HTML writer
  <http://homepage.hispeed.ch/py430/python/index.html#rst2s5>`__.

  .. |S5| replace:: S\ :sup:`5`
  .. _S5: http://www.meyerweb.com/eric/tools/s5/

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

.. _S5 testbed: http://meyerweb.com/eric/tools/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:

  a) _`Fully qualified`: Reader and Writer are hard-coded into the
     front end (e.g. ``pep2html [options]``, ``pysource2pdf
     [options]``).

  b) _`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]``).

  c) _`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.

  d) _`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?


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End: