5 :Author: David Goodger (with input from many); open to all Docutils
7 :Contact: docutils-develop@lists.sourceforge.net
10 :Copyright: This document has been placed in the public domain.
12 .. _Docutils: http://docutils.sourceforge.net/
17 Priority items are marked with "@" symbols. The more @s, the higher
18 the priority. Items in question form (containing "?") are ideas which
19 require more thought and debate; they are potential to-do's.
21 Many of these items are awaiting champions. If you see something
22 you'd like to tackle, please do! If there's something you'd like to
23 see done but are unable to implement it yourself, please consider
24 donating to Docutils: |donate|
26 .. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
27 :target: http://sourceforge.net/donate/index.php?group_id=38414
31 :alt: Support the Docutils project!
33 Please see also the Bugs_ document for a list of bugs in Docutils.
35 .. _bugs: ../../BUGS.html
38 Minimum Requirements for Python Standard Library Candidacy
39 ==========================================================
41 Below are action items that must be added and issues that must be
42 addressed before Docutils can be considered suitable to be proposed
43 for inclusion in the Python standard library.
45 Many of these are now handled by Sphinx_
47 * Support for `document splitting`_. May require some major code
50 * Support for subdocuments (see `large documents`_).
52 * `Object numbering and object references`_.
54 * `Nested inline markup`_.
56 * `Python Source Reader`_.
58 * The HTML writer needs to be rewritten (or a second HTML writer
59 added) to allow for custom classes, and for arbitrary splitting
62 * Documentation_ of the architecture. Other docs too.
66 * Suitability for `Python module documentation
67 <http://docutils.sf.net/sandbox/README.html#documenting-python>`_.
69 .. _Sphinx: http://sphinx.pocoo.org/
74 * Move to single source for Python 2 and Python 3.
75 (Cf. `Porting Python 2 Code to Python 3`_ and
76 `clean single-source support for Python 2/3`_.)
78 - Gradually phase out support for Python 2.4 and 2.5 first.
80 .. _Porting Python 2 Code to Python 3:
81 https://docs.python.org/3/howto/pyporting.html
82 .. _clean single-source support for Python 2/3:
83 http://python-future.org
85 * Encoding of command line arguments can only be guessed:
87 * try UTF-8/strict first, then try the locale's encoding with
88 strict error handling, then ASCII/replace?
90 UTF-8 is almost 100% safe to try first; false positives are rare,
91 The locale's encoding with strict error handling may be a
92 reasonable compromise, but any error would indicate that the
93 locale's encoding is inappropriate. The only safe fallback is
96 * Do not decode argv before option parsing but individual string
99 +1 Allows for separate command-line vs. filesystem encodings,
100 respectively to keep file names encoded.
101 +1 Allows to configure command-line encoding in a config file,
104 Cf. <http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957>.
106 * Improve handling on Windows:
108 - Get graphical installer.
109 - Make rst2html.py an .exe file using py2exe.
113 The user interface is very difficult to use for most Windows users;
114 you can't really expect them to use the command line. We need some
115 kind of GUI that can launch rst2html.py, and save the HTML output to
116 a file, and launch a browser. What's important is that we get
117 settings to work with the GUI. So we need some way to dynamically
118 generate a list of settings for the GUI. The current settings_spec
119 for OptionParser doesn't seem to be usable for this for the
122 - It's biased toward the command line -- there are *two* options for
125 - You cannot have both a one-line description and a longer
126 description for tooltips/help-texts.
128 - It doesn't provide hints for the input type. You cannot easily
129 infer the type of a setting from its validator, because any
130 component can add new validators. In fact, it may be necessary to
131 have both a hint about the input type (e.g. string) and a
132 validator (valid ID), or it may be necessary to have a different
133 set of choices for the CLI (1, INFO, 2, ...) and for the GUI
134 (INFO, WARNING, ...).
136 - It's coupled to the OptionParser. We want to be able to change
137 the underlying system without breaking everything.
139 - It's a bunch of primitive structures. We want an extensible (thus
140 object-oriented) interface.
142 So we probably need to create a class for storing all the settings,
143 and auto-generate the OptionParser data from that.
145 I talked to Stephan Deibel about getting Docutils integrated into
146 Wing IDE. He said it's possible, and he'd be willing to help.
147 There's a scripting interface to Wing, which we'd use. We can
148 dynamically generate a list of preferences and not worry too much
149 about the rendering (from what I understood); Wing's whole GUI is
150 dynamic anyway. The interface could be made usable for other GUIs.
151 For example, we could try to get option support for DocFactory. //
154 * Allow different report levels for STDERR and system_messages inside
157 * Change the docutils-update script (in sandbox/infrastructure), to
158 support arbitrary branch snapshots.
160 * Move some general-interest sandboxes out of individuals'
161 directories, into subprojects?
163 * Add option for file (and URL) access restriction to make Docutils
164 usable in Wikis and similar applications.
166 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
167 settings. These partially solve the problem, allowing or disabling
168 **all** file accesses, but not limited access.
170 * Configuration file handling needs discussion:
172 - There should be some error checking on the contents of config
173 files. How much checking should be done? How loudly should
174 Docutils complain if it encounters an error/problem?
176 - Docutils doesn't complain when it doesn't find a configuration
177 file supplied with the ``--config`` option. Should it? (If yes,
180 * Internationalization:
182 - I18n needs refactoring, the language dictionaries are difficult to
183 maintain. Maybe have a look at gettext or similar tools.
185 (This would make a nice Google Summer of Code project)
187 - Language modules: in accented languages it may be useful to have
188 both accented and unaccented entries in the
189 ``bibliographic_fields`` mapping for versatility.
191 - Add a "--strict-language" option & setting: no English fallback
192 for language-dependent features.
194 Make this the default for output (as opposed to input)?
195 Throw an error with a helpfull message, e.g.
197 Default "contents" title for language %s missing, please specify
202 "attention" title for language %s missing, please use a generic
203 admonition with explicit title.
205 - Add internationalization to _`footer boilerplate text` (resulting
206 from "--generator", "--source-link", and "--date" etc.), allowing
210 * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
212 * In ``docutils.readers.get_reader_class`` (& ``parsers`` &
213 ``writers`` too), should we be importing "standalone" or
214 "docutils.readers.standalone"? (This would avoid importing
215 top-level modules if the module name is not in docutils/readers.
216 Potential nastiness.)
218 * Perhaps store a _`name-to-id mapping file`? This could be stored
219 permanently, read by subsequent processing runs, and updated with
220 new entries. ("Persistent ID mapping"?)
222 * Perhaps the ``Component.supports`` method should deal with
223 individual features ("meta" etc.) instead of formats ("html" etc.)?
225 * Think about _`large documents` made up of multiple subdocument
226 files. Issues: continuity (`persistent sequences`_ above),
227 cross-references (`name-to-id mapping file`_ above and `targets in
228 other documents`_ below), splitting (`document splitting`_ below).
230 When writing a book, the author probably wants to split it up into
231 files, perhaps one per chapter (but perhaps even more detailed).
232 However, we'd like to be able to have references from one chapter to
233 another, and have continuous numbering (pages and chapters, as
234 applicable). Of course, none of this is implemented yet. There has
235 been some thought put into some aspects; see `the "include"
236 directive`__ and the `Reference Merging`_ transform below.
238 When I was working with SGML in Japan, we had a system where there
239 was a top-level coordinating file, book.sgml, which contained the
240 top-level structure of a book: the <book> element, containing the
241 book <title> and empty component elements (<preface>, <chapter>,
242 <appendix>, etc.), each with filename attributes pointing to the
243 actual source for the component. Something like this::
246 <title>Title of the Book</title>
247 <preface inrefid="pr01"></preface>
248 <chapter inrefid="ch01"></chapter>
249 <chapter inrefid="ch02"></chapter>
250 <chapter inrefid="ch03"></chapter>
251 <appendix inrefid="ap01"></appendix>
254 (The "inrefid" attribute stood for "insertion reference ID".)
256 The processing system would process each component separately, but
257 it would recognize and use the book file to coordinate chapter and
258 page numbering, and keep a persistent ID to (title, page number)
259 mapping database for cross-references. Docutils could use a similar
260 system for large-scale, multipart documents.
262 __ ../ref/rst/directives.html#including-an-external-document-fragment
278 As I said earlier in chapter :chapter:`Objects.txt`, the
279 reference count gets increased every time a binding is made.
283 As I said earlier in chapter 2, the
284 reference count gets increased every time a binding is made.
286 The ToC in this form doesn't even need to be references to actual
287 reST documents; I'm simply doing it that way for a minimum of
288 future-proofing, in case I do want to add the ability to pick up
289 references within external chapters.
291 Perhaps, instead of ToC (which would overload the "contents"
292 directive concept already in use), we could use "manifest". A
293 "manifest" directive might associate local reference names with
297 intro: Introduction.txt
302 Then the sample becomes::
304 .. include:: manifest.txt
306 As I said earlier in chapter :chapter:`objects`, the
307 reference count gets increased every time a binding is made.
309 * Add support for _`multiple output files` and _`generic data
312 It should be possible for a component to **emit or reference** data
313 to be either **included or referenced** in the output document.
314 Examples of such data are stylesheets or images.
316 For this, we need a "data" object which stores the data either
317 inline or by referring to a file. The Docutils framework is
318 responsible for either:
320 * storing the data in the appropriate location (e.g. in the
321 directory of the output file, or in a user-specified directory)
322 and providing the paths of the stored files to the writer, *or*
324 * providing the data itself to the writer so that it can be embedded
325 in the output document.
327 This approach decouples data handling from the data source (which
328 can either be embedded or referenced) and the destination (which can
329 either be embedded or referenced as well).
331 See <http://article.gmane.org/gmane.text.docutils.devel/3631>.
333 * Add testing for Docutils' front end tools?
335 * Publisher: "Ordinary setup" shouldn't requre specific ordering; at
336 the very least, there ought to be error checking higher up in the
339 ``Publisher.get_settings`` requires that all components be set up
340 before it's called. Perhaps the I/O *objects* shouldn't be set, but
341 I/O *classes*. Then options are set up (``.set_options``), and
342 ``Publisher.set_io`` (or equivalent code) is called with source &
343 destination paths, creating the I/O objects.
345 Perhaps I/O objects shouldn't be instantiated until required. For
346 split output, the Writer may be called multiple times, once for each
347 doctree, and each doctree should have a separate Output object (with
348 a different path). Is the "Builder" pattern applicable here?
350 * Perhaps I/O objects should become full-fledged components (i.e.
351 subclasses of ``docutils.Component``, as are Readers, Parsers, and
352 Writers now), and thus have associated option/setting specs and
355 * Multiple file I/O suggestion from Michael Hudson: use a file-like
356 object or something you can iterate over to get file-like objects.
358 * Add an "--input-language" option & setting? Specify a different
359 language module for input (bibliographic fields, directives) than
360 for output. The "--language" option would set both input & output
363 * Auto-generate reference tables for language-dependent features?
364 Could be generated from the source modules. A special command-line
365 option could be added to Docutils front ends to do this. (Idea from
368 * Enable feedback of some kind from internal decisions, such as
369 reporting the successful input encoding. Modify runtime settings?
370 System message? Simple stderr output?
372 * Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
374 * Add an "--include file" command-line option (config setting too?),
375 equivalent to ".. include:: file" as the first line of the doc text?
376 Especially useful for character entity sets, text transform specs,
379 * Support "include" as embedded inline-compatible directive in substitution
382 .. |version| include:: version.txt
384 This document describes version |version| of ...
386 (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
388 * Add an ``:optional: <replacement text>`` option to the "include"
389 directive? This would not throw an error for a missing file, instead a
390 warning is given and ``<replacement text>`` is used instead. It would be
391 the responsibility of the author to ensure the missing file does not lead
392 to problems later in the document.
396 + Standard rST syntax to replace Sphinx's "literalinclude"::
398 .. include:: blah.cpp
400 :optional: file ``blah.cpp`` not found
402 + Variable content taken from a file, e.g.
406 .. |version| replace:: 3.1
410 .. include:: version.txt
411 :optional: .. |version| replace:: unknown
413 This document describes version |version| of ...
415 (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
417 * Parameterize the Reporter object or class? See the `2004-02-18
418 "rest checking and source path"`_ thread.
420 .. _2004-02-18 "rest checking and source path":
421 http://thread.gmane.org/gmane.text.docutils.user/1112
423 * Add a "disable_transforms" setting? And a dummy Writer subclass
424 that does nothing when its .write() method is called? Would allow
425 for easy syntax checking. See the `2004-02-18 "rest checking and
426 source path"`_ thread.
428 * Add a generic meta-stylesheet mechanism? An external file could
429 associate style names ("class" attributes) with specific elements.
430 Could be generalized to arbitrary output attributes; useful for HTML
431 & XMLs. Aahz implemented something like this in
432 sandbox/aahz/Effective/EffMap.py.
434 * .. _classes for table cells:
436 William Dode suggested that table cells be assigned "class"
437 attributes by columns, so that stylesheets can affect text
438 alignment. Unfortunately, there doesn't seem to be a way (in HTML
439 at least) to leverage the "colspec" elements (HTML "col" tags) by
440 adding classes to them. The resulting HTML is very verbose::
442 <td class="col1">111</td>
443 <td class="col2">222</td>
446 At the very least, it should be an option. People who don't use it
447 shouldn't be penalized by increases in their HTML file sizes.
449 Table rows could also be assigned classes (like odd/even). That
450 would be easier to implement.
452 How should it be implemented?
454 * There could be writer options (column classes & row classes) with
457 * The table directive could grow some options. Something like
458 ":cell-classes: col1 col2 col3" (either must match the number of
459 columns, or repeat to fill?) and ":row-classes: odd even" (repeat
460 to fill; body rows only, or header rows too?).
462 Probably per-table directive options are best. The "class" values
463 could be used by any writer, and applying such classes to all tables
464 in a document with writer options is too broad.
466 See also the `table_styling Sphinx extension`_ which defines
468 :widths: also in Docutils core (but different implementation)
469 :column-alignment: Sets per-column text alignment
470 :column-wrapping: Sets per-column text wrapping
471 :column-dividers: Add dividers between columns
472 :column-classes: Add per-column css classes.
473 :header-columns: Specify number of “stub” columns
475 .. _table_styling Sphinx extension: https://pythonhosted.org/cloud_sptheme/
476 lib/cloud_sptheme.ext.table_styling.html
478 * Add file-specific settings support to config files, like::
483 Is this even possible? Should the criterion be the name of the
484 input file or the output file? Alternative (more explicit) syntax::
486 [source_file index.txt]
489 [dest_file index.html]
492 Or rather allow settings configuration from the rst source file
493 (see misc.settings_ directive)?
495 * The "validator" support added to OptionParser is very similar to
496 "traits_" in SciPy_. Perhaps something could be done with them?
497 (Had I known about traits when I was implementing docutils.frontend,
498 I may have used them instead of rolling my own.)
500 .. _traits: http://code.enthought.com/traits/
501 .. _SciPy: http://www.scipy.org/
503 * tools/buildhtml.py: Extend the --prune option ("prune" config
504 setting) to accept file names (generic path) in addition to
505 directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
506 *not* be converted to HTML).
508 * Add support for _`plugins`.
510 * _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
511 /etc/docutils.conf are read as configuration files. Proposal: allow
512 ~/.docutils to be a a configuration *directory*, along with
513 /etc/docutils/ and ./docutils.conf/. Within these directories,
514 check for config.txt files. We can also have subdirectories here,
515 for plugins, S5 themes, components (readers/writers/parsers) etc.
517 Docutils will continue to support configuration files for backwards
520 * Add support for document decorations other than headers & footers?
521 For example, top/bottom/side navigation bars for web pages. Generic
524 Seems like a bad idea as long as it isn't independent from the ouput
525 format (for example, navigation bars are only useful for web pages).
527 * docutils_update: Check for a ``Makefile`` in a directory, and run
528 ``make`` if found? This would allow for variant processing on
529 specific source files, such as running rst2s5.py instead of
532 * Add a "disable table of contents" setting? The S5 writer could set
533 it as a default. Rationale:
535 The ``contents`` (table of contents) directive must not be used
536 [in S5/HTML documents]. It changes the CSS class of headings
537 and they won't show up correctly in the screen presentation.
539 -- `Easy Slide Shows With reStructuredText & S5
540 <../user/slide-shows.html>`_
542 Analogue to the ``sectnum_xform`` setting, it could be used by the
543 latex writer to switch to a LaTeX generated ToC (currently, the latex
544 writer calls it "use_latex_toc").
546 object numbering and object references
547 --------------------------------------
549 For equations, tables & figures.
551 These would be the equivalent of DocBook's "formal" elements.
553 In LaTeX, automatic counters are implemented for sections, equations and
554 floats (figures, tables) (configurable via stylesheets or in the
555 latex-preamble). Objects can be given `reference names`_ with the
556 ``\label{<refname}`` command, ``\ref{<refname>}`` inserts the
557 corresponding number.
559 No such mechanism exists in HTML.
561 * We need _`persistent sequences`, similar to chapter and footnote
562 numbers. See `OpenOffice.org XML`_ "fields".
564 - Should the sequences be automatic or manual (user-specifyable)?
566 * It is already possible to give `reference names`_ to objects via
567 internal hyperlink targets or the "name" directive option::
571 .. figure:: image.png
575 .. figure:: image.png
578 Improve the mapping of "phrase references" to IDs/labels with
579 Literal transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just
580 stripping the accents and other non-ASCII chars.
581 Use http://pypi.python.org/pypi/Unidecode?
583 A "table" directive has been implemented, supporting table titles.
585 Perhaps the name could derive from the title/caption?
587 .. _reference names: ../ref/rst/restructuredtext.html#reference-names
589 * We need syntax for object references. Cf. `OpenOffice.org XML`_
592 - Parameterized substitutions are too complicated
593 (cf. `or not to do`: `object references`_)
595 - An interpreted text approach is simpler and better::
597 See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
599 - "equation", "figure", and "page" roles could generate appropriate
602 See :figure:`figure name` on :page:`figure name`.
604 See `Interpreted Text`_ below.
606 Reference boilerplate could be specified in the document
607 (defaulting to nothing)::
610 :prefix-ref: "Figure "
611 :prefix-caption: "Fig. "
614 The position of the role (prefix or suffix) could also be utilized
616 .. _OpenOffice.org XML: http://xml.openoffice.org/
617 .. _object references: rst/alternatives.html#object-references
619 See also the `Modified rst2html
620 <http://www.loria.fr/~rougier/coding/article/rst2html.py>`__
621 by Nicolas Rougier for a sample implementation.
630 * Add a FAQ entry about using Docutils (with reStructuredText) on a
631 server and that it's terribly slow. See the first paragraphs in
632 <http://article.gmane.org/gmane.text.docutils.user/1584>.
634 * Add document about what Docutils has previously been used for
635 (web/use-cases.txt?).
637 * Improve index in docs/user/config.txt.
643 * Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
645 * Improve the internal module documentation (docstrings in the code).
646 Specific deficiencies listed below.
648 - docutils.parsers.rst.states.State.build_table: data structure
649 required (including StringList).
651 - docutils.parsers.rst.states: more complete documentation of parser
654 * docs/ref/doctree.txt: DTD element structural relationships,
655 semantics, and attributes. In progress; element descriptions to be
658 * Document the ``pending`` elements, how they're generated and what
661 * Document the transforms (perhaps in docstrings?): how they're used,
662 what they do, dependencies & order considerations.
664 * Document the HTML classes used by html4css1.py.
666 * Write an overview of the Docutils architecture, as an introduction
667 for developers. What connects to what, why, and how. Either update
668 PEP 258 (see PEPs_ below) or as a separate doc.
670 * Give information about unit tests. Maybe as a howto?
672 * Document the docutils.nodes APIs.
674 * Complete the docs/api/publisher.txt docs.
680 * Creating Docutils Writers
682 * Creating Docutils Readers
684 * Creating Docutils Transforms
686 * Creating Docutils Parsers
688 * Using Docutils as a Library
694 * Complete PEP 258 Docutils Design Specification.
696 - Fill in the blanks in API details.
698 - Specify the nodes.py internal data structure implementation?
700 [Tibs:] Eventually we need to have direct documentation in
701 there on how it all hangs together - the DTD is not enough
702 (indeed, is it still meant to be correct? [Yes, it is.
705 * Rework PEP 257, separating style from spec from tools, wrt Docutils?
706 See Doc-SIG from 2001-06-19/20.
714 * Analyze Tony Ibbs' PySource code.
716 * Analyze Doug Hellmann's HappyDoc project.
718 * Investigate how POD handles literate programming.
720 * Take the best ideas and integrate them into Docutils.
724 * Ask Python-dev for opinions (GvR for a pronouncement) on special
725 variables (__author__, __version__, etc.): convenience vs. namespace
726 pollution. Ask opinions on whether or not Docutils should recognize
729 * If we can detect that a comment block begins with ``##``, a la
730 JavaDoc, it might be useful to indicate interspersed section headers
731 & explanatory text in a module. For example::
733 """Module docstring."""
746 class MyException(Exception): pass
750 * Should standalone strings also become (module/class) docstrings?
751 Under what conditions? We want to prevent arbitrary strings from
752 becomming docstrings of prior attribute assignments etc. Assume
753 that there must be no blank lines between attributes and attribute
754 docstrings? (Use lineno of NEWLINE token.)
756 Triple-quotes are sometimes used for multi-line comments (such as
757 commenting out blocks of code). How to reconcile?
759 * HappyDoc's idea of using comment blocks when there's no docstring
760 may be useful to get around the conflict between `additional
761 docstrings`_ and ``from __future__ import`` for module docstrings.
762 A module could begin like this::
764 #!/usr/bin/env python
766 # :Copyright: whatever
768 """This is the public module docstring (``__doc__``)."""
770 # More docs, in comments.
771 # All comments at the beginning of a module could be
772 # accumulated as docstrings.
773 # We can't have another docstring here, because of the
774 # ``__future__`` statement.
776 from __future__ import division
778 Using the JavaDoc convention of a doc-comment block beginning with
779 ``##`` is useful though. It allows doc-comments and implementation
782 .. _additional docstrings:
783 ../peps/pep-0258.html#additional-docstrings
785 * HappyDoc uses an initial comment block to set "parser configuration
786 values". Do the same thing for Docutils, to set runtime settings on
787 a per-module basis? I.e.::
789 # Docutils:setting=value
791 Could be used to turn on/off function parameter comment recognition
792 & other marginal features. Could be used as a general mechanism to
793 augment config files and command-line options (but which takes
796 * Multi-file output should be divisible at arbitrary level.
798 * Support all forms of ``import`` statements:
800 - ``import module``: listed as "module"
801 - ``import module as alias``: "alias (module)"
802 - ``from module import identifier``: "identifier (from module)"
803 - ``from module import identifier as alias``: "alias (identifier
805 - ``from module import *``: "all identifiers (``*``) from module"
807 * Have links to colorized Python source files from API docs? And
808 vice-versa: backlinks from the colorized source files to the API
811 * In summaries, use the first *sentence* of a docstring if the first
812 line is not followed by a blank line.
815 reStructuredText Parser
816 =======================
818 Also see the `... Or Not To Do?`__ list.
820 __ rst/alternatives.html#or-not-to-do
825 * Another list problem::
831 This ends up as a definition list. This is more of a usability
834 * This case is probably meant to be a nested list, but it ends up as a
835 list inside a block-quote without an error message::
841 It should probably just be an error.
843 The problem with this is that you don't notice easily in HTML that
844 it's not a nested list but a block-quote -- there's not much of a
847 * Treat enumerated lists that are not arabic and consist of only one
848 item in a single line as ordinary paragraphs. See
849 <http://article.gmane.org/gmane.text.docutils.user/2635>.
851 * The citation syntax could use some improvements. See
852 <http://thread.gmane.org/gmane.text.docutils.user/2499> (and the
854 <http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>,
855 and the follow-ups at
856 <http://thread.gmane.org/gmane.text.docutils.user/3087>,
857 <http://thread.gmane.org/gmane.text.docutils.user/3110>,
858 <http://thread.gmane.org/gmane.text.docutils.user/3114>),
859 <http://thread.gmane.org/gmane.text.docutils.user/2443>,
860 <http://thread.gmane.org/gmane.text.docutils.user/2715>,
861 <http://thread.gmane.org/gmane.text.docutils.user/3027>,
862 <http://thread.gmane.org/gmane.text.docutils.user/3120>,
863 <http://thread.gmane.org/gmane.text.docutils.user/3253>.
865 * The current list-recognition logic has too many false positives, as
872 Here ``V.`` is recognized as an enumerator, which leads to
873 confusion. We need to find a solution that resolves such problems
874 without complicating the spec to much.
876 See <http://thread.gmane.org/gmane.text.docutils.user/2524>.
878 * Add indirect links via citation references & footnote references.
881 `Goodger (2005)`_ is helpful.
883 .. _Goodger (2005): [goodger2005]_
884 .. [goodger2005] citation text
886 See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
888 * Complain about bad URI characters
889 (http://article.gmane.org/gmane.text.docutils.user/2046) and
890 disallow internal whitespace
891 (http://article.gmane.org/gmane.text.docutils.user/2214).
893 * Create ``info``-level system messages for unnecessarily
894 backslash-escaped characters (as in ``"\something"``, rendered as
895 "something") to allow checking for errors which silently slipped
898 * Add (functional) tests for untested roles.
900 * Add test for ":figwidth: image" option of "figure" directive. (Test
901 code needs to check if PIL is available on the system.)
903 * Add support for CJK double-width whitespace (indentation) &
904 punctuation characters (markup; e.g. double-width "*", "-", "+")?
906 * Add motivation sections for constructs in spec.
908 * Support generic hyperlink references to _`targets in other
909 documents`? Not in an HTML-centric way, though (it's trivial to say
910 ``http://www.example.com/doc#name``, and useless in non-HTML
911 contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
914 * .. _adaptable file extensions:
916 In target URLs, it would be useful to not explicitly specify the
917 file extension. If we're generating HTML, then ".html" is
918 appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
919 indicate "choose the most appropriate filename extension"? For
922 .. _Another Document: another.*
924 What is to be done for output formats that don't *have* hyperlinks?
925 For example, LaTeX targeted at print. Hyperlinks may be "called
926 out", as footnotes with explicit URLs. (Don't convert the links.)
928 But then there's also LaTeX targeted at PDFs, which *can* have
929 links. Perhaps a runtime setting for "*" could explicitly provide
930 the extension, defaulting to the output file's extension.
932 Should the system check for existing files? No, not practical.
934 Handle documents only, or objects (images, etc.) also?
936 If this handles images also, how to differentiate between document
937 and image links? Element context (within "image")? Which image
938 extension to use for which document format? Again, a runtime
939 setting would suffice.
941 This may not be just a parser issue; it may need framework support.
943 Mailing list threads: `Images in both HTML and LaTeX`__ (especially
944 `this summary of Lea's objections`__), `more-universal links?`__,
945 `Output-format-sensitive link targets?`__
947 __ http://thread.gmane.org/gmane.text.docutils.user/1239
948 __ http://article.gmane.org/gmane.text.docutils.user/1278
949 __ http://thread.gmane.org/gmane.text.docutils.user/1915
950 __ http://thread.gmane.org/gmane.text.docutils.user/2438
952 Idea from Jim Fulton: an external lookup table of targets:
954 I would like to specify the extension (e.g. .txt) [in the
955 source, rather than ``filename.*``], but tell the converter to
956 change references to the files anticipating that the files will
961 .. _Another Document: another.txt
963 rst2html.py --convert-links "another.txt bar.txt" foo.txt
965 That is, name the files for which extensions should be converted.
967 Note that I want to refer to original files in the original text
968 (another.txt rather than another.txt) because I want the
969 unconverted text to stand on its own.
971 Note that in most cases, people will be able to use globs::
973 rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
975 It might be nice to be able to use multiple arguments, as in::
977 rst2html.py --convert-link-extensions-for *.txt -- foo.txt
981 > What is to be done for output formats
982 > that don't have hyperlinks?
984 Don't convert the links.
988 > Handle documents only, or objects
989 > (images, etc.) also?
991 No, documents only, but there really is no need for gueswork.
992 Just get the file names as command-line arguments. EIBTI
993 [explicit is better than implicit].
995 For images, we probably need separate solution (which is being
996 worked on), whereas for documents, the issue is basically
997 interlinking between reStructuredText documents. IMO, this cries
998 for support for multiple input and output files, i.e. support for
999 documents which comprise multiple files. Adding adaptable file
1000 extensions seems like a kludge. // FW
1002 * Implement the header row separator modification to table.el. (Wrote
1003 to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
1004 support for "=====" header rows. On 2001-08-17 he replied, saying
1005 he'd put it on his to-do list, but "don't hold your breath".)
1007 * Fix the parser's indentation handling to conform with the stricter
1008 definition in the spec. (Explicit markup blocks should be strict or
1011 .. XXX What does this mean? Can you elaborate, David?
1013 * Make the parser modular. Allow syntax constructs to be added or
1014 disabled at run-time. Subclassing is probably not enough because it
1015 makes it difficult to apply multiple extensions.
1017 * Generalize the "doctest block" construct (which is overly
1018 Python-centric) to other interactive sessions? "Doctest block"
1019 could be renamed to "I/O block" or "interactive block", and each of
1020 these could also be recognized as such by the parser:
1025 A block beginning with a "$ " prompt is interpreted as a shell
1026 session interactive block. As with Doctest blocks, the
1027 interactive block ends with the first blank line, and wouldn't
1028 have to be indented.
1030 - Root shell sessions::
1033 A block beginning with a "# " prompt is interpreted as a root
1034 shell session (the user is or has to be logged in as root)
1035 interactive block. Again, the block ends with a blank line.
1037 Other standard (and unambiguous) interactive session prompts could
1038 easily be added (such as "> " for WinDOS).
1040 Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
1041 "docutils feedback").
1043 * Add support for pragma (syntax-altering) directives.
1045 Some pragma directives could be local-scope unless explicitly
1046 specified as global/pragma using ":global:" options.
1048 * Support whitespace in angle-bracketed standalone URLs according to
1049 Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
1052 .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt
1054 * Use the vertical spacing of the source text to determine the
1055 corresponding vertical spacing of the output?
1057 * [From Mark Nodine] For cells in simple tables that comprise a
1058 single line, the justification can be inferred according to the
1061 1. If the text begins at the leftmost column of the cell,
1062 then left justification, ELSE
1063 2. If the text begins at the rightmost column of the cell,
1064 then right justification, ELSE
1065 3. Center justification.
1067 The onus is on the author to make the text unambiguous by adding
1068 blank columns as necessary. There should be a parser setting to
1069 turn off justification-recognition (normally on would be fine).
1071 Decimal justification?
1073 All this shouldn't be done automatically. Only when it's requested
1074 by the user, e.g. with something like this::
1081 Otherwise it will break existing documents.
1083 * Generate a warning or info message for paragraphs which should have
1084 been lists, like this one::
1089 * Generalize the "target-notes" directive into a command-line option
1090 somehow? See docutils-develop 2003-02-13.
1092 * Allow a "::"-only paragraph (first line, actually) to introduce a
1093 _`literal block without a blank line`? (Idea from Paul Moore.) ::
1096 This is a literal block
1098 Is indentation enough to make the separation between a paragraph
1099 which contains just a ``::`` and the literal text unambiguous?
1100 (There's one problem with this concession: If one wants a definition
1101 list item which defines the term "::", we'd have to escape it.) It
1102 would only be reasonable to apply it to "::"-only paragraphs though.
1103 I think the blank line is visually necessary if there's text before
1106 The text in this paragraph needs separation
1107 from the literal block following::
1108 This doesn't look right.
1110 * Add new syntax for _`nested inline markup`? Or extend the parser to
1111 parse nested inline markup somehow? See the `collected notes
1112 <rst/alternatives.html#nested-inline-markup>`__.
1114 * Drop the backticks from embedded URIs with omitted reference text?
1115 Should the angle brackets be kept in the output or not? ::
1119 Probably not worth the trouble.
1121 * How about a syntax for alternative hyperlink behavior, such as "open
1122 in a new window" (as in HTML's ``<a target="_blank">``)?
1124 The MoinMoin wiki uses a caret ("^") at the beginning of the URL
1125 ("^" is not a legal URI character). That could work for both inline
1126 and explicit targets::
1128 The `reference docs <^url>`__ may be handy.
1132 This may be too specific to HTML. It hasn't been requested very
1135 * Add an option to add URI schemes at runtime.
1137 * _`Segmented lists`::
1139 : segment : segment : segment
1140 : segment : segment : very long
1142 : segment : segment : segment
1144 The initial colon (":") can be thought of as a type of bullet
1146 We could even have segment titles::
1148 :: title : title : title
1149 : segment : segment : segment
1150 : segment : segment : segment
1152 This would correspond well to DocBook's SegmentedList. Output could
1153 be tabular or "name: value" pairs, as described in DocBook's docs.
1155 * Allow backslash-escaped colons in field names::
1157 :Case Study\: Event Handling: This chapter will be dropped.
1159 * Enable grid _`tables inside XML comments`, where "``--``" ends comments.
1161 Implementation possibilities:
1163 1. Make the table syntax characters into "table" directive options.
1164 This is the most flexible but most difficult, and we probably
1165 don't need that much flexibility.
1167 2. Substitute "~" for "-" with a specialized directive option
1170 3. Make the standard table syntax recognize "~" as well as "-", even
1171 without a directive option. Individual tables would have to be
1172 internally consistent.
1174 4. Allow Unicode box characters for table markup
1175 (`feature request [6]`_)
1177 Directive options are preferable to configuration settings, because
1178 tables are document-specific. A pragma directive would be another
1179 approach, to set the syntax once for a whole document.
1181 Unicode box character markup would kill two birds with one stone.
1183 In the meantime, the list-table_ directive is a good replacement for
1184 grid tables inside XML comments.
1186 .. _feature request [6]:
1187 http://sourceforge.net/p/docutils/feature-requests/6
1188 .. _list-table: ../ref/rst/directives.html#list-table
1191 * Generalize docinfo contents (bibliographic fields): remove specific
1192 fields, and have only a single generic "field"?
1194 * _`Line numbers` and "source" in system messages:
1196 - Add "source" and "line" keyword arguments to all Reporter calls?
1197 This would require passing source/line arguments along all
1198 intermediate functions (where currently only `line` is used).
1200 Or rather specify "line" only if actually needed?
1202 Currently, `document.reporter` uses a state machine instance to
1203 determine the "source" and "line" info from
1204 `statemachine.input_lines` if not given explicitely. Except for
1205 special cases, the "line" argument is not needed because,
1206 `document.statemachine` keeps record of the current line number.
1208 - For system messages generated after the parsing is completed (i.e. by
1209 transforms or the writer) "line" info must be present in the doctree
1212 Elements' .line assignments should be checked. (Assign to .source
1213 too? Add a set_info method? To what?)
1215 The "source" (and line number in the source) can either be added
1216 explicitely to the elements or determined from the “raw” line
1217 number by `document.statemachine.get_source_and_line`.
1219 - Some line numbers in elements are not being set properly
1220 (explicitly), just implicitly/automatically. See rev. 1.74 of
1221 docutils/parsers/rst/states.py for an example of how to set.
1223 - The line numbers of definition list items are wrong::
1225 $ rst2pseudoxml.py --expose-internal-attribute line
1234 <document source="<stdin>">
1236 <definition_list_item internal:line="3">
1240 <paragraph internal:line="2">
1243 <definition_list_item internal:line="6">
1247 <paragraph internal:line="6">
1253 Quite a few nodes are getting a "None" source attribute as well. In
1254 particular, see the bodies of definition lists.
1261 Since Docutils 0.8, a "math" role and directive using LaTeX math
1262 syntax as input format is part of reStructuredText.
1266 * Use a "Transform" for math format conversions as extensively discussed in
1267 the "math directive issues" thread in May 2008
1268 (http://osdir.com/ml/text.docutils.devel/2008-05/threads.html)?
1270 * Generic `math-output setting`_ (currently specific to HTML).
1271 (List of math-output preferences?)
1273 * Try to be compatible with `Math support in Sphinx`_?
1275 * The ``:label:`` option selects a label for the equation, by which it
1276 can be cross-referenced, and causes an equation number to be issued.
1277 In Docutils, the option ``:name:`` sets the label.
1278 Equation numbering is not implemented yet.
1280 * Option ``:nowrap:`` prevents wrapping of the given math in a
1281 math environment (you have to specify the math environment in the
1284 .. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
1286 * Equation numbering and references. (see the section on
1287 `object numbering and object references` for equations,
1288 formal tables, and images.)
1290 .. _math-output setting: ../user/config.html#math-output
1293 alternative input formats
1294 `````````````````````````
1296 Use a directive option to specify an alternative input format, e.g. (but not
1300 Not for hand-written code but maybe usefull when pasted in (or included
1303 For an overview of MathML implementations and tests, see, e.g.,
1304 the `mathweb wiki`_ or the `ConTeXT MathML page`_.
1306 .. _MathML: http://www.w3.org/TR/MathML2/
1307 .. _mathweb wiki: http://www.mathweb.org/wiki/MathML
1308 .. _ConTeXT MathML page: http://wiki.contextgarden.net/MathML
1312 Simple, ASCII based math input language (see also `ASCIIMath tutorial`_).
1314 * The Python module ASCIIMathML_ translates a string with ASCIIMath into a
1315 MathML tree. Used, e.g., by MultiMarkdown__.
1317 A more comprehensive implementation is ASCIIMathPython_ by
1318 Paul Trembley (also used in his sandbox projects).
1320 * For conversion to LaTeX, there is a JavaScript script at
1321 http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js
1323 .. _ASCIIMath: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
1324 .. _ASCIIMath tutorial:
1325 http://www.wjagray.co.uk/maths/ASCIIMathTutorial.html
1326 .. _ASCIIMathML: http://pypi.python.org/pypi/asciimathml/
1327 .. _ASCIIMathPython: http://sourceforge.net/projects/asciimathpython/
1328 __ http://fletcherpenney.net/multimarkdown/
1330 `Unicode Nearly Plain Text Encoding of Mathematics`_
1331 format for lightly marked-up representation of mathematical
1332 expressions in Unicode.
1334 (Unicode Technical Note. Sole responsibility for its contents rests
1335 with the author(s). Publication does not imply any endorsement by
1336 the Unicode Consortium.)
1338 .. _Unicode Nearly Plain Text Encoding of Mathematics:
1339 http://www.unicode.org/notes/tn28/
1342 See `the culmination of a relevant discussion in 2003
1343 <http://article.gmane.org/gmane.text.docutils.user/118>`__.
1350 Which equation environments should be supported by the math directive?
1354 + numbered: `equation`
1355 + unnumbered: `equation*`
1357 * multiline (test for ``\\`` outside of a nested environment
1358 (e.g. `array` or `cases`)
1360 + numbered: `align` (number every line)
1362 (To give one common number to all lines, put them in a `split`
1363 environment. Docutils then places it in an `equation` environment.)
1365 + unnumbered: `align*`
1367 + Sphinx math also supports `gather` (checking for blank lines in
1368 the content). Docutils puts content blocks separated by blank
1369 lines in separate math-block doctree nodes. (The only difference of
1370 `gather` to two consecutive "normal" environments seems to be that
1371 page-breaks between the two are prevented.)
1373 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
1379 There is no native math support in HTML.
1380 For supported math output variants see the `math-output setting`_.
1381 Add more/better alternatives?
1384 Converters from LaTeX to MathML include
1386 * TtM_ (C), ``--math-output=MathML ttm``, undocumented, may be removed.
1388 No "matrix", "align" and "cases" environments.
1391 * TeX4ht_ (TeX based)
1392 * itex_ (also `used in Abiword`__)
1393 * `Steve’s LATEX-to-MathML translator`_
1394 ('mini-language', javascript, Python)
1395 * `MathJax for Node`_
1397 * Write a new converter? E.g. based on:
1399 * a generic tokenizer (see e.g. a `latex-codec recipe`_,
1400 `updated latex-codec`_, )
1401 * the Unicode-Char <-> LaTeX mappings database unimathsymbols_
1403 __ http://msevior.livejournal.com/26377.html
1404 .. _MathML: http://www.w3.org/TR/MathML2/
1405 .. _ttm: http://hutchinson.belmont.ma.us/tth/mml/
1406 .. _TeX4ht: http://www.tug.org/applications/tex4ht/mn.html
1407 .. _MathToWeb: http://www.mathtoweb.com/
1408 .. _itex: http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html
1409 .. _Steve’s LATEX-to-MathML translator:
1410 http://www.gold-saucer.org/mathml/greasemonkey/dist/display-latex
1411 .. _latex-codec recipe:
1412 http://code.activestate.com/recipes/252124-latex-codec/
1413 .. _updated latex-codec:
1414 http://mirror.ctan.org/biblio/bibtex/utils/mab2bib/latex.py
1415 .. _unimathsymbols: http://milde.users.sourceforge.net/LUCR/Math/
1416 .. _MathJax for Node: https://github.com/mathjax/MathJax-node
1419 .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
1423 format math in standard HTML enhanced by CSS rules
1424 (Overview__, `Examples and experiments`__).
1425 The ``math-output=html`` option uses the converter from eLyXer_
1426 (included with Docutils).
1428 Alternatives: LaTeX-math to HTML/CSS converters include
1431 * Hevea_ (Objective Caml)
1432 * `MathJax for Node`_
1434 __ http://www.cs.tut.fi/~jkorpela/math/
1435 __ http://www.zipcon.net/~swhite/docs/math/math.html
1436 .. _elyxer: http://elyxer.nongnu.org/
1437 .. _TtH: ttp://hutchinson.belmont.ma.us/tth/index.html
1438 .. _Hevea: http://para.inria.fr/~maranget/hevea/
1441 (PNG or SVG) like e.g. Wikipedia.
1444 * the pure-python MathML->SVG converter SVGMath_)
1445 * `MathJax for Node`_
1447 .. _dvisvgm: http://dvisvgm.sourceforge.net/
1448 .. _SVGMath: http://www.grigoriev.ru/svgmath/
1451 client side JavaScript conversion
1452 Use TeX notation in the web page and JavaScript in the displaying browser.
1453 (implemented as `math-output setting`_ "mathjax").
1455 * jqMath_ (faster and lighter than MathJax_)
1457 .. _MathJax: http://www.mathjax.org/
1458 .. _jqMath: http://mathscribe.com/author/jqmath.html
1463 * The `OpenDocument standard`_ version 1.1 says:
1465 Mathematical content is represented by MathML 2.0
1467 However, putting MathML into an ODP file seems tricky as these
1468 (maybe outdated) links suppose:
1469 http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx
1470 http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx
1472 .. _OpenDocument standard:
1473 http://www.oasis-open.org/standards#opendocumentv1.1
1475 * OOoLaTeX__: "a set of macros designed to bring the power of LaTeX
1478 __ http://ooolatex.sourceforge.net/
1484 Directives below are often referred to as "module.directive", the
1485 directive function. The "module." is not part of the directive name
1486 when used in a document.
1488 * Allow for field lists in list tables. See
1489 <http://thread.gmane.org/gmane.text.docutils.devel/3392>.
1493 Unify table implementations and unify options of table directives
1494 (http://article.gmane.org/gmane.text.docutils.user/1857).
1496 * Allow directives to be added at run-time?
1498 * Use the language module for directive option names?
1500 * Add "substitution_only" and "substitution_ok" function attributes,
1501 and automate context checking?
1503 * Implement options or features on existing directives:
1505 - All directives that produce titled elements should grow implicit
1506 reference names based on the titles.
1508 - Allow the _`:trim:` option for all directives when they occur in a
1509 substitution definition, not only the unicode_ directive.
1511 .. _unicode: ../ref/rst/directives.html#unicode-character-codes
1513 - Add the "class" option to the unicode_ directive. For example, you
1514 might want to get characters or strings with borders around them.
1516 - _`images.figure`: "title" and "number", to indicate a formal
1519 - _`parts.sectnum`: "local"?, "refnum"
1521 A "local" option could enable numbering for sections from a
1522 certain point down, and sections in the rest of the document are
1523 not numbered. For example, a reference section of a manual might
1524 be numbered, but not the rest. OTOH, an all-or-nothing approach
1525 would probably be enough.
1527 The "sectnum" directive should be usable multiple times in a
1528 single document. For example, in a long document with "chapter"
1529 and "appendix" sections, there could be a second "sectnum" before
1530 the first appendix, changing the sequence used (from 1,2,3... to
1531 A,B,C...). This is where the "local" concept comes in. This part
1532 of the implementation can be left for later.
1534 A "refnum" option (better name?) would insert reference names
1535 (targets) consisting of the reference number. Then a URL could be
1536 of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
1537 internal references by number? Allow name-based *and*
1538 number-based ids at the same time, or only one or the other (which
1539 would the table of contents use)? Usage issue: altering the
1540 section structure of a document could render hyperlinks invalid.
1542 - _`parts.contents`: Add a "suppress" or "prune" option? It would
1543 suppress contents display for sections in a branch from that point
1544 down. Or a new directive, like "prune-contents"?
1546 Add an option to include topics in the TOC? Another for sidebars?
1547 The "topic" directive could have a "contents" option, or the
1548 "contents" directive" could have an "include-topics" option. See
1549 docutils-develop 2003-01-29.
1551 - _`parts.header` & _`parts.footer`: Support multiple, named headers
1552 & footers? For example, separate headers & footers for odd, even,
1553 and the first page of a document.
1555 This may be too specific to output formats which have a notion of
1560 - Add a ``:parent:`` option for setting the parent's class
1561 (http://article.gmane.org/gmane.text.docutils.devel/3165).
1565 - Option to label lines?
1567 - How about an environment variable, say RSTINCLUDEPATH or
1568 RSTPATH, for standard includes (as in ``.. include:: <name>``)?
1569 This could be combined with a setting/option to allow
1570 user-defined include directories.
1572 - Add support for inclusion by URL? ::
1575 :url: http://www.example.org/inclusion.txt
1577 - Strip blank lines from begin and end of a literal included file or
1578 file section. This would correspond to the way a literal block is
1581 As nodes.literal_block expects (and we have) the text as a string
1582 (rather than a list of lines), using a regexp seems the way.
1584 - _`misc.raw`: add a "destination" option to the "raw" directive? ::
1591 It needs thought & discussion though, to come up with a consistent
1592 set of destination labels and consistent behavior.
1594 And placing HTML code inside the <head> element of an HTML
1595 document is rather the job of a templating system.
1597 - _`body.sidebar`: Allow internal section structure? Adornment
1598 styles would be independent of the main document.
1600 That is really complicated, however, and the document model
1601 greatly benefits from its simplicity.
1603 * Implement directives. Each of the list items below begins with an
1604 identifier of the form, "module_name.directive_function_name". The
1605 directive name itself could be the same as the
1606 directive_function_name, or it could differ.
1610 It has the disadvantage that it's only easily implementable for
1611 HTML, so it's specific to one output format.
1613 (For non-HTML writers, the imagemap would have to be replaced with
1616 - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
1618 - _`parts.citations`: See `Footnote & Citation Gathering`_.
1620 - _`misc.language`: Specify (= change) the language of a document at
1623 * The misc.settings_ directive suggested below offers a more generic
1626 * The language of document parts can be indicated by the "special class
1627 value" ``"language-"`` + `BCP 47`_ language code. Class arguments to
1628 the title are attached to the document's base node - hence titled
1629 documents can be given a different language at parse time. However,
1630 "language by class attribute" does not change parsing (localized
1631 directives etc.), only supporting writers.
1633 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1636 - _`misc.settings`: Set any(?) Docutils runtime setting from within
1637 a document? Needs much thought and discussion.
1639 Security concerns need to be taken into account (it shouldn't be
1640 possible to enable ``file_insertion_enabled`` from within a
1641 document), and settings that only would have taken effect before
1642 the directive (like ``tab-width``) shouldn't be accessible either.
1644 See this sub-thread:
1645 <http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649>
1647 - _`misc.gather`: Gather (move, or copy) all instances of a specific
1648 element. A generalization of the `Footnote & Citation Gathering`_
1651 - Add a custom "directive" directive, equivalent to "role"? For
1656 .. class:: incremental
1660 "``.. incr::``" above is equivalent to "``.. class:: incremental``".
1664 .. directive:: printed-links
1670 :class: print-inline
1672 This acts like macros. The directive contents will have to be
1673 evaluated when referenced, not when defined.
1675 * Needs a better name? "Macro", "substitution"?
1676 * What to do with directive arguments & options when the
1677 macro/directive is referenced?
1679 - Make the meaning of block quotes overridable? Only a 1-shot
1680 though; doesn't solve the general problem.
1682 - _`conditional directives`:
1684 .. note:: See also the implementation in Sphinx_.
1686 Docutils already has the ability to say "use this content for
1687 Writer X" via the "raw" directive. It also does have the ability
1688 to say "use this content for any Writer other than X" via the
1689 "strip-elements with class" config value. However, using "raw"
1690 input just to select a special writer is inconvenient in many
1692 It wouldn't be difficult to get more straightforward support, though.
1694 My first idea would be to add a set of conditional directives.
1695 Let's call them "writer-is" and "writer-is-not" for discussion
1696 purposes (don't worry about implemention details). We might
1699 .. writer-is:: text-only
1715 .. figure:: protocol_stack.eps
1717 .. writer-is-not:: text-only pdf
1719 .. figure:: protocol_stack.png
1721 This could be an interface to the Filter transform
1722 (docutils.transforms.components.Filter).
1724 The ideas in `adaptable file extensions`_ above may also be
1727 SVG's "switch" statement may provide inspiration.
1729 Here's an example of a directive that could produce multiple
1730 outputs (*both* raw troff pass-through *and* a GIF, for example)
1731 and allow the Writer to select. ::
1738 %sum from i=o to inf c sup i~=~lim from {m -> inf}
1739 sum from i=0 to m sup i%
1744 - _`body.example`: Examples; suggested by Simon Hefti. Semantics as
1745 per Docbook's "example"; admonition-style, numbered, reference,
1746 with a caption/title.
1748 - _`body.index`: Index targets.
1750 See `Index Entries & Indexes
1751 <./rst/alternatives.html#index-entries-indexes>`__.
1753 - _`body.literal`: Literal block, possibly "formal" (see `object
1754 numbering and object references`_ above). Possible options:
1756 - "highlight" a range of lines
1758 - include only a specified range of lines
1760 - "number" or "line-numbers"? (since 0.9 available with "code" directive)
1762 - "styled" could indicate that the directive should check for
1763 style comments at the end of lines to indicate styling or
1766 Specific derivatives (i.e., a "python-interactive" directive)
1767 could interpret style based on cues, like the ">>> " prompt and
1768 "input()"/"raw_input()" calls.
1770 See docutils-users 2003-03-03.
1772 - _`body.listing`: Code listing with title (to be numbered
1773 eventually), equivalent of "figure" and "table" directives.
1775 - _`pysource.usage`: Extract a usage message from the program,
1776 either by running it at the command line with a ``--help`` option
1777 or through an exposed API. [Suggestion for Optik.]
1779 - _`body.float`: Generic float that can be used for figures, tables,
1780 code listings, flowcharts, ...
1782 There is a Sphinx extension by Ignacio Fernández Galván <jellby@gmail.com>
1784 I implemented something for generic floats in sphinx, and submitted a
1785 pull request that is still waiting::
1789 :caption: My caption
1791 https://github.com/sphinx-doc/sphinx/pull/1858
1797 Interpreted text is entirely a reStructuredText markup construct, a
1798 way to get around built-in limitations of the medium. Some roles are
1799 intended to introduce new doctree elements, such as "title-reference".
1800 Others are merely convenience features, like "RFC".
1802 All supported interpreted text roles must already be known to the
1803 Parser when they are encountered in a document. Whether pre-defined
1804 in core/client code, or in the document, doesn't matter; the roles
1805 just need to have already been declared. Adding a new role may
1806 involve adding a new element to the DTD and may require extensive
1807 support, therefore such additions should be well thought-out. There
1808 should be a limited number of roles.
1810 The only place where no limit is placed on variation is at the start,
1811 at the Reader/Parser interface. Transforms are inserted by the Reader
1812 into the Transformer's queue, where non-standard elements are
1813 converted. Once past the Transformer, no variation from the standard
1814 Docutils doctree is possible.
1816 An example is the Python Source Reader, which will use interpreted
1817 text extensively. The default role will be "Python identifier", which
1818 will be further interpreted by namespace context into <class>,
1819 <method>, <module>, <attribute>, etc. elements (see pysource.dtd),
1820 which will be transformed into standard hyperlink references, which
1821 will be processed by the various Writers. No Writer will need to have
1822 any knowledge of the Python-Reader origin of these elements.
1824 * Add explicit interpreted text roles for the rest of the implicit
1825 inline markup constructs: named-reference, anonymous-reference,
1826 footnote-reference, citation-reference, substitution-reference,
1827 target, uri-reference (& synonyms).
1829 * Add directives for each role as well? This would allow indirect
1832 This text contains |nested inline markup|.
1834 .. |nested inline markup| emphasis::
1836 nested ``inline`` markup
1840 - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
1841 around role contents.
1843 For example, the following reStructuredText source ... ::
1845 .. role:: red(raw-formatting)
1847 :html: <font color="red">
1848 :latex: {\color{red}
1855 ... will yield the following document fragment::
1859 <inline classes="red">
1862 <raw format="latex">
1864 <inline classes="red">
1868 <raw format="latex">
1871 Possibly without the intermediate "inline" node.
1873 - _`"acronym" and "abbreviation"`: Associate the full text with a
1874 short form. Jason Diamond's description:
1876 I want to translate ```reST`:acronym:`` into ``<acronym
1877 title='reStructuredText'>reST</acronym>``. The value of the
1878 title attribute has to be defined out-of-band since you can't
1879 parameterize interpreted text. Right now I have them in a
1880 separate file but I'm experimenting with creating a directive
1881 that will use some form of reST syntax to let you define them.
1883 Should Docutils complain about undefined acronyms or
1886 What to do if there are multiple definitions? How to
1887 differentiate between CSS (Content Scrambling System) and CSS
1888 (Cascading Style Sheets) in a single document? David Priest
1891 The short answer is: you don't. Anyone who did such a thing
1892 would be writing very poor documentation indeed. (Though I
1893 note that `somewhere else in the docs`__, there's mention of
1894 allowing replacement text to be associated with the
1895 abbreviation. That takes care of the duplicate
1896 acronyms/abbreviations problem, though a writer would be
1897 foolish to ever need it.)
1899 __ `inline parameter syntax`_
1901 How to define the full text? Possibilities:
1903 1. With a directive and a definition list? ::
1910 Docstring Processing System
1912 Would this list remain in the document as a glossary, or would
1913 it simply build an internal lookup table? A "glossary"
1914 directive could be used to make the intention clear.
1915 Acronyms/abbreviations and glossaries could work together.
1917 Then again, a glossary could be formed by gathering individual
1918 definitions from around the document.
1920 2. Some kind of `inline parameter syntax`_? ::
1922 `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
1923 see is what you get>`:acronym: plaintext markup.
1925 .. _inline parameter syntax:
1926 rst/alternatives.html#parameterized-interpreted-text
1928 3. A combination of 1 & 2?
1930 The multiple definitions issue could be handled by establishing
1931 rules of priority. For example, directive-based lookup tables
1932 have highest priority, followed by the first inline definition.
1933 Multiple definitions in directive-based lookup tables would
1934 trigger warnings, similar to the rules of `implicit hyperlink
1937 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
1939 4. Using substitutions? ::
1941 .. |reST| acronym:: reST
1942 :text: reStructuredText
1944 What do we do for other formats than HTML which do not support
1945 tool tips? Put the full text in parentheses?
1947 - "figure", "table", "listing", "chapter", "page", etc: See `object
1948 numbering and object references`_ above.
1950 - "glossary-term": This would establish a link to a glossary. It
1951 would require an associated "glossary-entry" directive, whose
1952 contents could be a definition list::
1961 This would allow entries to be defined anywhere in the document,
1962 and collected (via a "glossary" directive perhaps) at one point.
1968 [DG 2017-01-02: These are not definitive to-dos, just one developer's
1969 opinion. Added 2009-10-13 by Günter Milde, in r6178.]
1970 [Updated by GM 2017-02-04]
1972 The number of doctree nodes can be reduced by "normalizing" some related
1973 nodes. This makes the document model and the writers somewhat simpler.
1975 * The "doctest" element can be replaced by literal blocks with a class
1976 attribute (similar to the "code" directive output).
1977 The syntax shall be left in reST.
1979 [DG 2017-01-02:] +0.
1982 The syntax could be left in reST (for a set period of time?).
1984 [DG 2017-01-02:] The syntax must be left in reST, practically
1985 forever. Removing it would introduce a huge backwards
1986 incompatibility. Any syntax removal must be preceded by a thorough
1987 review and planning, including a deprecation warning process. My
1988 opinion: it's not worth it.
1990 * "Normalize" special admonitions (note, hint, warning, ...) during parsing
1991 (similar to _`transforms.writer_aux.Admonitions`). There is no need to
1992 keep them as distinct elements in the doctree specification.
1994 [DG 2017-01-02:] -1: <note>{body}</> is much more concise and
1995 expressive than <admonition><title>Note</>{body}</>, and the title
1996 translation can be put off until much later in the process.
2000 -0 for <admonition class=note><title>Note</>... instead of <note>:
2001 a document is rarely printed/used as doctree or XML.
2003 +1 reduce the complexity of the doctree
2004 (there is no 1:1 rST syntax element <-> doctree node mapping anyway).
2006 +2 every writer needs 9 visit_*/depart_* method pairs to handle the 9
2007 subtypes of an admonition, i.e. we could but also remove 36 redundant
2008 methods (HTML, LaTeX, Manpage, ODF).
2010 -1 the most unfortunately named of these directives will survive. [#]_
2012 .. [#] with "biblical touch" and hard to translate:
2014 :admonition: | Ermahnung; Verweis; Warnung; Rüge
2015 | (exhortation; censure; warning; reprimand, rebuke)
2018 Keep the special admonition directives in reStructuredText syntax.
2020 [DG 2017-01-02:] We must definitely keep the syntax. Removing it
2021 would introduce a huge backwards incompatibility.
2024 Unimplemented Transforms
2025 ========================
2027 * _`Footnote & Citation Gathering`
2029 Collect and move footnotes & citations to the end of a document or the
2030 place of a "footnotes" or "citations" directive
2031 (see `<./ref/rst/directives.html>_`)
2034 Collect all footnotes that are referenced in the document before the
2035 directive (and after an eventually preceding ``.. footnotes::``
2036 directive) and insert at this place.
2038 Allows "endnotes" at a configurable place.
2041 Collect citations that are referenced ...
2045 a) defined in the document as citation elements
2047 b) auto-generated from entries in a bibliographic database.
2049 + based on bibstuff_?
2050 + also have a look at
2052 * CrossTeX_, a backwards-compatible, improved bibtex
2053 re-implementation in Python (including HTML export).
2054 (development stalled since 2 years)
2056 * Pybtex_,a drop-in replacement for BibTeX written in Python.
2058 * BibTeX styles & (experimental) pythonic style API.
2059 * Database in BibTeX, BibTeXML and YAML formats.
2060 * full Unicode support.
2061 * Write to TeX, HTML and plain text.
2063 * `Zotero plain <http://e6h.org/%7Eegh/hg/zotero-plain/>`__
2064 supports Zotero databases and CSL_ styles with Docutils with an
2067 * `sphinxcontrib-bibtex`_ Sphinx extension with "bibliography"
2068 directive and "cite" role supporting BibTeX databases.
2070 * `Modified rst2html
2071 <http://www.loria.fr/~rougier/coding/article/rst2html.py>`__ by
2075 * Automatically insert a "References" heading?
2077 .. _CrossTeX: http://www.cs.cornell.edu/people/egs/crosstex/
2078 .. _Pybtex: http://pybtex.sourceforge.net/
2079 .. _CSL: http://www.citationstyles.org/
2080 .. _sphinxcontrib-bibtex: http://sphinxcontrib-bibtex.readthedocs.org/
2082 * _`Reference Merging`
2084 When merging two or more subdocuments (such as docstrings),
2085 conflicting references may need to be resolved. There may be:
2087 * duplicate reference and/or substitution names that need to be made
2089 * duplicate footnote numbers that need to be renumbered.
2091 Should this be done before or after reference-resolving transforms
2092 are applied? What about references from within one subdocument to
2095 * _`Document Splitting`
2097 If the processed document is written to multiple files (possibly in
2098 a directory tree), it will need to be split up. Internal references
2099 will have to be adjusted.
2101 (HTML only? Initially, yes. Eventually, anything should be
2106 - Insert a "destination" attribute into the root element of each
2107 split-out document, containing the path/filename. The Output
2108 object or Writer will recognize this attribute and split out the
2109 files accordingly. Must allow for common headers & footers,
2110 prev/next, breadcrumbs, etc.
2112 - Transform a single-root document into a document containing
2113 multiple subdocuments, recursively. The content model of the
2114 "document" element would have to change to::
2117 ( (title, subtitle?)?,
2119 (docinfo, transition?)?,
2123 (I.e., add the last line -- 0 or more document elements.)
2125 Let's look at the case of hierarchical (directories and files)
2126 HTML output. Each document element containing further document
2127 elements would correspond to a directory (with an index.html file
2128 for the content preceding the subdocuments). Each document
2129 element containing no subdocuments (i.e., structure model elements
2130 only) corresponds to a concrete file with no directory.
2132 The natural transform would be to map sections to subdocuments,
2133 but possibly only a given number of levels deep.
2137 If a document is split up, each segment will need navigation links:
2138 parent, children (small TOC), previous (preorder), next (preorder).
2139 Part of `Document Splitting`_?
2141 * _`List of System Messages`
2143 The ``system_message`` elements are inserted into the document tree,
2144 adjacent to the problems themselves where possible. Some (those
2145 generated post-parse) are kept until later, in
2146 ``document.messages``, and added as a special final section,
2147 "Docutils System Messages".
2149 Docutils could be made to generate hyperlinks to all known
2150 system_messages and add them to the document, perhaps to the end of
2151 the "Docutils System Messages" section.
2153 Fred L. Drake, Jr. wrote:
2155 I'd like to propose that both parse- and transformation-time
2156 messages are included in the "Docutils System Messages" section.
2157 If there are no objections, I can make the change.
2159 The advantage of the current way of doing things is that parse-time
2160 system messages don't require a transform; they're already in the
2161 document. This is valuable for testing (unit tests,
2162 tools/quicktest.py). So if we do decide to make a change, I think
2163 the insertion of parse-time system messages ought to remain as-is
2164 and the Messages transform ought to move all parse-time system
2165 messages (remove from their originally inserted positions, insert in
2166 System Messages section).
2168 * _`Index Generation`
2174 * Make it easier to find out fragment names (#foo-bar) of ``_`inline
2175 targets```. Currently you have to either look at the source or
2178 For example, we could add support for self-referencing targets
2179 (i.e. inline targets would [unobtrusively] link to themselves, so
2180 that you can just click them and then copy the address). Or we
2181 could add support for titles that display the fragment name (as in
2182 <http://subversion.tigris.org/mailing-list-guidelines.html>; just
2183 hover the paragraphs).
2185 Either way it should be optional and deactivated by default.
2187 This would be useful for documents like Docutils' bug list or to-do
2190 * Make the _`list compacting` logic more generic: For example, allow
2191 for literal blocks or line blocks inside of compact list items.
2193 This is not implementable as long as list compacting is done by
2194 omitting ``<p>`` tags. List compacting would need to be done by
2195 adjusting CSS margins instead.
2197 :2015-04-02: The new html writer no longer strips <p> tags but adds the
2198 class value ``simple`` to the list.
2199 Formatting is done by CSS --- configurable by a custom style
2202 Auto-compactization can be overridden by the ``open`` vs.
2203 ``compact`` class arguments.
2205 * Idea for field-list rendering: hanging indent::
2207 Field name (bold): First paragraph of field body begins
2208 with the field name inline.
2210 If the first item of a field body is not a paragraph,
2211 it would begin on the following line.
2213 :2015-04-02: The new html writer writes field-lists as definition lists
2214 with class ``field-list``.
2215 Formatting is done by CSS --- configurable by a custom style
2216 sheet. The default style sheet has some examples, including a
2217 run-in field-list style.
2219 * Add more support for <link> elements, especially for navigation
2222 The framework does not have a notion of document relationships, so
2223 probably raw.destination_ should be used.
2225 We'll have framework support for document relationships when support
2226 for `multiple output files`_ is added. The HTML writer could
2227 automatically generate <link> elements then.
2229 .. _raw.destination: misc.raw_
2231 * Base list compaction on the spacing of source list? Would require
2232 parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
2234 * Add a tool tip ("title" attribute?) to footnote back-links
2235 identifying them as such. Text in Docutils language module.
2241 * Remove the generic style information (duplicated from html4css1.css)
2242 from pep.css to avoid redundancy.
2244 Set ``stylesheet-path`` to "html4css.css,pep.css" and the
2245 ``stylesheet-dirs`` accordingly instead. (See the xhtml11 writer for an
2252 * Add a way to begin an untitled slide.
2254 * Add a way to begin a new slide, continuation, using the same title
2255 as the previous slide? (Unnecessary?) You need that if you have a
2256 lot of items in one section which don't fit on one slide.
2258 Maybe either this item or the previous one can be realized using
2261 * Have a timeout on incremental items, so the colour goes away after 1
2264 * Add an empty, black last slide (optionally). Currently the handling
2265 of the last slide is not very nice, it re-cycles through the
2266 incremental items on the last slide if you hit space-bar after the
2269 * Add a command-line option to disable advance-on-click.
2271 * Add a speaker's master document, which would contain a small version
2272 of the slide text with speaker's notes interspersed. The master
2273 document could use ``target="whatever"`` to direct links to a
2274 separate window on a second monitor (e.g., a projector).
2276 .. Note:: This item and the following items are partially
2277 accomplished by the S5 1.2 code (currently in alpha), which has
2278 not yet been integrated into Docutils.
2280 * Speaker's notes -- how to intersperse? Could use reST comments
2281 (".."), but make them visible in the speaker's master document. If
2282 structure is necessary, we could use a "comment" directive (to avoid
2283 nonsensical DTD changes, the "comment" directive could produce an
2284 untitled topic element).
2286 The speaker's notes could (should?) be separate from S5's handout
2289 * The speaker's master document could use frames for easy navigation:
2290 TOC on the left, content on the right.
2292 - It would be nice if clicking in the TOC frame simultaneously
2293 linked to both the speaker's notes frame and to the slide window,
2294 synchronizing both. Needs JavaScript?
2296 - TOC would have to be tightly formatted -- minimal indentation.
2298 - TOC auto-generated, as in the PEP Reader. (What if there already
2299 is a "contents" directive in the document?)
2301 - There could be another frame on the left (top-left or bottom-left)
2302 containing a single "Next" link, always pointing to the next slide
2303 (synchronized, of course). Also "Previous" link? FF/Rew go to
2304 the beginning of the next/current parent section? First/Last
2305 also? Tape-player-style buttons like ``|<< << < > >> >>|``?
2310 Add epub as an output format.
2312 epub is an open file format for ebooks based on HTML, specified by the
2313 `International Digital Publishing Forum`_. Thus, documents in epub
2314 format are suited to be read with `electronic reading devices`_.
2316 Pack the output of a HTML writer and supporting files (e.g. images)
2317 into one single epub document.
2319 There are `links to two 3rd party ePub writers`__ in the Docutils link list.
2320 Test and consider moving the better one into the docutils core.
2322 __ ../user/links.html#ePub
2323 .. _International Digital Publishing Forum: http://www.idpf.org/
2324 .. _electronic reading devices:
2325 http://en.wikipedia.org/wiki/List_of_e-book_readers
2331 Also see the Problems__ section in the `latex writer documentation`_.
2333 __ ../user/latex.html#problems
2335 .. _latex writer documentation: ../user/latex.html
2338 ../../../sandbox/latex-variants/README.html
2343 * Too deeply nested lists fail: generate a warning and provide
2346 2017-02-09 this is fixed for enumeration in 0.13.1
2348 for others, cf. sandbox/latex-variants/tests/rst-levels.txt
2350 * File names of included graphics (see also `grffile` package).
2352 Generate clean and configurable LaTeX source
2353 ----------------------------------------------
2355 * Check the generated source with package `nag`.
2357 Configurable placement of figure and table floats
2358 `````````````````````````````````````````````````
2360 * Special class argument to individually place figures?
2364 placement-<optional arg> -> \figure[<optional arg>]{...}
2366 e.g. ``.. class:: placement-htb``,
2371 :h: place-here-if-possible
2374 :p: place-on-extra-page
2376 e.g.: ``.. class:: place-here-if-possible place-top place-bottom``
2378 Maybe support both variants?
2381 LaTeX constructs and packages instead of re-implementations
2382 ```````````````````````````````````````````````````````````
2384 Which packages do we want to use?
2386 + base and "recommended" packages
2388 (packages that should be in a "reasonably sized and reasonably modern
2389 LaTeX installation like the `texlive-latex-recommended` Debian package,
2392 + No "fancy" or "exotic" requirements.
2394 + pointers to advanced packages and their use in the `latex writer
2399 + True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
2400 (also for target-footnotes):
2402 - attach footnote text to footnote-symobol node
2403 - write \footnote{<footnote text>}
2404 - consider cases where LaTeX does not support footnotes
2405 (inside tables, headings, ...)?
2406 - consider multiple footnote refs to common footnote text.
2410 If the symbol you want is not one of the ones listed, you'll need to
2411 redefine ``\@fnsymbol`` and add it, e.g. perhaps like::
2413 \def\@fnsymbol#1{\ifcase#1\hbox{}\or *\or \dagger\or \ddagger\or
2414 \mathchar "278\or \mathchar "27B\or \|\or **\or \dagger\dagger \or
2415 \ddagger\ddagger \or \mathchar"27C \else\@ctrerr\fi\relax}
2417 which would allow \symbolfootnote[10]{footnote} to have a club as its
2420 + document customization (links to how-to and packages):
2422 .. Footnote packages:
2424 :footnote: texlive-latex-recommended % savenotes environment
2425 :footmisc: texlive-latex-extra % formatting options
2426 :manyfoot: texlive-latex-extra
2427 :bigfoot: texlive-latex-extra
2428 :perpage: texlive-latex-extra
2429 :ftnxtra: new on CTAN
2430 fixes the issue of footnote inside \caption{},
2431 tabular environment and \section{} like commands.
2435 http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf
2439 `Footnotes whose texts are identical
2440 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=repfootnote>`__
2442 * label per hand or use footmisc
2444 `More than one sequence of footnotes
2445 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot>`__
2449 `Footnotes in tables
2450 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab>`__
2452 * `tabularx` and longtable allow footnotes.
2453 * `footnote` provides a "savenotes" environment which collects all
2454 footnotes and emits them at ``end{savenotes}``
2456 `Footnotes in LaTeX section headings
2457 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect>`__
2459 * Take advantage of the fact that the mandatory argument doesn't
2460 move if the optional argument is present::
2462 \section[title] {title\footnote{title ftnt}}
2464 * Use the footmisc package, with package option stable - this modifies
2465 footnotes so that they softly and silently vanish away if used in a
2470 `Footnotes numbered per page
2471 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footnpp>`__
2473 * perpage provides a general mechanism for resetting counters per page
2474 * footmisc provides a package option perpage
2476 * use `eqlist` or `enumitem` (texlive-latex-extra) for field-lists?
2478 * ``--use-latex-when-possible`` »super option« that would set the
2481 --no-section-numbering
2484 --use-latex-abstract
2485 --use-latex-footnotes
2486 --use-latex-citations
2488 ? (My preference is to default to use-latex-* whenever possible [GM])
2494 * Use italic instead of slanted for titlereference?
2496 * Start a new paragraph after lists (as currently)
2497 or continue (no blank line in source, no parindent in output)?
2501 * continue if the `compound paragraph`_ directive is used, or
2502 * force a new paragraph with an empty comment.
2504 * Sidebar handling (environment with `framed`, `marginnote`, `wrapfig`,
2507 * Use optionlist for docinfo?
2509 * Keep literal-blocks together on a page, avoid pagebreaks.
2511 Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
2514 Should be possible with ``--literal-block-env==lstlistings`` and some
2517 * More space between title and subtitle? ::
2520 + \\[0.5em] % subtitle%
2522 .. _PSNFSS documentation:
2523 http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
2524 .. _compound paragraph:
2525 ../ref/rst/directives.html#compound-paragraph
2527 http://mirror.ctan.org/help/Catalogue/entries/fixltx2e.html
2532 * Improve/simplify logic to set the column width in the output.
2534 + Assumed reST line length for table width setting configurable, or
2535 + use `ltxtable` (a combination of `tabularx` (auto-width) and
2536 `longtable` (page breaks)), or
2537 + use tabularx column type ``X`` and let LaTeX decide width, or
2541 http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=tabulary
2543 * From comp.text.tex (13. 4. 2011):
2545 When using fixed width columns, you should ensure that the total
2546 width does not exceed \linewidth: if the first column is p{6cm}
2547 the second one should be p{\dimexpr\linewidth-6cm-4\tabcolsep}
2548 because the glue \tabcolsep is added twice at every column edge.
2549 You may also consider to set \tabcolsep to a different value...
2551 * csv-tables do not have a colwidth.
2553 * Add more classes or options, e.g. for
2555 + column width set by latex,
2556 + horizontal alignment and rules.
2557 + long table vs. tabular (see next item).
2559 * Use tabular instead of longtable for tables in legends or generally
2562 Alternatively, default to tabular and use longtable only if specified
2563 by config setting or class argument (analogue to booktable)?
2565 * Table heads and footer for longtable (firstpage lastpage ..)?
2567 * In tools.txt the option tables right column, there should be some more
2568 spacing between the description and the next paragraph "Default:".
2570 * Paragraph separation in tables is hairy.
2571 see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
2573 - The strut solution did not work.
2574 - setting extrarowheight added ad top of row not between paragraphs in
2575 a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
2576 - baselineskip/stretch does not help.
2578 * Should there be two hlines after table head and on table end?
2580 * Place titled tables in a float ('table' environment)?
2582 The 'table', 'csv-table', and 'list-table' directives support an (optional)
2583 table title. In analogy to the 'figure' directive this should map to a
2586 Image and figure directives
2587 ```````````````````````````
2589 * compare the test case in:
2591 + `<../../test/functional/input/data/standard.txt>`__
2592 + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
2593 + `<../../test/functional/expected/standalone_rst_latex.tex>`__
2595 * The default CSS styling for HTML output (plain.css, default.css) lets
2596 text following a right- or left-aligned image float to the side of the
2599 + Use this default also for LaTeX?
2601 + Wrap text around figures/images with class argument "wrap"
2602 (like the odt writer)?
2604 Use `wrapfig` (or other recommended) package.
2606 * support more graphic formats (especially SVG, the only standard
2607 vector format for HTML)
2609 There is a `SWF package`_ at CTAN.
2612 http://mirror.ctan.org/macros/latex/contrib/flashmovie
2618 * support "figwidth" argument for figures.
2620 As the 'figwidth' argument is still ignored and the "natural width" of
2621 a figure in LaTeX is 100 % of the text width, setting the 'align'
2622 argument has currently no effect on the LaTeX output.
2625 * Let `meta` directive insert PDF-keywords into header?
2627 * Multiple author entries in docinfo (same thing as in html).
2630 * Consider supporting the "compact" option and class argument (from
2631 rst2html) as some lists look better compact and others need the space.
2633 * Better citation support
2634 (see `Footnote & Citation Gathering`_).
2636 * If ``use-latex-citations`` is used, a bibliography is inserted right at the
2637 end of the document.
2639 Put in place of the to-be-implemented "citations" directive
2640 (see `Footnote & Citation Gathering`_).
2646 The `LyX <http://www.lyx.org>`_ document processor has a comprehensive
2647 Unicode to LaTeX conversion feature with a file called ``unicodesymbols``
2648 that lists LaTeX counterparts for a wide range of Unicode characters.
2650 * Use this in the LaTeXTranslator?
2651 Think of copyright issues!
2653 * The "ucs" package has many translations in ...doc/latex/ucs/config/
2655 * The bibstuff_ tool ships a `latex_codec` Python module!
2657 .. _bibstuff: http://code.google.com/p/bibstuff/
2659 Allow choice between utf8 (standard) and utf8x (extended) encodings
2660 ```````````````````````````````````````````````````````````````````
2662 * Allow the user to select *utf8* or *utf8x* LaTeX encoding. (Docutil's
2663 output encoding becomes LaTeX's input encoding.)
2665 The `ucs` package provides extended support for UTF-8 encoding in LaTeX
2666 via the `inputenc`-option ``utf8x``. It is, however, a non-standard
2667 extension and no longer developed.
2670 a) Python has 4 names for the UTF-8 encoding (``utf_8, U8, UTF, utf8``)
2671 give a special meaning to one of the aliases,
2673 b) scan "stylesheets" and "latex-preamble" options and use ``utf8x``
2674 if it contains ``ucs``
2679 * Glyphs missing in the font are left out in the PDF without warning
2680 (e.g. ⇔ left-right double arrow in the functional test output).
2682 * Disable word-wrap (hyphenation) in literal text locally with
2683 ``providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}``?
2689 * ^^ LaTeX's special syntax for characters results in "strange" replacements
2690 (both with \href and \url).
2692 `file with ^^ <../strange^^name>`__:
2693 `<../strange^^name>`__
2695 * Unbalanced braces, { or }, will fail (both with \href and \url)::
2697 `file with { <../strange{name>`__
2698 `<../strange{name>`__
2700 Currently, a warning is written to the error output stream.
2702 For correct printing, we can
2704 * use the \href command with "normal" escaped name argument, or
2705 * define a url-command in the preamble ::
2707 \urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
2709 but need to find a way to insert it as href argument.
2711 The following fails::
2713 \href{http://www.w3.org/XML/Schema^^dev}{\fragileURLi}
2715 Use %-replacement like http://nowhere/url_with%28parens%29 ?
2717 -> does not work for file paths (with pdflatex and xpdf).
2720 add-stylesheet option
2721 `````````````````````
2723 From http://article.gmane.org/gmane.text.docutils.devel/3429/
2725 The problem is that since we have a default value, we have to
2726 differentiate between adding another stylesheet and replacing the
2727 default. I suggest that the existing --stylesheet & --stylesheet-path
2728 options keep their semantics to replace the existing settings. We
2729 could introduce new --add-stylesheet & --add-stylesheet-path options,
2730 which accumulate; further --stylesheet/--stylesheet-path options would
2731 clear these lists. The stylesheet or stylesheet_path setting (only
2732 one may be set), plus the added_stylesheets and added_stylesheet_paths
2733 settings, describe the combined styles.
2735 For example, this run will have only one custom stylesheet:
2737 rstpep2html.py --stylesheet-path custom.css ...
2739 This run will use the default stylesheet, and the custom one:
2741 rstpep2html.py --add-stylesheet-path custom.css ...
2743 This run will use the default stylesheet, a custom local stylesheet,
2744 and an external stylesheet:
2746 rstpep2html.py --add-stylesheet-path custom.css \
2747 --add-stylesheet http://www.example.org/external.css ...
2749 This run will use only the second custom stylesheet:
2751 rstpep2html.py --add-stylesheet-path custom.css \
2752 --stylesheet-path second.css ...
2760 * What about if we don't know which Reader and/or Writer we are
2761 going to use? If the Reader/Writer is specified on the
2762 command-line? (Will this ever happen?)
2764 Perhaps have different types of front ends:
2766 a) _`Fully qualified`: Reader and Writer are hard-coded into the
2767 front end (e.g. ``pep2html [options]``, ``pysource2pdf
2770 b) _`Partially qualified`: Reader is hard-coded, and the Writer is
2771 specified a sub-command (e.g. ``pep2 html [options]``,
2772 ``pysource2 pdf [options]``). The Writer is known before option
2773 processing happens, allowing the OptionParser to be built
2774 dynamically. Alternatively, the Writer could be hard-coded and
2775 the Reader specified as a sub-command (e.g. ``htmlfrom pep
2778 c) _`Unqualified`: Reader and Writer are specified as subcommands
2779 (e.g. ``publish pep html [options]``, ``publish pysource pdf
2780 [options]``). A single front end would be sufficient, but
2781 probably only useful for testing purposes.
2783 d) _`Dynamic`: Reader and/or Writer are specified by options, with
2784 defaults if unspecified (e.g. ``publish --writer pdf
2785 [options]``). Is this possible? The option parser would have
2786 to be told about new options it needs to handle, on the fly.
2787 Component-specific options would have to be specified *after*
2788 the component-specifying option.
2790 Allow common options before subcommands, as in CVS? Or group all
2791 options together? In the case of the `fully qualified`_
2792 front ends, all the options will have to be grouped together
2793 anyway, so there's no advantage (we can't use it to avoid
2794 conflicts) to splitting common and component-specific options
2797 * Parameterize help text & defaults somehow? Perhaps a callback? Or
2798 initialize ``settings_spec`` in ``__init__`` or ``init_options``?
2800 * Disable common options that don't apply?
2801 (This should now be easier with ``frontend.filter_settings_spec``.)
2803 * Add ``--section-numbering`` command line option. The "sectnum"
2804 directive should override the ``--no-section-numbering`` command
2807 * Create a single dynamic_ or unqualified_ front end that can be
2814 indent-tabs-mode: nil
2815 sentence-end-double-space: t