5 :Author: David Goodger (with input from many); open to all Docutils
7 :Contact: goodger@python.org
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 * Encoding of command line arguments can only be guessed:
76 * try UTF-8/strict first, then try the locale's encoding with
77 strict error handling, then ASCII/replace?
79 UTF-8 is almost 100% safe to try first; false positives are rare,
80 The locale's encoding with strict error handling may be a
81 reasonable compromise, but any error would indicate that the
82 locale's encoding is inappropriate. The only safe fallback is
85 * Do not decode argv before option parsing but individual string
88 +1 Allows for separate command-line vs. filesystem encodings,
89 respectively to keep file names encoded.
90 +1 Allows to configure command-line encoding in a config file,
93 Cf. <http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957>.
95 * Improve handling on Windows:
97 - Get graphical installer.
98 - Make rst2html.py an .exe file using py2exe.
102 The user interface is very difficult to use for most Windows users;
103 you can't really expect them to use the command line. We need some
104 kind of GUI that can launch rst2html.py, and save the HTML output to
105 a file, and launch a browser. What's important is that we get
106 settings to work with the GUI. So we need some way to dynamically
107 generate a list of settings for the GUI. The current settings_spec
108 for OptionParser doesn't seem to be usable for this for the
111 - It's biased toward the command line -- there are *two* options for
114 - You cannot have both a one-line description and a longer
115 description for tooltips/help-texts.
117 - It doesn't provide hints for the input type. You cannot easily
118 infer the type of a setting from its validator, because any
119 component can add new validators. In fact, it may be necessary to
120 have both a hint about the input type (e.g. string) and a
121 validator (valid ID), or it may be necessary to have a different
122 set of choices for the CLI (1, INFO, 2, ...) and for the GUI
123 (INFO, WARNING, ...).
125 - It's coupled to the OptionParser. We want to be able to change
126 the underlying system without breaking everything.
128 - It's a bunch of primitive structures. We want an extensible (thus
129 object-oriented) interface.
131 So we probably need to create a class for storing all the settings,
132 and auto-generate the OptionParser data from that.
134 I talked to Stephan Deibel about getting Docutils integrated into
135 Wing IDE. He said it's possible, and he'd be willing to help.
136 There's a scripting interface to Wing, which we'd use. We can
137 dynamically generate a list of preferences and not worry too much
138 about the rendering (from what I understood); Wing's whole GUI is
139 dynamic anyway. The interface could be made usable for other GUIs.
140 For example, we could try to get option support for DocFactory. //
143 * Allow different report levels for STDERR and system_messages inside
146 * Change the docutils-update script (in sandbox/infrastructure), to
147 support arbitrary branch snapshots.
149 * Move some general-interest sandboxes out of individuals'
150 directories, into subprojects?
152 * Add option for file (and URL) access restriction to make Docutils
153 usable in Wikis and similar applications.
155 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
156 settings. These partially solve the problem, allowing or disabling
157 **all** file accesses, but not limited access.
159 * Configuration file handling needs discussion:
161 - There should be some error checking on the contents of config
162 files. How much checking should be done? How loudly should
163 Docutils complain if it encounters an error/problem?
165 - Docutils doesn't complain when it doesn't find a configuration
166 file supplied with the ``--config`` option. Should it? (If yes,
169 * Internationalization:
171 - I18n needs refactoring, the language dictionaries are difficult to
172 maintain. Maybe have a look at gettext or similar tools.
174 (This would make a nice Google Summer of Code project)
176 - Language modules: in accented languages it may be useful to have
177 both accented and unaccented entries in the
178 ``bibliographic_fields`` mapping for versatility.
180 - Add a "--strict-language" option & setting: no English fallback
181 for language-dependent features.
183 Make this the default for output (as opposed to input)?
184 Throw an error with a helpfull message, e.g.
186 Default "contents" title for language %s missing, please specify
191 "attention" title for language %s missing, please use a generic
192 admonition with explicit title.
194 - Add internationalization to _`footer boilerplate text` (resulting
195 from "--generator", "--source-link", and "--date" etc.), allowing
199 * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
201 * In ``docutils.readers.get_reader_class`` (& ``parsers`` &
202 ``writers`` too), should we be importing "standalone" or
203 "docutils.readers.standalone"? (This would avoid importing
204 top-level modules if the module name is not in docutils/readers.
205 Potential nastiness.)
207 * Perhaps store a _`name-to-id mapping file`? This could be stored
208 permanently, read by subsequent processing runs, and updated with
209 new entries. ("Persistent ID mapping"?)
211 * Perhaps the ``Component.supports`` method should deal with
212 individual features ("meta" etc.) instead of formats ("html" etc.)?
214 * Think about _`large documents` made up of multiple subdocument
215 files. Issues: continuity (`persistent sequences`_ above),
216 cross-references (`name-to-id mapping file`_ above and `targets in
217 other documents`_ below), splitting (`document splitting`_ below).
219 When writing a book, the author probably wants to split it up into
220 files, perhaps one per chapter (but perhaps even more detailed).
221 However, we'd like to be able to have references from one chapter to
222 another, and have continuous numbering (pages and chapters, as
223 applicable). Of course, none of this is implemented yet. There has
224 been some thought put into some aspects; see `the "include"
225 directive`__ and the `Reference Merging`_ transform below.
227 When I was working with SGML in Japan, we had a system where there
228 was a top-level coordinating file, book.sgml, which contained the
229 top-level structure of a book: the <book> element, containing the
230 book <title> and empty component elements (<preface>, <chapter>,
231 <appendix>, etc.), each with filename attributes pointing to the
232 actual source for the component. Something like this::
235 <title>Title of the Book</title>
236 <preface inrefid="pr01"></preface>
237 <chapter inrefid="ch01"></chapter>
238 <chapter inrefid="ch02"></chapter>
239 <chapter inrefid="ch03"></chapter>
240 <appendix inrefid="ap01"></appendix>
243 (The "inrefid" attribute stood for "insertion reference ID".)
245 The processing system would process each component separately, but
246 it would recognize and use the book file to coordinate chapter and
247 page numbering, and keep a persistent ID to (title, page number)
248 mapping database for cross-references. Docutils could use a similar
249 system for large-scale, multipart documents.
251 __ ../ref/rst/directives.html#including-an-external-document-fragment
267 As I said earlier in chapter :chapter:`Objects.txt`, the
268 reference count gets increased every time a binding is made.
272 As I said earlier in chapter 2, the
273 reference count gets increased every time a binding is made.
275 The ToC in this form doesn't even need to be references to actual
276 reST documents; I'm simply doing it that way for a minimum of
277 future-proofing, in case I do want to add the ability to pick up
278 references within external chapters.
280 Perhaps, instead of ToC (which would overload the "contents"
281 directive concept already in use), we could use "manifest". A
282 "manifest" directive might associate local reference names with
286 intro: Introduction.txt
291 Then the sample becomes::
293 .. include:: manifest.txt
295 As I said earlier in chapter :chapter:`objects`, the
296 reference count gets increased every time a binding is made.
298 * Add support for _`multiple output files` and _`generic data
301 It should be possible for a component to **emit or reference** data
302 to be either **included or referenced** in the output document.
303 Examples of such data are stylesheets or images.
305 For this, we need a "data" object which stores the data either
306 inline or by referring to a file. The Docutils framework is
307 responsible for either:
309 * storing the data in the appropriate location (e.g. in the
310 directory of the output file, or in a user-specified directory)
311 and providing the paths of the stored files to the writer, *or*
313 * providing the data itself to the writer so that it can be embedded
314 in the output document.
316 This approach decouples data handling from the data source (which
317 can either be embedded or referenced) and the destination (which can
318 either be embedded or referenced as well).
320 See <http://article.gmane.org/gmane.text.docutils.devel/3631>.
322 * Add testing for Docutils' front end tools?
324 * Publisher: "Ordinary setup" shouldn't requre specific ordering; at
325 the very least, there ought to be error checking higher up in the
328 ``Publisher.get_settings`` requires that all components be set up
329 before it's called. Perhaps the I/O *objects* shouldn't be set, but
330 I/O *classes*. Then options are set up (``.set_options``), and
331 ``Publisher.set_io`` (or equivalent code) is called with source &
332 destination paths, creating the I/O objects.
334 Perhaps I/O objects shouldn't be instantiated until required. For
335 split output, the Writer may be called multiple times, once for each
336 doctree, and each doctree should have a separate Output object (with
337 a different path). Is the "Builder" pattern applicable here?
339 * Perhaps I/O objects should become full-fledged components (i.e.
340 subclasses of ``docutils.Component``, as are Readers, Parsers, and
341 Writers now), and thus have associated option/setting specs and
344 * Multiple file I/O suggestion from Michael Hudson: use a file-like
345 object or something you can iterate over to get file-like objects.
347 * Add an "--input-language" option & setting? Specify a different
348 language module for input (bibliographic fields, directives) than
349 for output. The "--language" option would set both input & output
352 * Auto-generate reference tables for language-dependent features?
353 Could be generated from the source modules. A special command-line
354 option could be added to Docutils front ends to do this. (Idea from
357 * Enable feedback of some kind from internal decisions, such as
358 reporting the successful input encoding. Modify runtime settings?
359 System message? Simple stderr output?
361 * Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
363 * Merge docs/user/latex.txt info into tools.txt and config.txt?
365 * Add an "--include file" command-line option (config setting too?),
366 equivalent to ".. include:: file" as the first line of the doc text?
367 Especially useful for character entity sets, text transform specs,
370 * Parameterize the Reporter object or class? See the `2004-02-18
371 "rest checking and source path"`_ thread.
373 .. _2004-02-18 "rest checking and source path":
374 http://thread.gmane.org/gmane.text.docutils.user/1112
376 * Add a "disable_transforms" setting? And a dummy Writer subclass
377 that does nothing when its .write() method is called? Would allow
378 for easy syntax checking. See the `2004-02-18 "rest checking and
379 source path"`_ thread.
381 * Add a generic meta-stylesheet mechanism? An external file could
382 associate style names ("class" attributes) with specific elements.
383 Could be generalized to arbitrary output attributes; useful for HTML
384 & XMLs. Aahz implemented something like this in
385 sandbox/aahz/Effective/EffMap.py.
387 * .. _classes for table cells:
389 William Dode suggested that table cells be assigned "class"
390 attributes by columns, so that stylesheets can affect text
391 alignment. Unfortunately, there doesn't seem to be a way (in HTML
392 at least) to leverage the "colspec" elements (HTML "col" tags) by
393 adding classes to them. The resulting HTML is very verbose::
395 <td class="col1">111</td>
396 <td class="col2">222</td>
399 At the very least, it should be an option. People who don't use it
400 shouldn't be penalized by increases in their HTML file sizes.
402 Table rows could also be assigned classes (like odd/even). That
403 would be easier to implement.
405 How should it be implemented?
407 * There could be writer options (column classes & row classes) with
410 * The table directive could grow some options. Something like
411 ":cell-classes: col1 col2 col3" (either must match the number of
412 columns, or repeat to fill?) and ":row-classes: odd even" (repeat
413 to fill; body rows only, or header rows too?).
415 Probably per-table directive options are best. The "class" values
416 could be used by any writer, and applying such classes to all tables
417 in a document with writer options is too broad.
419 * Add file-specific settings support to config files, like::
424 Is this even possible? Should the criterion be the name of the
425 input file or the output file? Alternative (more explicit) syntax::
427 [source_file index.txt]
430 [dest_file index.html]
433 Or rather allow settings configuration from the rst source file?
435 * The "validator" support added to OptionParser is very similar to
436 "traits_" in SciPy_. Perhaps something could be done with them?
437 (Had I known about traits when I was implementing docutils.frontend,
438 I may have used them instead of rolling my own.)
440 .. _traits: http://code.enthought.com/traits/
441 .. _SciPy: http://www.scipy.org/
443 * tools/buildhtml.py: Extend the --prune option ("prune" config
444 setting) to accept file names (generic path) in addition to
445 directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
446 *not* be converted to HTML).
448 * Add support for _`plugins`.
450 * _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
451 /etc/docutils.conf are read as configuration files. Proposal: allow
452 ~/.docutils to be a a configuration *directory*, along with
453 /etc/docutils/ and ./docutils.conf/. Within these directories,
454 check for config.txt files. We can also have subdirectories here,
455 for plugins, S5 themes, components (readers/writers/parsers) etc.
457 Docutils will continue to support configuration files for backwards
460 * Add support for document decorations other than headers & footers?
461 For example, top/bottom/side navigation bars for web pages. Generic
464 Seems like a bad idea as long as it isn't independent from the ouput
465 format (for example, navigation bars are only useful for web pages).
467 * docutils_update: Check for a ``Makefile`` in a directory, and run
468 ``make`` if found? This would allow for variant processing on
469 specific source files, such as running rst2s5.py instead of
472 * Add a "disable table of contents" setting? The S5 writer could set
473 it as a default. Rationale:
475 The ``contents`` (table of contents) directive must not be used
476 [in S5/HTML documents]. It changes the CSS class of headings
477 and they won't show up correctly in the screen presentation.
479 -- `Easy Slide Shows With reStructuredText & S5
480 <../user/slide-shows.html>`_
482 Analogue to the ``sectnum_xform`` setting, it could be used by the
483 latex writer to switch to a LaTeX generated ToC (currently, the latex
484 writer calls it "use_latex_toc").
486 object numbering and object references
487 --------------------------------------
489 For equations, tables & figures.
491 These would be the equivalent of DocBook's "formal" elements.
493 In LaTeX, automatic counters are implemented for sections, equations and
494 floats (figures, tables) (configurable via stylesheets or in the
495 latex-preamble). Objects can be given `reference names`_ with the
496 ``\label{<refname}`` command, ``\ref{<refname>}`` inserts the
497 corresponding number.
499 No such mechanism exists in HTML.
501 * We need _`persistent sequences`, similar to chapter and footnote
502 numbers. See `OpenOffice.org XML`_ "fields".
504 - Should the sequences be automatic or manual (user-specifyable)?
506 * It is already possible to give `reference names`_ to objects via
507 internal hyperlink targets or the "name" directive option::
511 .. figure:: image.png
515 .. figure:: image.png
518 Improve the mapping of "phrase references" to IDs/labels with
519 Literal transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just
520 stripping the accents and other non-ASCII chars.
521 Use http://pypi.python.org/pypi/Unidecode?
523 A "table" directive has been implemented, supporting table titles.
525 Perhaps the name could derive from the title/caption?
527 .. _reference names: ../ref/rst/restructuredtext.html#reference-names
529 * We need syntax for object references. Cf. `OpenOffice.org XML`_
532 - Parameterized substitutions are too complicated
533 (cf. `or not to do`: `object references`_)
535 - An interpreted text approach is simpler and better::
537 See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
539 - "equation", "figure", and "page" roles could generate appropriate
542 See :figure:`figure name` on :page:`figure name`.
544 See `Interpreted Text`_ below.
546 Reference boilerplate could be specified in the document
547 (defaulting to nothing)::
550 :prefix-ref: "Figure "
551 :prefix-caption: "Fig. "
554 The position of the role (prefix or suffix) could also be utilized
556 .. _OpenOffice.org XML: http://xml.openoffice.org/
557 .. _object references: rst/alternatives.html#object-references
566 * Add a FAQ entry about using Docutils (with reStructuredText) on a
567 server and that it's terribly slow. See the first paragraphs in
568 <http://article.gmane.org/gmane.text.docutils.user/1584>.
570 * Add document about what Docutils has previously been used for
571 (web/use-cases.txt?).
573 * Improve index in docs/user/config.txt.
579 * Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
581 * Improve the internal module documentation (docstrings in the code).
582 Specific deficiencies listed below.
584 - docutils.parsers.rst.states.State.build_table: data structure
585 required (including StringList).
587 - docutils.parsers.rst.states: more complete documentation of parser
590 * docs/ref/doctree.txt: DTD element structural relationships,
591 semantics, and attributes. In progress; element descriptions to be
594 * Document the ``pending`` elements, how they're generated and what
597 * Document the transforms (perhaps in docstrings?): how they're used,
598 what they do, dependencies & order considerations.
600 * Document the HTML classes used by html4css1.py.
602 * Write an overview of the Docutils architecture, as an introduction
603 for developers. What connects to what, why, and how. Either update
604 PEP 258 (see PEPs_ below) or as a separate doc.
606 * Give information about unit tests. Maybe as a howto?
608 * Document the docutils.nodes APIs.
610 * Complete the docs/api/publisher.txt docs.
616 * Creating Docutils Writers
618 * Creating Docutils Readers
620 * Creating Docutils Transforms
622 * Creating Docutils Parsers
624 * Using Docutils as a Library
630 * Complete PEP 258 Docutils Design Specification.
632 - Fill in the blanks in API details.
634 - Specify the nodes.py internal data structure implementation?
636 [Tibs:] Eventually we need to have direct documentation in
637 there on how it all hangs together - the DTD is not enough
638 (indeed, is it still meant to be correct? [Yes, it is.
641 * Rework PEP 257, separating style from spec from tools, wrt Docutils?
642 See Doc-SIG from 2001-06-19/20.
650 * Analyze Tony Ibbs' PySource code.
652 * Analyze Doug Hellmann's HappyDoc project.
654 * Investigate how POD handles literate programming.
656 * Take the best ideas and integrate them into Docutils.
660 * Ask Python-dev for opinions (GvR for a pronouncement) on special
661 variables (__author__, __version__, etc.): convenience vs. namespace
662 pollution. Ask opinions on whether or not Docutils should recognize
665 * If we can detect that a comment block begins with ``##``, a la
666 JavaDoc, it might be useful to indicate interspersed section headers
667 & explanatory text in a module. For example::
669 """Module docstring."""
682 class MyException(Exception): pass
686 * Should standalone strings also become (module/class) docstrings?
687 Under what conditions? We want to prevent arbitrary strings from
688 becomming docstrings of prior attribute assignments etc. Assume
689 that there must be no blank lines between attributes and attribute
690 docstrings? (Use lineno of NEWLINE token.)
692 Triple-quotes are sometimes used for multi-line comments (such as
693 commenting out blocks of code). How to reconcile?
695 * HappyDoc's idea of using comment blocks when there's no docstring
696 may be useful to get around the conflict between `additional
697 docstrings`_ and ``from __future__ import`` for module docstrings.
698 A module could begin like this::
700 #!/usr/bin/env python
702 # :Copyright: whatever
704 """This is the public module docstring (``__doc__``)."""
706 # More docs, in comments.
707 # All comments at the beginning of a module could be
708 # accumulated as docstrings.
709 # We can't have another docstring here, because of the
710 # ``__future__`` statement.
712 from __future__ import division
714 Using the JavaDoc convention of a doc-comment block beginning with
715 ``##`` is useful though. It allows doc-comments and implementation
718 .. _additional docstrings:
719 ../peps/pep-0258.html#additional-docstrings
721 * HappyDoc uses an initial comment block to set "parser configuration
722 values". Do the same thing for Docutils, to set runtime settings on
723 a per-module basis? I.e.::
725 # Docutils:setting=value
727 Could be used to turn on/off function parameter comment recognition
728 & other marginal features. Could be used as a general mechanism to
729 augment config files and command-line options (but which takes
732 * Multi-file output should be divisible at arbitrary level.
734 * Support all forms of ``import`` statements:
736 - ``import module``: listed as "module"
737 - ``import module as alias``: "alias (module)"
738 - ``from module import identifier``: "identifier (from module)"
739 - ``from module import identifier as alias``: "alias (identifier
741 - ``from module import *``: "all identifiers (``*``) from module"
743 * Have links to colorized Python source files from API docs? And
744 vice-versa: backlinks from the colorized source files to the API
747 * In summaries, use the first *sentence* of a docstring if the first
748 line is not followed by a blank line.
751 reStructuredText Parser
752 =======================
754 Also see the `... Or Not To Do?`__ list.
756 __ rst/alternatives.html#or-not-to-do
761 * Allow embedded references and not only embedded URIs: ```link text
762 <reference_>`_``; see the second half of
763 <http://article.gmane.org/gmane.text.docutils.devel/3738>.
765 * Another list problem::
771 This ends up as a definition list. This is more of a usability
774 * This case is probably meant to be a nested list, but it ends up as a
775 list inside a block-quote without an error message::
781 It should probably just be an error.
783 The problem with this is that you don't notice easily in HTML that
784 it's not a nested list but a block-quote -- there's not much of a
787 * Treat enumerated lists that are not arabic and consist of only one
788 item in a single line as ordinary paragraphs. See
789 <http://article.gmane.org/gmane.text.docutils.user/2635>.
791 * The citation syntax could use some improvements. See
792 <http://thread.gmane.org/gmane.text.docutils.user/2499> (and the
794 <http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>,
795 and the follow-ups at
796 <http://thread.gmane.org/gmane.text.docutils.user/3087>,
797 <http://thread.gmane.org/gmane.text.docutils.user/3110>,
798 <http://thread.gmane.org/gmane.text.docutils.user/3114>),
799 <http://thread.gmane.org/gmane.text.docutils.user/2443>,
800 <http://thread.gmane.org/gmane.text.docutils.user/2715>,
801 <http://thread.gmane.org/gmane.text.docutils.user/3027>,
802 <http://thread.gmane.org/gmane.text.docutils.user/3120>,
803 <http://thread.gmane.org/gmane.text.docutils.user/3253>.
805 * The current list-recognition logic has too many false positives, as
812 Here ``V.`` is recognized as an enumerator, which leads to
813 confusion. We need to find a solution that resolves such problems
814 without complicating the spec to much.
816 See <http://thread.gmane.org/gmane.text.docutils.user/2524>.
818 * Add indirect links via citation references & footnote references.
821 `Goodger (2005)`_ is helpful.
823 .. _Goodger (2005): [goodger2005]_
824 .. [goodger2005] citation text
826 See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
828 * Change the specification so that more punctuation is allowed
829 before/after inline markup start/end string
830 (http://article.gmane.org/gmane.text.docutils.cvs/3824).
832 * Complain about bad URI characters
833 (http://article.gmane.org/gmane.text.docutils.user/2046) and
834 disallow internal whitespace
835 (http://article.gmane.org/gmane.text.docutils.user/2214).
837 * Create ``info``-level system messages for unnecessarily
838 backslash-escaped characters (as in ``"\something"``, rendered as
839 "something") to allow checking for errors which silently slipped
842 * Add (functional) tests for untested roles.
844 * Add test for ":figwidth: image" option of "figure" directive. (Test
845 code needs to check if PIL is available on the system.)
847 * Add support for CJK double-width whitespace (indentation) &
848 punctuation characters (markup; e.g. double-width "*", "-", "+")?
850 * Add motivation sections for constructs in spec.
852 * Support generic hyperlink references to _`targets in other
853 documents`? Not in an HTML-centric way, though (it's trivial to say
854 ``http://www.example.com/doc#name``, and useless in non-HTML
855 contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
858 * .. _adaptable file extensions:
860 In target URLs, it would be useful to not explicitly specify the
861 file extension. If we're generating HTML, then ".html" is
862 appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
863 indicate "choose the most appropriate filename extension"? For
866 .. _Another Document: another.*
868 What is to be done for output formats that don't *have* hyperlinks?
869 For example, LaTeX targeted at print. Hyperlinks may be "called
870 out", as footnotes with explicit URLs. (Don't convert the links.)
872 But then there's also LaTeX targeted at PDFs, which *can* have
873 links. Perhaps a runtime setting for "*" could explicitly provide
874 the extension, defaulting to the output file's extension.
876 Should the system check for existing files? No, not practical.
878 Handle documents only, or objects (images, etc.) also?
880 If this handles images also, how to differentiate between document
881 and image links? Element context (within "image")? Which image
882 extension to use for which document format? Again, a runtime
883 setting would suffice.
885 This may not be just a parser issue; it may need framework support.
887 Mailing list threads: `Images in both HTML and LaTeX`__ (especially
888 `this summary of Lea's objections`__), `more-universal links?`__,
889 `Output-format-sensitive link targets?`__
891 __ http://thread.gmane.org/gmane.text.docutils.user/1239
892 __ http://article.gmane.org/gmane.text.docutils.user/1278
893 __ http://thread.gmane.org/gmane.text.docutils.user/1915
894 __ http://thread.gmane.org/gmane.text.docutils.user/2438
896 Idea from Jim Fulton: an external lookup table of targets:
898 I would like to specify the extension (e.g. .txt) [in the
899 source, rather than ``filename.*``], but tell the converter to
900 change references to the files anticipating that the files will
905 .. _Another Document: another.txt
907 rst2html.py --convert-links "another.txt bar.txt" foo.txt
909 That is, name the files for which extensions should be converted.
911 Note that I want to refer to original files in the original text
912 (another.txt rather than another.txt) because I want the
913 unconverted text to stand on its own.
915 Note that in most cases, people will be able to use globs::
917 rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
919 It might be nice to be able to use multiple arguments, as in::
921 rst2html.py --convert-link-extensions-for *.txt -- foo.txt
925 > What is to be done for output formats
926 > that don't have hyperlinks?
928 Don't convert the links.
932 > Handle documents only, or objects
933 > (images, etc.) also?
935 No, documents only, but there really is no need for gueswork.
936 Just get the file names as command-line arguments. EIBTI
937 [explicit is better than implicit].
939 For images, we probably need separate solution (which is being
940 worked on), whereas for documents, the issue is basically
941 interlinking between reStructuredText documents. IMO, this cries
942 for support for multiple input and output files, i.e. support for
943 documents which comprise multiple files. Adding adaptable file
944 extensions seems like a kludge. // FW
946 * Implement the header row separator modification to table.el. (Wrote
947 to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
948 support for "=====" header rows. On 2001-08-17 he replied, saying
949 he'd put it on his to-do list, but "don't hold your breath".)
951 * Fix the parser's indentation handling to conform with the stricter
952 definition in the spec. (Explicit markup blocks should be strict or
955 .. XXX What does this mean? Can you elaborate, David?
957 * Make the parser modular. Allow syntax constructs to be added or
958 disabled at run-time. Subclassing is probably not enough because it
959 makes it difficult to apply multiple extensions.
961 * Generalize the "doctest block" construct (which is overly
962 Python-centric) to other interactive sessions? "Doctest block"
963 could be renamed to "I/O block" or "interactive block", and each of
964 these could also be recognized as such by the parser:
969 A block beginning with a "$ " prompt is interpreted as a shell
970 session interactive block. As with Doctest blocks, the
971 interactive block ends with the first blank line, and wouldn't
974 - Root shell sessions::
977 A block beginning with a "# " prompt is interpreted as a root
978 shell session (the user is or has to be logged in as root)
979 interactive block. Again, the block ends with a blank line.
981 Other standard (and unambiguous) interactive session prompts could
982 easily be added (such as "> " for WinDOS).
984 Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
985 "docutils feedback").
987 * Add support for pragma (syntax-altering) directives.
989 Some pragma directives could be local-scope unless explicitly
990 specified as global/pragma using ":global:" options.
992 * Support whitespace in angle-bracketed standalone URLs according to
993 Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
996 .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt
998 * Use the vertical spacing of the source text to determine the
999 corresponding vertical spacing of the output?
1001 * [From Mark Nodine] For cells in simple tables that comprise a
1002 single line, the justification can be inferred according to the
1005 1. If the text begins at the leftmost column of the cell,
1006 then left justification, ELSE
1007 2. If the text begins at the rightmost column of the cell,
1008 then right justification, ELSE
1009 3. Center justification.
1011 The onus is on the author to make the text unambiguous by adding
1012 blank columns as necessary. There should be a parser setting to
1013 turn off justification-recognition (normally on would be fine).
1015 Decimal justification?
1017 All this shouldn't be done automatically. Only when it's requested
1018 by the user, e.g. with something like this::
1025 Otherwise it will break existing documents.
1027 * Generate a warning or info message for paragraphs which should have
1028 been lists, like this one::
1033 * Generalize the "target-notes" directive into a command-line option
1034 somehow? See docutils-develop 2003-02-13.
1036 * Allow a "::"-only paragraph (first line, actually) to introduce a
1037 _`literal block without a blank line`? (Idea from Paul Moore.) ::
1040 This is a literal block
1042 Is indentation enough to make the separation between a paragraph
1043 which contains just a ``::`` and the literal text unambiguous?
1044 (There's one problem with this concession: If one wants a definition
1045 list item which defines the term "::", we'd have to escape it.) It
1046 would only be reasonable to apply it to "::"-only paragraphs though.
1047 I think the blank line is visually necessary if there's text before
1050 The text in this paragraph needs separation
1051 from the literal block following::
1052 This doesn't look right.
1054 * Add new syntax for _`nested inline markup`? Or extend the parser to
1055 parse nested inline markup somehow? See the `collected notes
1056 <rst/alternatives.html#nested-inline-markup>`__.
1058 * Drop the backticks from embedded URIs with omitted reference text?
1059 Should the angle brackets be kept in the output or not? ::
1063 Probably not worth the trouble.
1065 * How about a syntax for alternative hyperlink behavior, such as "open
1066 in a new window" (as in HTML's ``<a target="_blank">``)?
1068 The MoinMoin wiki uses a caret ("^") at the beginning of the URL
1069 ("^" is not a legal URI character). That could work for both inline
1070 and explicit targets::
1072 The `reference docs <^url>`__ may be handy.
1076 This may be too specific to HTML. It hasn't been requested very
1079 * Add an option to add URI schemes at runtime.
1081 * _`Segmented lists`::
1083 : segment : segment : segment
1084 : segment : segment : very long
1086 : segment : segment : segment
1088 The initial colon (":") can be thought of as a type of bullet
1090 We could even have segment titles::
1092 :: title : title : title
1093 : segment : segment : segment
1094 : segment : segment : segment
1096 This would correspond well to DocBook's SegmentedList. Output could
1097 be tabular or "name: value" pairs, as described in DocBook's docs.
1099 * Allow backslash-escaped colons in field names::
1101 :Case Study\: Event Handling: This chapter will be dropped.
1103 * Enable grid _`tables inside XML comments`, where "--" ends comments.
1104 I see three implementation possibilities:
1106 1. Make the table syntax characters into "table" directive options.
1107 This is the most flexible but most difficult, and we probably
1108 don't need that much flexibility.
1110 2. Substitute "~" for "-" with a specialized directive option
1113 3. Make the standard table syntax recognize "~" as well as "-", even
1114 without a directive option. Individual tables would have to be
1115 internally consistent.
1117 Directive options are preferable to configuration settings, because
1118 tables are document-specific. A pragma directive would be another
1119 approach, to set the syntax once for a whole document.
1121 In the meantime, the list-table_ directive is a good replacement for
1122 grid tables inside XML comments.
1124 .. _list-table: ../ref/rst/directives.html#list-table
1126 * Generalize docinfo contents (bibliographic fields): remove specific
1127 fields, and have only a single generic "field"?
1129 Inline markup recognition rules
1130 -------------------------------
1132 Allow unicode whitespace and punctuation around `inline markup`_. See bug
1133 http://sourceforge.net/tracker/?func=detail&aid=3402314&group_id=38414&atid=422030
1134 and the older discussion
1135 <http://thread.gmane.org/gmane.text.docutils.user/2765>.
1137 The rules are currently *complicated* (rules, exceptions,
1138 explicite character lists, exceptions of exceptions) and *incomplete*: Many
1139 non-ASCII characters are missing in the inline markup start-string and
1140 end-string recognition rules. Use cases like »German ›angular‹ quotes« are
1143 .. _inline markup: ../ref/rst/restructuredtext.html#inline-markup
1148 Define character classes based on `Unicode categories`_, possibly with some
1149 exceptions (for backwards compatibility or based on use cases) and use them
1150 in the inline markup start-string and end-string recognition rules.
1152 The following sub-section is intended to replace the 5 inline markup rules in
1153 the reStructuredText Markup Specification's section on `inline markup`_.
1154 The composition of the character classes is open for discussion_.
1156 The actual change needs to be done in `parsers.rst.states.Inliner`.
1158 Inline markup syntax rules
1159 ~~~~~~~~~~~~~~~~~~~~~~~~~~
1161 The inline markup start-string and end-string recognition rules distinguish
1162 the following character classes based on `Unicode categories`_:
1165 :Zs: Separator, Space
1166 :Zl: Separator, Line
1168 :Zp: Separator, Paragraph
1170 Exception: Non-breaking spaces count as Delimiters_, they may
1171 immediately follow a start-string or precede an end-string.
1173 :[ ]: U+00A0, NO-BREAK SPACE
1174 :[ ]: U+202F, NARROW NO-BREAK SPACE
1177 :Ps: Punctuation, Open
1178 :Pi: Punctuation, Initial quote
1179 :Pf: Punctuation, Final quote [#PiPf]_
1180 :<: U+003C, LESS-THAN SIGN [#ltgt]_
1183 :Pe: Punctuation, Close
1184 :Pf: Punctuation, Final quote
1185 :Pi: Punctuation, Initial quote [#PiPf]_
1186 :>: U+003E, GREATER-THAN SIGN
1189 :Pd: Punctuation, Dash
1190 :Po: Punctuation, Other [#Po]_
1191 :[ ]: U+00A0, NO-BREAK SPACE
1192 :[ ]: U+202F, NARROW NO-BREAK SPACE
1194 If any of the following conditions are not met, the start-string or
1195 end-string will not be recognized or processed:
1197 1. Inline markup start-strings must start a text block or be immediately
1198 preceded by a character of the classes Whitespace_, Open_, or
1201 2. Inline markup start-strings must not be followed by Whitespace_.
1203 3. Inline markup end-strings must not be preceded by Whitespace_.
1205 4. Inline markup end-strings must end a text block or be immediately
1206 followed by a character of the classes Whitespace_, Close_, or
1209 5. If an inline markup start-string is immediately preceded by a
1210 single or double quote or a character from Open_, it must not be
1211 immediately followed by a corresponding single or double quote or
1212 character from Close.
1214 6. An inline markup end-string must be separated by at least one
1215 character from the start-string.
1217 7. An unescaped backslash preceding a start-string or end-string will
1218 disable markup recognition, except for the end-string of `inline
1219 literals`_. See `Escaping Mechanism`_ above for details.
1225 The current markup recognition rules deviate from the above proposal in some
1226 cases "to allow 90% of non-markup uses of "*", "`", "_", and "|" without
1227 resorting to backslashes".
1229 The above proposal aims to catch 85% of non-markup uses with simpler
1230 rules and enable additional markup uses (e.g. »German ›angular‹ quotes«)
1231 without escaping. It breaks backwards compatibility in some cases.
1232 However, if this is "the right thing", it should be done **now**, as long
1233 as the project is still "beta".
1235 Character classifications in need of discussion:
1237 .. [#PiPf] Pi (Punctuation, Initial quote) characters are "usually
1238 closing, sometimes opening". Pf (Punctuation, Final quote) characters
1239 are "usually closing, sometimes opening". I.e., both Pi and Pf may
1240 behave like Ps or Pe depending on usage. The current implementation
1241 sorts them into Open_ and Close_.
1242 Adding Pf to Close_ and Pi to Open_ solves e.g. the problem with
1243 »German ›angular‹ quotes«.
1245 .. [#ltgt] ``<`` and ``>`` belong to the Unicode category Ms (Symbols, Math).
1246 The current implementation sorts them into Open_ and Close_ because of
1247 their use as angular brackets in ASCII markup.
1249 .. [#Po] The ``Po`` characters ``.,;!?`` are usually followed by
1250 whitespace. The backslash ``\`` is rarely used in front of marked-up
1251 text. The current implementation sorts these characters into Close_.
1253 The Po characters ``¡¿`` open a sentence. The current
1254 implementation sorts them into Open_.
1259 a) The proposal_ above:
1261 +1 truly international (considering characters of all writing systems
1262 recorded in Unicode)
1263 +2 simpler specification of the rules
1264 -1 more complicated implementation
1266 b) Backwards compatibility
1270 :Po: "conservative" sorting of other punctuation:
1277 +1 backwards compatible,
1278 +1 logical extension of the existing rules,
1279 -1 exception list for "other" punctuation needed,
1280 -1 rules even more complicated,
1281 -1 not clear how to sort "other" punctuation that is currently not
1283 -2 use cases like »German ›angular‹ quotes« not recognized.
1285 c) Simple rule: merge Open_, Close, and Delimiters_
1287 Whitespace_, Open_, Close_, and Delimiters_ may all precede or follow
1290 +3 very comprehensible,
1291 -1 false positives need escaping,
1292 -2 not backwards compatible.
1297 Some ideas for implementing the above rules:
1299 David's regexp to match whitespace but keep NO-BREAK spaces as "invisible
1302 u'(?![\xa0\u202f])\\s', re.UNICODE
1304 For punctuation, check `Unicode categories`_ with
1305 ``unicodedata.category(ch)``
1306 (http://bytes.com/topic/python/answers/854011-identifying-unicode-punctuation-characters-python-regex)
1307 and generate a pattern string, e.g. ::
1309 chars_open = u''.join(unichr(x) for x in range(74868)
1310 if unicodedata.category(unichr(x)) in ('Ps', 'Pi', 'Pf')
1312 Do this in the setup script and use the resulting string literal?
1313 (Avoids re-calculation with every parsing run.)
1315 .. _inline markup: ../ref/rst/restructuredtext.html#inline-markup
1316 .. _inline literals: ../ref/rst/restructuredtext.html#inline-literals
1317 .. _escaping mechanism: ../ref/rst/restructuredtext.html#escaping-mechanism
1318 .. _Unicode categories:
1319 http://www.unicode.org/Public/5.1.0/ucd/UCD.html#General_Category_Values
1325 Since Docutils 0.8, a "math" role and directive using LaTeX math
1326 syntax as input format is part of reStructuredText.
1328 Provide for `alternative input formats`__?
1330 __ ./rst/alternatives.html#math-markup
1332 Try to be compatible with `Math support in Sphinx`_?
1334 * The ``:label:`` option selects a label for the equation, by which it
1335 can be cross-referenced, and causes an equation number to be issued.
1336 In Docutils, this would be called ``:name:``.
1338 * Option ``:nowrap:`` prevents wrapping of the given math in a
1339 math environment (you have to specify the math environment in the
1342 .. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
1348 Which equation environments should be supported by the math directive?
1352 + numbered: `equation`
1353 + unnumbered: `equation*`
1355 * multiline (test for ``\\`` outside of a nested environment
1356 (e.g. `array` or `cases`)
1358 + numbered: `align` (number every line)
1360 (To give one common number to all lines, put them in a `split`
1361 environment. Docutils then places it in an `equation` environment.)
1363 + unnumbered: `align*`
1365 + Sphinx math also supports `gather` (checking for blank lines in
1366 the content). Docutils puts content blocks separated by blank
1367 lines in separate math-block doctree nodes. (The only difference of
1368 `gather` to two consecutive "normal" environments seems to be that
1369 page-breaks between the two are prevented.)
1371 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
1377 There is no native math support in HTML.
1380 Converters from LaTeX to MathML include
1382 * latex_math_ (Python) by Jens Jørgen Mortensen in the Docutils sandbox
1385 * TeX4ht_ (TeX based)
1387 * itex_ (also `used in Abiword`__)
1388 * TtM_ (C, non free, free binary for Linux) with an `online-trial page`__
1389 * `Steve’s LATEX-to-MathML translator`_
1390 ('mini-language', javascript, Python)
1392 latex_math_ is the base for the current latex2mathml_ module used
1393 with ``--math-output=MathML``.
1395 * Write a new converter based on:
1397 * a generic tokenizer (see e.g. a `latex-codec recipe`_,
1398 `updated latex-codec`_, )
1399 * the Unicode-Char <-> LaTeX mappings database unimathsymbols_
1401 __ http://msevior.livejournal.com/26377.html
1402 __ http://hutchinson.belmont.ma.us/tth/mml/ttmmozform.html
1403 .. _MathML: http://www.w3.org/TR/MathML2/
1404 .. _latex_math: ../../../sandbox/jensj/latex_math/
1405 .. _latex2mathml: ../../docutils/math/latex2mathml.py
1406 .. _Blahtex: http://gva.noekeon.org/blahtexml/
1407 .. _MathToWeb: http://www.mathtoweb.com/
1408 .. _TeX4ht: http://www.tug.org/applications/tex4ht/mn.html
1409 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1410 .. _itex: http://golem.ph.utexas.edu/~distler/blog/itex2MMLcommands.html
1411 .. _ttm: http://hutchinson.belmont.ma.us/tth/mml/
1412 .. _Steve’s LATEX-to-MathML translator:
1413 http://www.gold-saucer.org/mathml/greasemonkey/dist/display-latex
1414 .. _latex-codec recipe:
1415 http://code.activestate.com/recipes/252124-latex-codec/
1416 .. _updated latex-codec:
1417 http://mirror.ctan.org/biblio/bibtex/utils/mab2bib/latex.py
1418 .. _unimathsymbols: http://milde.users.sourceforge.net/LUCR/Math/
1421 .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
1425 format math in standard HTML enhanced by CSS rules
1426 (Overview__, `Examples and experiments`__).
1428 LaTeX-math to HTML/CSS converters include
1431 * Hevea_ (Objective Caml)
1434 The ``math-output=html`` option uses the converter from eLyXer.
1436 __ http://www.cs.tut.fi/~jkorpela/math/
1437 __ http://www.zipcon.net/~swhite/docs/math/math.html
1438 .. _TtH: ttp://hutchinson.belmont.ma.us/tth/index.html
1439 .. _Hevea: http://para.inria.fr/~maranget/hevea/
1440 .. _elyxer: http://elyxer.nongnu.org/
1443 (PNG or SVG) like e.g. Wikipedia. (e.g. with dvisvgm_ or the
1444 pure-python MathML->SVG converter SVGMath_)
1446 .. _dvisvgm: http://dvisvgm.sourceforge.net/
1447 .. _SVGMath: http://www.grigoriev.ru/svgmath/
1453 * The `OpenDocument standard`_ version 1.1 says:
1455 Mathematical content is represented by MathML 2.0
1457 However, putting MathML into an ODP file seems tricky as these
1458 (maybe outdated) links suppose:
1459 http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx
1460 http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx
1462 .. _OpenDocument standard:
1463 http://www.oasis-open.org/standards#opendocumentv1.1
1465 * OOoLaTeX__: "a set of macros designed to bring the power of LaTeX
1468 __ http://ooolatex.sourceforge.net/
1474 Directives below are often referred to as "module.directive", the
1475 directive function. The "module." is not part of the directive name
1476 when used in a document.
1478 * Allow for field lists in list tables. See
1479 <http://thread.gmane.org/gmane.text.docutils.devel/3392>.
1483 Unify table implementations and unify options of table directives
1484 (http://article.gmane.org/gmane.text.docutils.user/1857).
1486 * Allow directives to be added at run-time?
1488 * Use the language module for directive option names?
1490 * Add "substitution_only" and "substitution_ok" function attributes,
1491 and automate context checking?
1493 * Implement options or features on existing directives:
1495 - All directives that produce titled elements should grow implicit
1496 reference names based on the titles.
1498 - Allow the _`:trim:` option for all directives when they occur in a
1499 substitution definition, not only the unicode_ directive.
1501 .. _unicode: ../ref/rst/directives.html#unicode-character-codes
1503 - Add the "class" option to the unicode_ directive. For example, you
1504 might want to get characters or strings with borders around them.
1506 - _`images.figure`: "title" and "number", to indicate a formal
1509 - _`parts.sectnum`: "local"?, "refnum"
1511 A "local" option could enable numbering for sections from a
1512 certain point down, and sections in the rest of the document are
1513 not numbered. For example, a reference section of a manual might
1514 be numbered, but not the rest. OTOH, an all-or-nothing approach
1515 would probably be enough.
1517 The "sectnum" directive should be usable multiple times in a
1518 single document. For example, in a long document with "chapter"
1519 and "appendix" sections, there could be a second "sectnum" before
1520 the first appendix, changing the sequence used (from 1,2,3... to
1521 A,B,C...). This is where the "local" concept comes in. This part
1522 of the implementation can be left for later.
1524 A "refnum" option (better name?) would insert reference names
1525 (targets) consisting of the reference number. Then a URL could be
1526 of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
1527 internal references by number? Allow name-based *and*
1528 number-based ids at the same time, or only one or the other (which
1529 would the table of contents use)? Usage issue: altering the
1530 section structure of a document could render hyperlinks invalid.
1532 - _`parts.contents`: Add a "suppress" or "prune" option? It would
1533 suppress contents display for sections in a branch from that point
1534 down. Or a new directive, like "prune-contents"?
1536 Add an option to include topics in the TOC? Another for sidebars?
1537 The "topic" directive could have a "contents" option, or the
1538 "contents" directive" could have an "include-topics" option. See
1539 docutils-develop 2003-01-29.
1541 - _`parts.header` & _`parts.footer`: Support multiple, named headers
1542 & footers? For example, separate headers & footers for odd, even,
1543 and the first page of a document.
1545 This may be too specific to output formats which have a notion of
1550 - Add a ``:parent:`` option for setting the parent's class
1551 (http://article.gmane.org/gmane.text.docutils.devel/3165).
1555 - Option to label lines?
1557 - How about an environment variable, say RSTINCLUDEPATH or
1558 RSTPATH, for standard includes (as in ``.. include:: <name>``)?
1559 This could be combined with a setting/option to allow
1560 user-defined include directories.
1562 - Add support for inclusion by URL? ::
1565 :url: http://www.example.org/inclusion.txt
1567 - Strip blank lines from begin and end of a literal included file or
1568 file section. This would correspond to the way a literal block is
1571 As nodes.literal_block expects (and we have) the text as a string
1572 (rather than a list of lines), using a regexp seems the way.
1574 - _`misc.raw`: add a "destination" option to the "raw" directive? ::
1581 It needs thought & discussion though, to come up with a consistent
1582 set of destination labels and consistent behavior.
1584 And placing HTML code inside the <head> element of an HTML
1585 document is rather the job of a templating system.
1587 - _`body.sidebar`: Allow internal section structure? Adornment
1588 styles would be independent of the main document.
1590 That is really complicated, however, and the document model
1591 greatly benefits from its simplicity.
1593 * Implement directives. Each of the list items below begins with an
1594 identifier of the form, "module_name.directive_function_name". The
1595 directive name itself could be the same as the
1596 directive_function_name, or it could differ.
1600 It has the disadvantage that it's only easily implementable for
1601 HTML, so it's specific to one output format.
1603 (For non-HTML writers, the imagemap would have to be replaced with
1606 - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
1608 - _`parts.citations`: See `Footnote & Citation Gathering`_.
1610 - _`misc.language`: Specify (= change) the language of a document at
1613 * The misc.settings_ directive suggested below offers a more generic
1616 * The language of document parts can be indicated by the "special class
1617 value" ``"language-"`` + `BCP 47`_ language code. Class arguments to
1618 the title are attached to the document's base node - hence titled
1619 documents can be given a different language at parse time. However,
1620 "language by class attribute" does not change parsing (localized
1621 directives etc.), only supporting writers.
1623 .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
1626 - _`misc.settings`: Set any(?) Docutils runtime setting from within
1627 a document? Needs much thought and discussion.
1629 Security concerns need to be taken into account (it shouldn't be
1630 possible to enable ``file_insertion_enabled`` from within a
1631 document), and settings that only would have taken effect before
1632 the directive (like ``tab-width``) shouldn't be accessible either.
1634 See this sub-thread:
1635 <http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649>
1637 - _`misc.gather`: Gather (move, or copy) all instances of a specific
1638 element. A generalization of the `Footnote & Citation Gathering`_
1641 - Add a custom "directive" directive, equivalent to "role"? For
1646 .. class:: incremental
1650 "``.. incr::``" above is equivalent to "``.. class:: incremental``".
1654 .. directive:: printed-links
1660 :class: print-inline
1662 This acts like macros. The directive contents will have to be
1663 evaluated when referenced, not when defined.
1665 * Needs a better name? "Macro", "substitution"?
1666 * What to do with directive arguments & options when the
1667 macro/directive is referenced?
1669 - Make the meaning of block quotes overridable? Only a 1-shot
1670 though; doesn't solve the general problem.
1672 - .. _conditional directives:
1674 .. note:: See also the implementation in Sphinx_.
1676 Docutils already has the ability to say "use this content for
1677 Writer X" (via the "raw" directive), but it doesn't have the
1678 ability to say "use this content for any Writer other than X". It
1679 wouldn't be difficult to add this ability though.
1681 My first idea would be to add a set of conditional directives.
1682 Let's call them "writer-is" and "writer-is-not" for discussion
1683 purposes (don't worry about implemention details). We might
1686 .. writer-is:: text-only
1702 .. figure:: protocol_stack.eps
1704 .. writer-is-not:: text-only pdf
1706 .. figure:: protocol_stack.png
1708 This could be an interface to the Filter transform
1709 (docutils.transforms.components.Filter).
1711 The ideas in `adaptable file extensions`_ above may also be
1714 SVG's "switch" statement may provide inspiration.
1716 Here's an example of a directive that could produce multiple
1717 outputs (*both* raw troff pass-through *and* a GIF, for example)
1718 and allow the Writer to select. ::
1725 %sum from i=o to inf c sup i~=~lim from {m -> inf}
1726 sum from i=0 to m sup i%
1731 - _`body.example`: Examples; suggested by Simon Hefti. Semantics as
1732 per Docbook's "example"; admonition-style, numbered, reference,
1733 with a caption/title.
1735 - _`body.index`: Index targets.
1737 See `Index Entries & Indexes
1738 <./rst/alternatives.html#index-entries-indexes>`__.
1740 - _`body.literal`: Literal block, possibly "formal" (see `object
1741 numbering and object references`_ above). Possible options:
1743 - "highlight" a range of lines
1745 - include only a specified range of lines
1747 - "number" or "line-numbers"
1749 - "styled" could indicate that the directive should check for
1750 style comments at the end of lines to indicate styling or
1753 Specific derivatives (i.e., a "python-interactive" directive)
1754 could interpret style based on cues, like the ">>> " prompt and
1755 "input()"/"raw_input()" calls.
1757 See docutils-users 2003-03-03.
1759 - _`body.listing`: Code listing with title (to be numbered
1760 eventually), equivalent of "figure" and "table" directives.
1762 - _`pysource.usage`: Extract a usage message from the program,
1763 either by running it at the command line with a ``--help`` option
1764 or through an exposed API. [Suggestion for Optik.]
1770 Interpreted text is entirely a reStructuredText markup construct, a
1771 way to get around built-in limitations of the medium. Some roles are
1772 intended to introduce new doctree elements, such as "title-reference".
1773 Others are merely convenience features, like "RFC".
1775 All supported interpreted text roles must already be known to the
1776 Parser when they are encountered in a document. Whether pre-defined
1777 in core/client code, or in the document, doesn't matter; the roles
1778 just need to have already been declared. Adding a new role may
1779 involve adding a new element to the DTD and may require extensive
1780 support, therefore such additions should be well thought-out. There
1781 should be a limited number of roles.
1783 The only place where no limit is placed on variation is at the start,
1784 at the Reader/Parser interface. Transforms are inserted by the Reader
1785 into the Transformer's queue, where non-standard elements are
1786 converted. Once past the Transformer, no variation from the standard
1787 Docutils doctree is possible.
1789 An example is the Python Source Reader, which will use interpreted
1790 text extensively. The default role will be "Python identifier", which
1791 will be further interpreted by namespace context into <class>,
1792 <method>, <module>, <attribute>, etc. elements (see pysource.dtd),
1793 which will be transformed into standard hyperlink references, which
1794 will be processed by the various Writers. No Writer will need to have
1795 any knowledge of the Python-Reader origin of these elements.
1797 * Add explicit interpreted text roles for the rest of the implicit
1798 inline markup constructs: named-reference, anonymous-reference,
1799 footnote-reference, citation-reference, substitution-reference,
1800 target, uri-reference (& synonyms).
1802 * Add directives for each role as well? This would allow indirect
1805 This text contains |nested inline markup|.
1807 .. |nested inline markup| emphasis::
1809 nested ``inline`` markup
1813 - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
1814 around role contents.
1816 For example, the following reStructuredText source ... ::
1818 .. role:: red(raw-formatting)
1820 :html: <font color="red">
1821 :latex: {\color{red}
1828 ... will yield the following document fragment::
1832 <inline classes="red">
1835 <raw format="latex">
1837 <inline classes="red">
1841 <raw format="latex">
1844 Possibly without the intermediate "inline" node.
1846 - _`"acronym" and "abbreviation"`: Associate the full text with a
1847 short form. Jason Diamond's description:
1849 I want to translate ```reST`:acronym:`` into ``<acronym
1850 title='reStructuredText'>reST</acronym>``. The value of the
1851 title attribute has to be defined out-of-band since you can't
1852 parameterize interpreted text. Right now I have them in a
1853 separate file but I'm experimenting with creating a directive
1854 that will use some form of reST syntax to let you define them.
1856 Should Docutils complain about undefined acronyms or
1859 What to do if there are multiple definitions? How to
1860 differentiate between CSS (Content Scrambling System) and CSS
1861 (Cascading Style Sheets) in a single document? David Priest
1864 The short answer is: you don't. Anyone who did such a thing
1865 would be writing very poor documentation indeed. (Though I
1866 note that `somewhere else in the docs`__, there's mention of
1867 allowing replacement text to be associated with the
1868 abbreviation. That takes care of the duplicate
1869 acronyms/abbreviations problem, though a writer would be
1870 foolish to ever need it.)
1872 __ `inline parameter syntax`_
1874 How to define the full text? Possibilities:
1876 1. With a directive and a definition list? ::
1883 Docstring Processing System
1885 Would this list remain in the document as a glossary, or would
1886 it simply build an internal lookup table? A "glossary"
1887 directive could be used to make the intention clear.
1888 Acronyms/abbreviations and glossaries could work together.
1890 Then again, a glossary could be formed by gathering individual
1891 definitions from around the document.
1893 2. Some kind of `inline parameter syntax`_? ::
1895 `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
1896 see is what you get>`:acronym: plaintext markup.
1898 .. _inline parameter syntax:
1899 rst/alternatives.html#parameterized-interpreted-text
1901 3. A combination of 1 & 2?
1903 The multiple definitions issue could be handled by establishing
1904 rules of priority. For example, directive-based lookup tables
1905 have highest priority, followed by the first inline definition.
1906 Multiple definitions in directive-based lookup tables would
1907 trigger warnings, similar to the rules of `implicit hyperlink
1910 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
1912 4. Using substitutions? ::
1914 .. |reST| acronym:: reST
1915 :text: reStructuredText
1917 What do we do for other formats than HTML which do not support
1918 tool tips? Put the full text in parentheses?
1920 - "figure", "table", "listing", "chapter", "page", etc: See `object
1921 numbering and object references`_ above.
1923 - "glossary-term": This would establish a link to a glossary. It
1924 would require an associated "glossary-entry" directive, whose
1925 contents could be a definition list::
1934 This would allow entries to be defined anywhere in the document,
1935 and collected (via a "glossary" directive perhaps) at one point.
1941 The number of doctree nodes can be reduced by "normalizing" some related
1942 nodes. This makes the document model and the writers somewhat simpler.
1944 * The "doctest" element should go away. The construct could simply be
1945 a front-end to generic literal blocks. We could immediately (in 0.7)
1946 remove the doctest node from the doctree, but leave the
1947 syntax in reST. The reST parser could represent doctest blocks as
1948 literal blocks with a class attribute. The syntax could be left in
1949 reST (for a set period of time?).
1951 * "Normalize" special admonitions (note, hint, warning, ...) during parsing
1952 (similar to _`transforms.writer_aux.Admonitions`). There is no need to
1953 keep them as distinct elements in the doctree specification.
1955 Keep the special admonition directives in reStructuredText syntax?
1957 * _`Line numbers` and "source" in system messages:
1959 - Add "source" and "line" keyword arguments to all Reporter calls?
1960 This would require passing source/line arguments along all
1961 intermediate functions (where currently only `line` is used).
1963 Or rather specify "line" only if actually needed?
1965 Currently, `document.reporter` uses a state machine instance to
1966 determine the "source" and "line" info from
1967 `statemachine.input_lines` if not given explicitely. Except for
1968 special cases, the "line" argument is not needed because,
1969 `document.statemachine` keeps record of the current line number.
1971 - For system messages generated after the parsing is completed (i.e. by
1972 transforms or the writer) "line" info must be present in the doctree
1975 Elements' .line assignments should be checked. (Assign to .source
1976 too? Add a set_info method? To what?)
1978 The "source" (and line number in the source) can either be added
1979 explicitely to the elements or determined from the “raw” line
1980 number by `document.statemachine.get_source_and_line`.
1982 - Some line numbers in elements are not being set properly
1983 (explicitly), just implicitly/automatically. See rev. 1.74 of
1984 docutils/parsers/rst/states.py for an example of how to set.
1986 - The line numbers of definition list items are wrong::
1988 $ rst2pseudoxml.py --expose-internal-attribute line
1997 <document source="<stdin>">
1999 <definition_list_item internal:line="3">
2003 <paragraph internal:line="2">
2006 <definition_list_item internal:line="6">
2010 <paragraph internal:line="6">
2016 Quite a few nodes are getting a "None" source attribute as well. In
2017 particular, see the bodies of definition lists.
2021 Unimplemented Transforms
2022 ========================
2024 * _`Footnote & Citation Gathering`
2026 Collect and move footnotes & citations to the end of a document or the
2027 place of a "footnotes" or "citations" directive
2028 (see `<./ref/rst/directives.html>_`)
2031 Collect all footnotes that are referenced in the document before the
2032 directive (and after an eventually preceding ``.. footnotes::``
2033 directive) and insert at this place.
2035 Allows "endnotes" at a configurable place.
2038 Collect citations that are referenced ...
2042 a) defined in the document as citation elements
2044 b) auto-generated from entries in a bibliographic database.
2046 + based on bibstuff_?
2047 + also have a look at
2049 * CrossTeX_, a backwards-compatible, improved bibtex
2050 re-implementation in Python (including HTML export).
2051 (development stalled since 2 years)
2053 * Pybtex_,a drop-in replacement for BibTeX written in Python.
2055 * BibTeX styles & (experimental) pythonic style API.
2056 * Database in BibTeX, BibTeXML and YAML formats.
2057 * full Unicode support.
2058 * Write to TeX, HTML and plain text.
2060 * Automatically insert a "References" heading?
2062 .. _CrossTeX: http://www.cs.cornell.edu/people/egs/crosstex/
2063 .. _Pybtex: http://pybtex.sourceforge.net/
2065 * _`Reference Merging`
2067 When merging two or more subdocuments (such as docstrings),
2068 conflicting references may need to be resolved. There may be:
2070 * duplicate reference and/or substitution names that need to be made
2072 * duplicate footnote numbers that need to be renumbered.
2074 Should this be done before or after reference-resolving transforms
2075 are applied? What about references from within one subdocument to
2078 * _`Document Splitting`
2080 If the processed document is written to multiple files (possibly in
2081 a directory tree), it will need to be split up. Internal references
2082 will have to be adjusted.
2084 (HTML only? Initially, yes. Eventually, anything should be
2089 - Insert a "destination" attribute into the root element of each
2090 split-out document, containing the path/filename. The Output
2091 object or Writer will recognize this attribute and split out the
2092 files accordingly. Must allow for common headers & footers,
2093 prev/next, breadcrumbs, etc.
2095 - Transform a single-root document into a document containing
2096 multiple subdocuments, recursively. The content model of the
2097 "document" element would have to change to::
2100 ( (title, subtitle?)?,
2102 (docinfo, transition?)?,
2106 (I.e., add the last line -- 0 or more document elements.)
2108 Let's look at the case of hierarchical (directories and files)
2109 HTML output. Each document element containing further document
2110 elements would correspond to a directory (with an index.html file
2111 for the content preceding the subdocuments). Each document
2112 element containing no subdocuments (i.e., structure model elements
2113 only) corresponds to a concrete file with no directory.
2115 The natural transform would be to map sections to subdocuments,
2116 but possibly only a given number of levels deep.
2120 If a document is split up, each segment will need navigation links:
2121 parent, children (small TOC), previous (preorder), next (preorder).
2122 Part of `Document Splitting`_?
2124 * _`List of System Messages`
2126 The ``system_message`` elements are inserted into the document tree,
2127 adjacent to the problems themselves where possible. Some (those
2128 generated post-parse) are kept until later, in
2129 ``document.messages``, and added as a special final section,
2130 "Docutils System Messages".
2132 Docutils could be made to generate hyperlinks to all known
2133 system_messages and add them to the document, perhaps to the end of
2134 the "Docutils System Messages" section.
2136 Fred L. Drake, Jr. wrote:
2138 I'd like to propose that both parse- and transformation-time
2139 messages are included in the "Docutils System Messages" section.
2140 If there are no objections, I can make the change.
2142 The advantage of the current way of doing things is that parse-time
2143 system messages don't require a transform; they're already in the
2144 document. This is valuable for testing (unit tests,
2145 tools/quicktest.py). So if we do decide to make a change, I think
2146 the insertion of parse-time system messages ought to remain as-is
2147 and the Messages transform ought to move all parse-time system
2148 messages (remove from their originally inserted positions, insert in
2149 System Messages section).
2151 * _`Index Generation`
2155 Convert quotes and dashes to typographically correct entities.
2156 Sphinx does this with ``smartypants.py``.
2158 Write a generic version that uses Unicode chars
2159 (let the writer replace these if required).
2161 Some arguments for "smart quotes" are collected in a `mail to
2162 docutils-user by Jörg W. Mittag from 2006-03-13`__.
2164 Also see the "... Or Not To Do?" list entry for
2165 `Character Processing`_
2167 __ http://article.gmane.org/gmane.text.docutils.user/2765
2169 .. _Character Processing: rst/alternatives.html#character-processing
2175 * Make it easier to find out fragment names (#foo-bar) of ``_`inline
2176 targets```. Currently you have to either look at the source or
2179 For example, we could add support for self-referencing targets
2180 (i.e. inline targets would [unobtrusively] link to themselves, so
2181 that you can just click them and then copy the address). Or we
2182 could add support for titles that display the fragment name (as in
2183 <http://subversion.tigris.org/mailing-list-guidelines.html>; just
2184 hover the paragraphs).
2186 Either way it should be optional and deactivated by default.
2188 This would be useful for documents like Docutils' bug list or to-do
2191 * Make the _`list compacting` logic more generic: For example, allow
2192 for literal blocks or line blocks inside of compact list items.
2194 This is not implementable as long as list compacting is done by
2195 omitting ``<p>`` tags. List compacting would need to be done by
2196 adjusting CSS margins instead.
2198 * Idea for field-list rendering: hanging indent::
2200 Field name (bold): First paragraph of field body begins
2201 with the field name inline.
2203 If the first item of a field body is not a paragraph,
2204 it would begin on the following line.
2206 * Add more support for <link> elements, especially for navigation
2209 The framework does not have a notion of document relationships, so
2210 probably raw.destination_ should be used.
2212 We'll have framework support for document relationships when support
2213 for `multiple output files`_ is added. The HTML writer could
2214 automatically generate <link> elements then.
2216 .. _raw.destination: misc.raw_
2218 * Base list compaction on the spacing of source list? Would require
2219 parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
2221 * Add a tool tip ("title" attribute?) to footnote back-links
2222 identifying them as such. Text in Docutils language module.
2228 * Remove the generic style information (duplicated from html4css1.css)
2229 from pep.css to avoid redundancy.
2231 Needs support for multiple stylesheets in the PEP writer
2232 (is this inherited from HTML?).
2238 * Add a way to begin an untitled slide.
2240 * Add a way to begin a new slide, continuation, using the same title
2241 as the previous slide? (Unnecessary?) You need that if you have a
2242 lot of items in one section which don't fit on one slide.
2244 Maybe either this item or the previous one can be realized using
2247 * Have a timeout on incremental items, so the colour goes away after 1
2250 * Add an empty, black last slide (optionally). Currently the handling
2251 of the last slide is not very nice, it re-cycles through the
2252 incremental items on the last slide if you hit space-bar after the
2255 * Add a command-line option to disable advance-on-click.
2257 * Add a speaker's master document, which would contain a small version
2258 of the slide text with speaker's notes interspersed. The master
2259 document could use ``target="whatever"`` to direct links to a
2260 separate window on a second monitor (e.g., a projector).
2262 .. Note:: This item and the following items are partially
2263 accomplished by the S5 1.2 code (currently in alpha), which has
2264 not yet been integrated into Docutils.
2266 * Speaker's notes -- how to intersperse? Could use reST comments
2267 (".."), but make them visible in the speaker's master document. If
2268 structure is necessary, we could use a "comment" directive (to avoid
2269 nonsensical DTD changes, the "comment" directive could produce an
2270 untitled topic element).
2272 The speaker's notes could (should?) be separate from S5's handout
2275 * The speaker's master document could use frames for easy navigation:
2276 TOC on the left, content on the right.
2278 - It would be nice if clicking in the TOC frame simultaneously
2279 linked to both the speaker's notes frame and to the slide window,
2280 synchronizing both. Needs JavaScript?
2282 - TOC would have to be tightly formatted -- minimal indentation.
2284 - TOC auto-generated, as in the PEP Reader. (What if there already
2285 is a "contents" directive in the document?)
2287 - There could be another frame on the left (top-left or bottom-left)
2288 containing a single "Next" link, always pointing to the next slide
2289 (synchronized, of course). Also "Previous" link? FF/Rew go to
2290 the beginning of the next/current parent section? First/Last
2291 also? Tape-player-style buttons like ``|<< << < > >> >>|``?
2296 Add epub as an output format.
2298 Pack the output of a HTML writer and supporting files (e.g. images)
2299 into one single epub document.
2301 epub is an open file format for ebooks based on HTML, specified by the
2302 `International Digital Publishing Forum`_. Thus, documents in epub
2303 format are suited to be read with `electronic reading devices`_. The
2304 epub format comprises:
2306 * `Open Publication Structure (OPS)
2307 <http://www.idpf.org/2007/ops/OPS_2.0_final_spec.html>`_
2308 * `Open Packaging Format (OPF)
2309 <http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html>`_
2310 * `OEBPS Container Format (OCF)
2311 <http://www.idpf.org/ocf/ocf1.0/download/ocf10.htm>`_
2315 There is a project for epub support with sphinx providing a
2316 (hopefully) reusable framework.
2318 .. _rst2epub: http://bitbucket.org/wierob/rst2epub/
2319 .. _International Digital Publishing Forum: http://www.idpf.org/
2320 .. _electronic reading devices:
2321 http://en.wikipedia.org/wiki/List_of_e-book_readers
2323 Also, the plasTeX_ Python package has an EPUB renderer:
2325 It simply calls the XHTML renderer and does the epub packaging in
2328 .. _plasTeX: http://plastex.sourceforge.net/
2334 Also see the Problems__ section in the `latex writer documentation`_.
2336 __ ../user/latex.html#problems
2338 .. _latex writer documentation: ../user/latex.html
2341 ../../../sandbox/latex-variants/README.html
2346 * A multirow cell in a table expects empty cells in the spanned rows while
2347 the doctree contains only the remaining cells ("Exchange Table Model", see
2348 docs/ref/soextblx.dtd).
2350 Needs bookkeeping of "open" multirow cells (how many how long) and
2351 insertion of additional '&'s.
2353 See `<../../test/functional/input/data/latex.txt>`__
2355 * Too deeply nested lists fail: generate a warning and provide
2358 * Spaces in inline literal text::
2361 spacing between the words of this sentence (words
2362 should be grouped in pairs).
2364 Discuss the desired behaviour and implement a consistent one.
2366 * An enumerated list in the docinfo fails (\newcounter definition inside
2369 * File names of included graphics (see also `grffile` package).
2371 Generate clean and configurable LaTeX source
2372 ----------------------------------------------
2374 * Check the generated source with package `nag`.
2376 Configurable placement of figure and table floats
2377 `````````````````````````````````````````````````
2379 * Special class argument to individually place figures?
2383 placement-<optional arg> -> \figure[<optional arg>]{...}
2385 e.g. ``.. class:: placement-htb``,
2390 :h: place-here-if-possible
2393 :p: place-on-extra-page
2395 e.g.: ``.. class:: place-here-if-possible place-top place-bottom``
2397 Maybe support both variants?
2400 LaTeX constructs and packages instead of re-implementations
2401 ```````````````````````````````````````````````````````````
2403 Which packages do we want to use?
2405 + base and "recommended" packages
2407 (packages that should be in a "reasonably sized and reasonably modern
2408 LaTeX installation like the `texlive-latex-recommended` Debian package,
2411 + No "fancy" or "exotic" requirements.
2413 + pointers to advanced packages and their use in the `latex writer
2416 * ``alltt`` environment for literal block.
2420 + True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
2421 (also for target-footnotes):
2423 - attach footnote text to footnote-symobol node
2424 - write \footnote{<footnote text>}
2425 - consider cases where LaTeX does not support footnotes
2426 (inside tables, headings, ...)?
2427 - consider multiple footnote refs to common footnote text.
2431 If the symbol you want is not one of the ones listed, you'll need to
2432 redefine ``\@fnsymbol`` and add it, e.g. perhaps like::
2434 \def\@fnsymbol#1{\ifcase#1\hbox{}\or *\or \dagger\or \ddagger\or
2435 \mathchar "278\or \mathchar "27B\or \|\or **\or \dagger\dagger \or
2436 \ddagger\ddagger \or \mathchar"27C \else\@ctrerr\fi\relax}
2438 which would allow \symbolfootnote[10]{footnote} to have a club as its
2441 + document customization (links to how-to and packages):
2443 .. Footnote packages:
2445 :footnote: texlive-latex-recommended % savenotes environment
2446 :footmisc: texlive-latex-extra % formatting options
2447 :manyfoot: texlive-latex-extra
2448 :bigfoot: texlive-latex-extra
2449 :perpage: texlive-latex-extra
2450 :ftnxtra: new on CTAN
2451 fixes the issue of footnote inside \caption{},
2452 tabular environment and \section{} like commands.
2456 http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf
2460 `Footnotes whose texts are identical
2461 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=repfootnote>`__
2463 * label per hand or use footmisc
2465 `More than one sequence of footnotes
2466 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot>`__
2470 `Footnotes in tables
2471 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab>`__
2473 * `tabularx` and longtable allow footnotes.
2474 * `footnote` provides a "savenotes" environment which collects all
2475 footnotes and emits them at ``end{savenotes}``
2477 `Footnotes in LaTeX section headings
2478 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect>`__
2480 * Take advantage of the fact that the mandatory argument doesn't
2481 move if the optional argument is present::
2483 \section[title] {title\footnote{title ftnt}}
2485 * Use the footmisc package, with package option stable - this modifies
2486 footnotes so that they softly and silently vanish away if used in a
2491 `Footnotes numbered per page
2492 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footnpp>`__
2494 * perpage provides a general mechanism for resetting counters per page
2495 * footmisc provides a package option perpage
2497 * enumeration environment, field list
2499 * use `mdwlist` from texlive-latex-recommended?
2501 * use `eqlist` (texlive-latex-extra) for field-lists?
2504 * ``--use-latex-when-possible`` »super option« that would set the
2507 --no-section-numbering
2510 --use-latex-abstract
2511 --use-latex-footnotes
2512 --use-latex-citations
2514 ? (My preference is to default to use-latex-* whenever possible [GM])
2520 * Use italic instead of slanted for titlereference?
2522 * Start a new paragraph after lists (as currently)
2523 or continue (no blank line in source, no parindent in output)?
2527 * continue if the `compound paragraph`_ directive is used, or
2528 * force a new paragraph with an empty comment.
2530 * Sidebar handling (environment with `framed`, `marginnote`, `wrapfig`,
2533 * Use optionlist for docinfo?
2535 * Keep literal-blocks together on a page, avoid pagebreaks.
2537 Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
2540 Should be possible with ``--literal-block-env==lstlistings`` and some
2543 * More space between title and subtitle? ::
2546 + \\[0.5em] % subtitle%
2548 .. _PSNFSS documentation:
2549 http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
2550 .. _compound paragraph:
2551 ../ref/rst/directives.html#compound-paragraph
2553 http://mirror.ctan.org/help/Catalogue/entries/fixltx2e.html
2558 * Improve/simplify logic to set the column width in the output.
2560 + Assumed reST line length for table width setting configurable, or
2561 + use `ltxtable` (a combination of `tabularx` (auto-width) and
2562 `longtable` (page breaks)), or
2563 + use tabularx column type ``X`` and let LaTeX decide width, or
2567 http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=tabulary
2569 * From comp.text.tex (13. 4. 2011):
2571 When using fixed width columns, you should ensure that the total
2572 width does not exceed \linewidth: if the first column is p{6cm}
2573 the second one should be p{\dimexpr\linewidth-6cm-4\tabcolsep}
2574 because the glue \tabcolsep is added twice at every column edge.
2575 You may also consider to set \tabcolsep to a different value...
2577 * csv-tables do not have a colwidth.
2579 * Add more classes or options, e.g. for
2581 + column width set by latex,
2582 + horizontal alignment and rules.
2583 + long table vs. tabular (see next item).
2585 * Use tabular instead of longtable for tables in legends or generally
2588 Alternatively, default to tabular and use longtable only if specified
2589 by config setting or class argument (analogue to booktable)?
2591 * Table heads and footer for longtable (firstpage lastpage ..)?
2593 * In tools.txt the option tables right column, there should be some more
2594 spacing between the description and the next paragraph "Default:".
2596 * Paragraph separation in tables is hairy.
2597 see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
2599 - The strut solution did not work.
2600 - setting extrarowheight added ad top of row not between paragraphs in
2601 a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
2602 - baselineskip/stretch does not help.
2604 * Should there be two hlines after table head and on table end?
2606 * Place titled tables in a float ('table' environment)?
2608 The 'table', 'csv-table', and 'list-table' directives support an (optional)
2609 table title. In analogy to the 'figure' directive this should map to a
2612 Image and figure directives
2613 ```````````````````````````
2615 * compare the test case in:
2617 + `<../../test/functional/input/data/standard.txt>`__
2618 + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
2619 + `<../../test/functional/expected/standalone_rst_latex.tex>`__
2621 * According to the HTML standard
2622 http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG a right- or
2623 left-aligned image should be floated alongside the paragraph.
2625 + Use this default also for LaTeX?
2627 + Wrap text around figures/images with class argument "wrap"
2628 (like the odt writer)?
2630 Use `wrapfig` (or other recommended) package.
2632 * support more graphic formats (especially SVG, the only standard
2633 vector format for HTML)
2635 There is a `SWF package`_ at CTAN.
2638 http://mirror.ctan.org/macros/latex/contrib/flashmovie
2644 * support "figwidth" argument for figures.
2646 As the 'figwidth' argument is still ignored and the "natural width" of
2647 a figure in LaTeX is 100 % of the text width, setting the 'align'
2648 argument has currently no effect on the LaTeX output.
2651 * Let `meta` directive insert PDF-keywords into header?
2653 * Multiple author entries in docinfo (same thing as in html).
2656 * Consider supporting the "compact" option and class argument (from
2657 rst2html) as some lists look better compact and others need the space.
2659 * Better citation support
2660 (see `Footnote & Citation Gathering`_).
2662 * If ``use-latex-citations`` is used, a bibliography is inserted right at the
2663 end of the document.
2665 Put in place of the to-be-implemented "citations" directive
2666 (see `Footnote & Citation Gathering`_).
2672 The `LyX <http://www.lyx.org>`_ document processor has a comprehensive
2673 Unicode to LaTeX conversion feature with a file called ``unicodesymbols``
2674 that lists LaTeX counterparts for a wide range of Unicode characters.
2676 * Use this in the LaTeXTranslator?
2677 Think of copyright issues!
2679 * The "ucs" package has many translations in ...doc/latex/ucs/config/
2681 * The bibstuff_ tool ships a `latex_codec` Python module!
2683 .. _bibstuff: http://code.google.com/p/bibstuff/
2685 Allow choice between utf8 (standard) and utf8x (extended) encodings
2686 ```````````````````````````````````````````````````````````````````
2688 * Allow the user to select *utf8* or *utf8x* LaTeX encoding. (Docutil's
2689 output encoding becomes LaTeX's input encoding.)
2691 The `ucs` package provides extended support for UTF-8 encoding in LaTeX
2692 via the `inputenc`-option ``utf8x``. It is, however, a non-standard
2693 extension and no longer developed.
2696 a) Python has 4 names for the UTF-8 encoding (``utf_8, U8, UTF, utf8``)
2697 give a special meaning to one of the aliases,
2699 b) scan "stylesheets" and "latex-preamble" options and use ``utf8x``
2700 if it contains ``ucs``
2705 * Glyphs missing in the font are left out in the PDF without warning
2706 (e.g. ⇔ left-right double arrow in the functional test output).
2708 * Disable word-wrap (hyphenation) in literal text locally with
2709 ``providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}``?
2715 * ^^ LaTeX's special syntax for characters results in "strange" replacements
2716 (both with \href and \url).
2718 `file with ^^ <../strange^^name>`__:
2719 `<../strange^^name>`__
2721 * Unbalanced braces, { or }, will fail (both with \href and \url)::
2723 `file with { <../strange{name>`__
2724 `<../strange{name>`__
2726 Currently, a warning is written to the error output stream.
2728 For correct printing, we can
2730 * use the \href command with "normal" escaped name argument, or
2731 * define a url-command in the preamble ::
2733 \urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
2735 but need to find a way to insert it as href argument.
2737 The following fails::
2739 \href{http://www.w3.org/XML/Schema^^dev}{\fragileURLi}
2741 Use %-replacement like http://nowhere/url_with%28parens%29 ?
2743 -> does not work for file paths (with pdflatex and xpdf).
2746 add-stylesheet option
2747 `````````````````````
2749 From http://article.gmane.org/gmane.text.docutils.devel/3429/
2751 The problem is that since we have a default value, we have to
2752 differentiate between adding another stylesheet and replacing the
2753 default. I suggest that the existing --stylesheet & --stylesheet-path
2754 options keep their semantics to replace the existing settings. We
2755 could introduce new --add-stylesheet & --add-stylesheet-path options,
2756 which accumulate; further --stylesheet/--stylesheet-path options would
2757 clear these lists. The stylesheet or stylesheet_path setting (only
2758 one may be set), plus the added_stylesheets and added_stylesheet_paths
2759 settings, describe the combined styles.
2761 For example, this run will have only one custom stylesheet:
2763 rstpep2html.py --stylesheet-path custom.css ...
2765 This run will use the default stylesheet, and the custom one:
2767 rstpep2html.py --add-stylesheet-path custom.css ...
2769 This run will use the default stylesheet, a custom local stylesheet,
2770 and an external stylesheet:
2772 rstpep2html.py --add-stylesheet-path custom.css \
2773 --add-stylesheet http://www.example.org/external.css ...
2775 This run will use only the second custom stylesheet:
2777 rstpep2html.py --add-stylesheet-path custom.css \
2778 --stylesheet-path second.css ...
2786 * What about if we don't know which Reader and/or Writer we are
2787 going to use? If the Reader/Writer is specified on the
2788 command-line? (Will this ever happen?)
2790 Perhaps have different types of front ends:
2792 a) _`Fully qualified`: Reader and Writer are hard-coded into the
2793 front end (e.g. ``pep2html [options]``, ``pysource2pdf
2796 b) _`Partially qualified`: Reader is hard-coded, and the Writer is
2797 specified a sub-command (e.g. ``pep2 html [options]``,
2798 ``pysource2 pdf [options]``). The Writer is known before option
2799 processing happens, allowing the OptionParser to be built
2800 dynamically. Alternatively, the Writer could be hard-coded and
2801 the Reader specified as a sub-command (e.g. ``htmlfrom pep
2804 c) _`Unqualified`: Reader and Writer are specified as subcommands
2805 (e.g. ``publish pep html [options]``, ``publish pysource pdf
2806 [options]``). A single front end would be sufficient, but
2807 probably only useful for testing purposes.
2809 d) _`Dynamic`: Reader and/or Writer are specified by options, with
2810 defaults if unspecified (e.g. ``publish --writer pdf
2811 [options]``). Is this possible? The option parser would have
2812 to be told about new options it needs to handle, on the fly.
2813 Component-specific options would have to be specified *after*
2814 the component-specifying option.
2816 Allow common options before subcommands, as in CVS? Or group all
2817 options together? In the case of the `fully qualified`_
2818 front ends, all the options will have to be grouped together
2819 anyway, so there's no advantage (we can't use it to avoid
2820 conflicts) to splitting common and component-specific options
2823 * Parameterize help text & defaults somehow? Perhaps a callback? Or
2824 initialize ``settings_spec`` in ``__init__`` or ``init_options``?
2826 * Disable common options that don't apply?
2827 (This should now be easier with ``frontend.filter_settings_spec``.)
2829 * Add ``--section-numbering`` command line option. The "sectnum"
2830 directive should override the ``--no-section-numbering`` command
2833 * Create a single dynamic_ or unqualified_ front end that can be
2840 indent-tabs-mode: nil
2841 sentence-end-double-space: t