Docutils To Do List

Author: David Goodger (with input from many); open to all Docutils developers
Contact: docutils-develop@lists.sourceforge.net
Date: 2015-04-20
Revision: 7883
Copyright: This document has been placed in the public domain.

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: Support the Docutils project!

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

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.

Many of these are now handled by Sphinx

General

object numbering and object references

For equations, tables & figures.

These would be the equivalent of DocBook's "formal" elements.

In LaTeX, automatic counters are implemented for sections, equations and floats (figures, tables) (configurable via stylesheets or in the latex-preamble). Objects can be given reference names with the \label{<refname} command, \ref{<refname>} inserts the corresponding number.

No such mechanism exists in HTML.

  • We need persistent sequences, similar to chapter and footnote numbers. See OpenOffice.org XML "fields".

    • Should the sequences be automatic or manual (user-specifyable)?
  • It is already possible to give reference names to objects via internal hyperlink targets or the "name" directive option:

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

    or

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

    Improve the mapping of "phrase references" to IDs/labels with Literal transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just stripping the accents and other non-ASCII chars. Use http://pypi.python.org/pypi/Unidecode?

    A "table" directive has been implemented, supporting table titles.

    Perhaps the name could derive from the title/caption?

  • We need syntax for object references. Cf. OpenOffice.org XML "reference fields":

    • Parameterized substitutions are too complicated (cf. or not to do: object references)

    • An interpreted text approach is simpler and better:

      See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
      
    • "equation", "figure", and "page" roles could generate appropriate boilerplate text:

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

      See Interpreted Text below.

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

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

      The position of the role (prefix or suffix) could also be utilized

See also the Modified rst2html by Nicolas Rougier for a sample implementation.

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?).
  • Improve index in docs/user/config.txt.

Developer Docs

  • Complete Docutils Runtime Settings.
  • 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:

Miscellaneous ideas:

reStructuredText Parser

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

Misc

  • Another list problem:

    * foo
          * bar
          * baz
    

    This ends up as a definition list. This is more of a usability issue.

  • This case is probably meant to be a nested list, but it ends up as a list inside a block-quote without an error message:

    - foo
    
     - bar
    

    It should probably just be an error.

    The problem with this is that you don't notice easily in HTML that it's not a nested list but a block-quote -- there's not much of a visual difference.

  • 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 improvements. See <http://thread.gmane.org/gmane.text.docutils.user/2499> (and the sub-thread at <http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>, and the follow-ups at <http://thread.gmane.org/gmane.text.docutils.user/3087>, <http://thread.gmane.org/gmane.text.docutils.user/3110>, <http://thread.gmane.org/gmane.text.docutils.user/3114>), <http://thread.gmane.org/gmane.text.docutils.user/2443>, <http://thread.gmane.org/gmane.text.docutils.user/2715>, <http://thread.gmane.org/gmane.text.docutils.user/3027>, <http://thread.gmane.org/gmane.text.docutils.user/3120>, <http://thread.gmane.org/gmane.text.docutils.user/3253>.

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

  • 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. (Don't convert the links.)

    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 Lea's objections), more-universal links?, Output-format-sensitive link targets?

    Idea from Jim Fulton: an external lookup table of targets:

    I would like to specify the extension (e.g. .txt) [in the source, rather than filename.*], but tell the converter to change references to the files anticipating that the files will be converted too.

    For example:

    .. _Another Document: another.txt
    
    rst2html.py --convert-links "another.txt bar.txt" foo.txt
    

    That is, name the files for which extensions should be converted.

    Note that I want to refer to original files in the original text (another.txt rather than another.txt) because I want the unconverted text to stand on its own.

    Note that in most cases, people will be able to use globs:

    rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
    

    It might be nice to be able to use multiple arguments, as in:

    rst2html.py --convert-link-extensions-for *.txt -- foo.txt
    
    > What is to be done for output formats
    > that don't have hyperlinks?
    

    Don't convert the links.

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

    No, documents only, but there really is no need for gueswork. Just get the file names as command-line arguments. EIBTI [explicit is better than implicit].

    For images, we probably need separate solution (which is being worked on), whereas for documents, the issue is basically interlinking between reStructuredText documents. IMO, this cries for support for multiple input and output files, i.e. support for documents which comprise multiple files. Adding adaptable file extensions seems like a kludge. // FW

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

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

  • How about a syntax for alternative hyperlink behavior, such as "open in a new window" (as in HTML's <a target="_blank">)?

    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.
    
  • Enable grid tables inside XML comments, where "--" ends comments.

    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.
    4. Allow Unicode box characters for table markup (feature request [6])

    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.

    Unicode box character markup would kill two birds with one stone.

    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"?

  • Line numbers and "source" in system messages:

    • Add "source" and "line" keyword arguments to all Reporter calls? This would require passing source/line arguments along all intermediate functions (where currently only line is used).

      Or rather specify "line" only if actually needed?

      Currently, document.reporter uses a state machine instance to determine the "source" and "line" info from statemachine.input_lines if not given explicitely. Except for special cases, the "line" argument is not needed because, document.statemachine keeps record of the current line number.

    • For system messages generated after the parsing is completed (i.e. by transforms or the writer) "line" info must be present in the doctree elements.

      Elements' .line assignments should be checked. (Assign to .source too? Add a set_info method? To what?)

      The "source" (and line number in the source) can either be added explicitely to the elements or determined from the “raw” line number by document.statemachine.get_source_and_line.

    • Some line numbers in elements are not being set properly (explicitly), just implicitly/automatically. See rev. 1.74 of docutils/parsers/rst/states.py for an example of how to set.

    • The line numbers of definition list items are wrong:

      $ rst2pseudoxml.py --expose-internal-attribute line
      1
        2
        3
      
      5
        6
        7
      
      <document source="<stdin>">
          <definition_list>
              <definition_list_item internal:line="3">
                  <term>
                      1
                  <definition>
                      <paragraph internal:line="2">
                          2
                          3
              <definition_list_item internal:line="6">
                  <term>
                      5
                  <definition>
                      <paragraph internal:line="6">
                          6
                          7
      
  • Quite a few nodes are getting a "None" source attribute as well. In particular, see the bodies of definition lists.

Math Markup

Since Docutils 0.8, a "math" role and directive using LaTeX math syntax as input format is part of reStructuredText.

Open issues:

  • Use a "Transform" for math format conversions as extensively discussed in the "math directive issues" thread in May 2008 (http://osdir.com/ml/text.docutils.devel/2008-05/threads.html)?
  • Generic "math-output" option (currently specific to HTML). (List of math-output preferences?)
  • Try to be compatible with Math support in Sphinx?
    • The :label: option selects a label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. In Docutils, the option :name: sets the label. Equation numbering is not implemented yet.
    • Option :nowrap: prevents wrapping of the given math in a math environment (you have to specify the math environment in the content).
  • Equation numbering and references. (Should be handled in a unified way with other numbered entities like formal tables and images.)

alternative input formats

Use a directive option to specify an alternative input format, e.g. (but not limited to):

MathML

Not for hand-written code but maybe usefull when pasted in (or included from a file)

For an overview of MathML implementations and tests, see, e.g., the mathweb wiki or the ConTeXT MathML page.

ASCIIMath

Simple, ASCII based math input language (see also ASCIIMath tutorial).

Unicode Nearly Plain Text Encoding of Mathematics

format for lightly marked-up representation of mathematical expressions in Unicode.

(Unicode Technical Note. Sole responsibility for its contents rests with the author(s). Publication does not imply any endorsement by the Unicode Consortium.)

itex
See the culmination of a relevant discussion in 2003.

LaTeX output

Which equation environments should be supported by the math directive?

  • one line:

    • numbered: equation
    • unnumbered: equation*
  • multiline (test for \\ outside of a nested environment (e.g. array or cases)

    • numbered: align (number every line)

      (To give one common number to all lines, put them in a split environment. Docutils then places it in an equation environment.)

    • unnumbered: align*

    • Sphinx math also supports gather (checking for blank lines in the content). Docutils puts content blocks separated by blank lines in separate math-block doctree nodes. (The only difference of gather to two consecutive "normal" environments seems to be that page-breaks between the two are prevented.)

See http://www.math.uiuc.edu/~hildebr/tex/displays.html.

HTML output

There is no native math support in HTML.

MathML

Converters from LaTeX to MathML include

  • latex_math (Python) by Jens Jørgen Mortensen in the Docutils sandbox

    This is the base for Docutils latex2mathml module used by default with --math-output=MathML.

  • blahtexml (C++), supported with --math-output=MathML blahtexml.

    Fast conversion, support for many symbols and environments, but no "align" (or other equation-aligning) environment.

  • LaTeXML (Perl), supported with --math-output=MathML latexml.

    Comprehensive macro support but very slow

  • TtM (C), --math-output=MathML ttm, support may be removed.

    No "matrix", "align" and "cases" environments.

  • MathToWeb (Java)

  • TeX4ht (TeX based)

  • itex (also used in Abiword)

  • Steve’s LATEX-to-MathML translator ('mini-language', javascript, Python)

  • Write a new converter? E.g. based on:

HTML/CSS

format math in standard HTML enhanced by CSS rules (Overview, Examples and experiments).

The math-output=html option uses the converter from eLyXer (included with Docutils).

Alternatives: LaTeX-math to HTML/CSS converters include

images
(PNG or SVG) like e.g. Wikipedia. (e.g. with dvisvgm or the pure-python MathML->SVG converter SVGMath)

OpenOffice output

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.

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

  • 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?

  • Implement options or features on existing directives:

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

    • Add the "class" option to the unicode directive. For example, you might want to get characters or strings with borders around them.

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

    • misc.include:

      • 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
        
      • Strip blank lines from begin and end of a literal included file or file section. This would correspond to the way a literal block is handled.

        As nodes.literal_block expects (and we have) the text as a string (rather than a list of lines), using a regexp seems the way.

    • 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?

      • The misc.settings directive suggested below offers a more generic approach.
      • The language of document parts can be indicated by the "special class value" "language-" + BCP 47 language code. Class arguments to the title are attached to the document's base node - hence titled documents can be given a different language at parse time. However, "language by class attribute" does not change parsing (localized directives etc.), only supporting writers.
    • misc.settings: Set any(?) Docutils runtime setting from within a document? Needs much thought and discussion.

      Security concerns need to be taken into account (it shouldn't be possible to enable file_insertion_enabled from within a document), and settings that only would have taken effect before the directive (like tab-width) shouldn't be accessible either.

      See this sub-thread: <http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649>

    • misc.gather: Gather (move, or copy) all instances of a specific element. A generalization of the Footnote & Citation Gathering 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?
    • Make the meaning of block quotes overridable? Only a 1-shot though; doesn't solve the general problem.

    • conditional directives:

      Note

      See also the implementation in Sphinx.

      Docutils already has the ability to say "use this content for Writer X" via the "raw" directive. It also does have the ability to say "use this content for any Writer other than X" via the "strip-elements with class" config value. However, using "raw" input just to select a special writer is inconvenient in many cases. It wouldn't be difficult to get more straightforward support, 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.

    • 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"? (since 0.9 available with "code" directive)

      • "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.

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

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

      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.

Doctree pruning

The number of doctree nodes can be reduced by "normalizing" some related nodes. This makes the document model and the writers somewhat simpler.

  • The "doctest" element should go away. The construct could simply be a front-end to generic literal blocks. We could immediately (in 0.7) 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?).

  • "Normalize" special admonitions (note, hint, warning, ...) during parsing (similar to transforms.writer_aux.Admonitions). There is no need to keep them as distinct elements in the doctree specification.

    Keep the special admonition directives in reStructuredText syntax?

Unimplemented Transforms

HTML Writer

PEP/HTML Writer

S5/HTML Writer

Epub/HTML Writer

Add epub as an output format.

epub is an open file format for ebooks based on HTML, specified by the International Digital Publishing Forum. Thus, documents in epub format are suited to be read with electronic reading devices.

Pack the output of a HTML writer and supporting files (e.g. images) into one single epub document.

There are links to two 3rd party ePub writers in the Docutils link list. Test and consider moving the better one into the docutils core.

LaTeX writer

Also see the Problems section in the latex writer documentation.

Bug fixes

  • A multirow cell in a table expects empty cells in the spanned rows while the doctree contains only the remaining cells ("Exchange Table Model", see docs/ref/soextblx.dtd).

    Needs bookkeeping of "open" multirow cells (how many how long) and insertion of additional '&'s.

    See ../../test/functional/input/data/latex.txt

  • Too deeply nested lists fail: generate a warning and provide a workaround.

  • Spaces in inline literal text:

    Now note    the
    spacing    between the    words of    this sentence    (words
    should    be grouped    in pairs).
    

    Discuss the desired behaviour and implement a consistent one.

  • An enumerated list in the docinfo fails (newcounter definition inside tabularx).

  • File names of included graphics (see also grffile package).

Generate clean and configurable LaTeX source

  • Check the generated source with package nag.

Configurable placement of figure and table floats

  • Special class argument to individually place figures?

    Either:

    placement-<optional arg> -> figure[<optional arg>]{...}

    e.g. .. class::  placement-htb,

    or more verbose:

    H:place-here
    h:place-here-if-possible
    t:place-top
    b:place-bottom
    p:place-on-extra-page

    e.g.: .. class:: place-here-if-possible place-top place-bottom

    Maybe support both variants?

LaTeX constructs and packages instead of re-implementations

Which packages do we want to use?

  • base and "recommended" packages

    (packages that should be in a "reasonably sized and reasonably modern LaTeX installation like the texlive-latex-recommended Debian package, say):

  • No "fancy" or "exotic" requirements.

  • pointers to advanced packages and their use in the latex writer documentation.

  • alltt environment for literal block.

  • footnotes

    • True footnotes with LaTeX auto-numbering (as option --latex-footnotes) (also for target-footnotes):
      • attach footnote text to footnote-symobol node
      • write footnote{<footnote text>}
      • consider cases where LaTeX does not support footnotes (inside tables, headings, ...)?
      • consider multiple footnote refs to common footnote text.
    • document customization (links to how-to and packages):
  • use eqlist or enumitem (texlive-latex-extra) for field-lists?

  • --use-latex-when-possible »super option« that would set the following:

       --no-section-numbering
       --use-latex-toc
       --use-latex-docinfo
       --use-latex-abstract
       --use-latex-footnotes
       --use-latex-citations
    
    ? (My preference is to default to use-latex-* whenever possible [GM])
    

Default layout

  • Use italic instead of slanted for titlereference?

  • Start a new paragraph after lists (as currently) or continue (no blank line in source, no parindent in output)?

    Overriding:

    • continue if the compound paragraph directive is used, or
    • force a new paragraph with an empty comment.
  • Sidebar handling (environment with framed, marginnote, wrapfig, ...)?

  • Use optionlist for docinfo?

  • Keep literal-blocks together on a page, avoid pagebreaks.

    Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before the block.

    Should be possible with --literal-block-env==lstlistings and some configuration...

  • More space between title and subtitle?

    -  \\ % subtitle%
    +  \\[0.5em] % subtitle%
    

Tables

  • Improve/simplify logic to set the column width in the output.

    • Assumed reST line length for table width setting configurable, or
    • use ltxtable (a combination of tabularx (auto-width) and longtable (page breaks)), or
    • use tabularx column type X and let LaTeX decide width, or
    • use tabulary?
  • From comp.text.tex (13. 4. 2011):

    When using fixed width columns, you should ensure that the total width does not exceed linewidth: if the first column is p{6cm} the second one should be p{dimexprlinewidth-6cm-4tabcolsep} because the glue tabcolsep is added twice at every column edge. You may also consider to set tabcolsep to a different value...

  • csv-tables do not have a colwidth.

  • Add more classes or options, e.g. for

    • column width set by latex,
    • horizontal alignment and rules.
    • long table vs. tabular (see next item).
  • Use tabular instead of longtable for tables in legends or generally inside a float?

    Alternatively, default to tabular and use longtable only if specified by config setting or class argument (analogue to booktable)?

  • Table heads and footer for longtable (firstpage lastpage ..)?

  • In tools.txt the option tables right column, there should be some more spacing between the description and the next paragraph "Default:".

  • Paragraph separation in tables is hairy. see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab

    • The strut solution did not work.
    • setting extrarowheight added ad top of row not between paragraphs in a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
    • baselineskip/stretch does not help.
  • Should there be two hlines after table head and on table end?

  • Place titled tables in a float ('table' environment)?

    The 'table', 'csv-table', and 'list-table' directives support an (optional) table title. In analogy to the 'figure' directive this should map to a table float.

Image and figure directives

Missing features

  • support "figwidth" argument for figures.

    As the 'figwidth' argument is still ignored and the "natural width" of a figure in LaTeX is 100 % of the text width, setting the 'align' argument has currently no effect on the LaTeX output.

  • Let meta directive insert PDF-keywords into header?

  • Multiple author entries in docinfo (same thing as in html). (already solved?)

  • Consider supporting the "compact" option and class argument (from rst2html) as some lists look better compact and others need the space.

  • Better citation support (see Footnote & Citation Gathering).

  • If use-latex-citations is used, a bibliography is inserted right at the end of the document.

    Put in place of the to-be-implemented "citations" directive (see Footnote & Citation Gathering).

Unicode to LaTeX

The LyX document processor has a comprehensive Unicode to LaTeX conversion feature with a file called unicodesymbols that lists LaTeX counterparts for a wide range of Unicode characters.

  • Use this in the LaTeXTranslator? Think of copyright issues!
  • The "ucs" package has many translations in ...doc/latex/ucs/config/
  • The bibstuff tool ships a latex_codec Python module!

Allow choice between utf8 (standard) and utf8x (extended) encodings

  • Allow the user to select utf8 or utf8x LaTeX encoding. (Docutil's output encoding becomes LaTeX's input encoding.)

The ucs package provides extended support for UTF-8 encoding in LaTeX via the inputenc-option utf8x. It is, however, a non-standard extension and no longer developed.

Ideas:
  1. Python has 4 names for the UTF-8 encoding (utf_8, U8, UTF, utf8) give a special meaning to one of the aliases,
  2. scan "stylesheets" and "latex-preamble" options and use utf8x if it contains ucs

XeTeX writer

  • Glyphs missing in the font are left out in the PDF without warning (e.g. ⇔ left-right double arrow in the functional test output).
  • Disable word-wrap (hyphenation) in literal text locally with providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}?

problematic URLs

  • ^^ LaTeX's special syntax for characters results in "strange" replacements (both with href and url).

    file with ^^: ../strange^^name

  • Unbalanced braces, { or }, will fail (both with href and url):

    `file with { <../strange{name>`__
    `<../strange{name>`__
    

Currently, a warning is written to the error output stream.

For correct printing, we can

  • use the href command with "normal" escaped name argument, or

  • define a url-command in the preamble

    \urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
    

but need to find a way to insert it as href argument.

The following fails:

\href{http://www.w3.org/XML/Schema^^dev}{\fragileURLi}

Use %-replacement like http://nowhere/url_with%28parens%29 ?

-> does not work for file paths (with pdflatex and xpdf).

add-stylesheet option

From http://article.gmane.org/gmane.text.docutils.devel/3429/

The problem is that since we have a default value, we have to differentiate between adding another stylesheet and replacing the default. I suggest that the existing --stylesheet & --stylesheet-path options keep their semantics to replace the existing settings. We could introduce new --add-stylesheet & --add-stylesheet-path options, which accumulate; further --stylesheet/--stylesheet-path options would clear these lists. The stylesheet or stylesheet_path setting (only one may be set), plus the added_stylesheets and added_stylesheet_paths settings, describe the combined styles.

For example, this run will have only one custom stylesheet:

rstpep2html.py --stylesheet-path custom.css ...

This run will use the default stylesheet, and the custom one:

rstpep2html.py --add-stylesheet-path custom.css ...

This run will use the default stylesheet, a custom local stylesheet, and an external stylesheet:

rstpep2html.py --add-stylesheet-path custom.css
--add-stylesheet http://www.example.org/external.css ...

This run will use only the second custom stylesheet:

rstpep2html.py --add-stylesheet-path custom.css
--stylesheet-path second.css ...

Front-End Tools