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 * Support for `document splitting`_. May require some major code
48 * Support for subdocuments (see `large documents`_).
50 * `Object numbering and object references`_.
52 * `Nested inline markup`_.
54 * `Python Source Reader`_.
56 * The HTML writer needs to be rewritten (or a second HTML writer
57 added) to allow for custom classes, and for arbitrary splitting
60 * Documentation_ of the architecture. Other docs too.
64 * A LaTeX writer making use of (La)TeX's power, so that the rendering
65 of the resulting documents is more easily customizable. (Similar to
66 what you wrote about a new HTML Writer.)
68 * Suitability for `Python module documentation
69 <http://docutils.sf.net/sandbox/README.html#documenting-python>`_.
75 * We don't have consistent (or no) encoding handling for command line
77 <http://thread.gmane.org/gmane.text.docutils.user/2890/focus=2957>.
79 * Improve handling on Windows:
81 - Get graphical installer.
82 - Make rst2html.py an .exe file using py2exe.
86 The user interface is very difficult to use for most Windows users;
87 you can't really expect them to use the command line. We need some
88 kind of GUI that can launch rst2html.py, and save the HTML output to
89 a file, and launch a browser. What's important is that we get
90 settings to work with the GUI. So we need some way to dynamically
91 generate a list of settings for the GUI. The current settings_spec
92 for OptionParser doesn't seem to be usable for this for the
95 - It's biased toward the command line -- there are *two* options for
98 - You cannot have both a one-line description and a longer
99 description for tooltips/help-texts.
101 - It doesn't provide hints for the input type. You cannot easily
102 infer the type of a setting from its validator, because any
103 component can add new validators. In fact, it may be necessary to
104 have both a hint about the input type (e.g. string) and a
105 validator (valid ID), or it may be necessary to have a different
106 set of choices for the CLI (1, INFO, 2, ...) and for the GUI
107 (INFO, WARNING, ...).
109 - It's coupled to the OptionParser. We want to be able to change
110 the underlying system without breaking everything.
112 - It's a bunch of primitive structures. We want an extensible (thus
113 object-oriented) interface.
115 So we probably need to create a class for storing all the settings,
116 and auto-generate the OptionParser data from that.
118 I talked to Stephan Deibel about getting Docutils integrated into
119 Wing IDE. He said it's possible, and he'd be willing to help.
120 There's a scripting interface to Wing, which we'd use. We can
121 dynamically generate a list of preferences and not worry too much
122 about the rendering (from what I understood); Wing's whole GUI is
123 dynamic anyway. The interface could be made usable for other GUIs.
124 For example, we could try to get option support for DocFactory. //
127 * Allow different report levels for STDERR and system_messages inside
130 * Change the docutils-update script (in sandbox/infrastructure), to
131 support arbitrary branch snapshots.
133 * Move some general-interest sandboxes out of individuals'
134 directories, into subprojects?
136 * Add option for file (and URL) access restriction to make Docutils
137 usable in Wikis and similar applications.
139 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
140 settings. These partially solve the problem, allowing or disabling
141 **all** file accesses, but not limited access.
143 * Configuration file handling needs discussion:
145 - There should be some error checking on the contents of config
146 files. How much checking should be done? How loudly should
147 Docutils complain if it encounters an error/problem?
149 - Docutils doesn't complain when it doesn't find a configuration
150 file supplied with the ``--config`` option. Should it? (If yes,
153 * Internationalization:
155 - I18n needs refactoring, the language dictionaries are difficult to
156 maintain. Maybe have a look at gettext or similar tools.
158 (This would make a nice Google Summer of Code project)
160 - Language modules: in accented languages it may be useful to have
161 both accented and unaccented entries in the
162 ``bibliographic_fields`` mapping for versatility.
164 - Add a "--strict-language" option & setting: no English fallback
165 for language-dependent features.
167 Make this the default for output (as opposed to input)?
168 Throw an error with a helpfull message, e.g.
170 Default "contents" title for language %s missing, please specify
175 "attention" title for language %s missing, please use a generic
176 admonition with explicit title.
178 - Add internationalization to _`footer boilerplate text` (resulting
179 from "--generator", "--source-link", and "--date" etc.), allowing
183 * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
185 * In ``docutils.readers.get_reader_class`` (& ``parsers`` &
186 ``writers`` too), should we be importing "standalone" or
187 "docutils.readers.standalone"? (This would avoid importing
188 top-level modules if the module name is not in docutils/readers.
189 Potential nastiness.)
191 * Perhaps store a _`name-to-id mapping file`? This could be stored
192 permanently, read by subsequent processing runs, and updated with
193 new entries. ("Persistent ID mapping"?)
195 * Perhaps the ``Component.supports`` method should deal with
196 individual features ("meta" etc.) instead of formats ("html" etc.)?
198 * Add _`object numbering and object references` (tables & figures).
199 These would be the equivalent of DocBook's "formal" elements.
201 We may need _`persistent sequences`, such as chapter numbers. See
202 `OpenOffice.org XML`_ "fields". Should the sequences be automatic
203 or manual (user-specifyable)?
205 We need to name the objects:
207 - "name" option for the "figure" directive? ::
209 .. figure:: image.png
212 Same for the "table" directive::
214 .. table:: optional title here
224 This would also allow other options to be set, like border
225 styles. The same technique could be used for other objects.
227 A preliminary "table" directive has been implemented, supporting
228 table titles. Perhaps the name should derive from the title.
230 - The object could also be done this way::
234 .. figure:: image.png
236 This may be a more general solution, equally applicable to tables.
237 However, explicit naming using an option seems simpler to users.
239 - Perhaps the figure name could be incorporated into the figure
240 definition, as an optional inline target part of the directive
243 .. figure:: _`figure name` image.png
245 Maybe with a delimiter::
247 .. figure:: _`figure name`: image.png
249 Or some other, simpler syntax.
251 We'll also need syntax for object references. See `OpenOffice.org
252 XML`_ "reference fields":
254 - Parameterized substitutions? For example::
256 See |figure (figure name)| on |page (figure name)|.
258 .. |figure (name)| figure-ref:: (name)
259 .. |page (name)| page-ref:: (name)
261 The result would be::
263 See figure 3.11 on page 157.
265 But this would require substitution directives to be processed at
266 reference-time, not at definition-time as they are now. Or,
267 perhaps the directives could just leave ``pending`` elements
268 behind, and the transforms do the work? How to pass the data
269 through? Too complicated.
271 - An interpreted text approach is simpler and better::
273 See :figure:`figure name` on :page:`figure name`.
275 The "figure" and "page" roles could generate appropriate
276 boilerplate text. The position of the role (prefix or suffix)
277 could also be utilized.
279 See `Interpreted Text`_ below.
281 - We could leave the boilerplate text up to the document::
283 See Figure :fig:`figure name` on page :pg:`figure name`.
285 - Reference boilerplate could be specified in the document
286 (defaulting to nothing)::
289 :prefix-ref: "Figure "
290 :prefix-caption: "Fig. "
293 .. _OpenOffice.org XML: http://xml.openoffice.org/
295 * Think about _`large documents` made up of multiple subdocument
296 files. Issues: continuity (`persistent sequences`_ above),
297 cross-references (`name-to-id mapping file`_ above and `targets in
298 other documents`_ below), splitting (`document splitting`_ below).
300 When writing a book, the author probably wants to split it up into
301 files, perhaps one per chapter (but perhaps even more detailed).
302 However, we'd like to be able to have references from one chapter to
303 another, and have continuous numbering (pages and chapters, as
304 applicable). Of course, none of this is implemented yet. There has
305 been some thought put into some aspects; see `the "include"
306 directive`__ and the `Reference Merging`_ transform below.
308 When I was working with SGML in Japan, we had a system where there
309 was a top-level coordinating file, book.sgml, which contained the
310 top-level structure of a book: the <book> element, containing the
311 book <title> and empty component elements (<preface>, <chapter>,
312 <appendix>, etc.), each with filename attributes pointing to the
313 actual source for the component. Something like this::
316 <title>Title of the Book</title>
317 <preface inrefid="pr01"></preface>
318 <chapter inrefid="ch01"></chapter>
319 <chapter inrefid="ch02"></chapter>
320 <chapter inrefid="ch03"></chapter>
321 <appendix inrefid="ap01"></appendix>
324 (The "inrefid" attribute stood for "insertion reference ID".)
326 The processing system would process each component separately, but
327 it would recognize and use the book file to coordinate chapter and
328 page numbering, and keep a persistent ID to (title, page number)
329 mapping database for cross-references. Docutils could use a similar
330 system for large-scale, multipart documents.
332 __ ../ref/rst/directives.html#including-an-external-document-fragment
348 As I said earlier in chapter :chapter:`Objects.txt`, the
349 reference count gets increased every time a binding is made.
353 As I said earlier in chapter 2, the
354 reference count gets increased every time a binding is made.
356 The ToC in this form doesn't even need to be references to actual
357 reST documents; I'm simply doing it that way for a minimum of
358 future-proofing, in case I do want to add the ability to pick up
359 references within external chapters.
361 Perhaps, instead of ToC (which would overload the "contents"
362 directive concept already in use), we could use "manifest". A
363 "manifest" directive might associate local reference names with
367 intro: Introduction.txt
372 Then the sample becomes::
374 .. include:: manifest.txt
376 As I said earlier in chapter :chapter:`objects`, the
377 reference count gets increased every time a binding is made.
379 * Add support for _`multiple output files` and _`generic data
382 It should be possible for a component to **emit or reference** data
383 to be either **included or referenced** in the output document.
384 Examples of such data are stylesheets or images.
386 For this, we need a "data" object which stores the data either
387 inline or by referring to a file. The Docutils framework is
388 responsible for either:
390 * storing the data in the appropriate location (e.g. in the
391 directory of the output file, or in a user-specified directory)
392 and providing the paths of the stored files to the writer, *or*
394 * providing the data itself to the writer so that it can be embedded
395 in the output document.
397 This approach decouples data handling from the data source (which
398 can either be embedded or referenced) and the destination (which can
399 either be embedded or referenced as well).
401 See <http://article.gmane.org/gmane.text.docutils.devel/3631>.
403 * Add testing for Docutils' front end tools?
405 * Publisher: "Ordinary setup" shouldn't requre specific ordering; at
406 the very least, there ought to be error checking higher up in the
409 ``Publisher.get_settings`` requires that all components be set up
410 before it's called. Perhaps the I/O *objects* shouldn't be set, but
411 I/O *classes*. Then options are set up (``.set_options``), and
412 ``Publisher.set_io`` (or equivalent code) is called with source &
413 destination paths, creating the I/O objects.
415 Perhaps I/O objects shouldn't be instantiated until required. For
416 split output, the Writer may be called multiple times, once for each
417 doctree, and each doctree should have a separate Output object (with
418 a different path). Is the "Builder" pattern applicable here?
420 * Perhaps I/O objects should become full-fledged components (i.e.
421 subclasses of ``docutils.Component``, as are Readers, Parsers, and
422 Writers now), and thus have associated option/setting specs and
425 * Multiple file I/O suggestion from Michael Hudson: use a file-like
426 object or something you can iterate over to get file-like objects.
428 * Add an "--input-language" option & setting? Specify a different
429 language module for input (bibliographic fields, directives) than
430 for output. The "--language" option would set both input & output
433 * Auto-generate reference tables for language-dependent features?
434 Could be generated from the source modules. A special command-line
435 option could be added to Docutils front ends to do this. (Idea from
438 * Enable feedback of some kind from internal decisions, such as
439 reporting the successful input encoding. Modify runtime settings?
440 System message? Simple stderr output?
442 * Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
444 * Merge docs/user/latex.txt info into tools.txt and config.txt?
446 * Add an "--include file" command-line option (config setting too?),
447 equivalent to ".. include:: file" as the first line of the doc text?
448 Especially useful for character entity sets, text transform specs,
451 * Parameterize the Reporter object or class? See the `2004-02-18
452 "rest checking and source path"`_ thread.
454 .. _2004-02-18 "rest checking and source path":
455 http://thread.gmane.org/gmane.text.docutils.user/1112
457 * Add a "disable_transforms" setting? And a dummy Writer subclass
458 that does nothing when its .write() method is called? Would allow
459 for easy syntax checking. See the `2004-02-18 "rest checking and
460 source path"`_ thread.
462 * Add a generic meta-stylesheet mechanism? An external file could
463 associate style names ("class" attributes) with specific elements.
464 Could be generalized to arbitrary output attributes; useful for HTML
465 & XMLs. Aahz implemented something like this in
466 sandbox/aahz/Effective/EffMap.py.
468 * .. _classes for table cells:
470 William Dode suggested that table cells be assigned "class"
471 attributes by columns, so that stylesheets can affect text
472 alignment. Unfortunately, there doesn't seem to be a way (in HTML
473 at least) to leverage the "colspec" elements (HTML "col" tags) by
474 adding classes to them. The resulting HTML is very verbose::
476 <td class="col1">111</td>
477 <td class="col2">222</td>
480 At the very least, it should be an option. People who don't use it
481 shouldn't be penalized by increases in their HTML file sizes.
483 Table rows could also be assigned classes (like odd/even). That
484 would be easier to implement.
486 How should it be implemented?
488 * There could be writer options (column classes & row classes) with
491 * The table directive could grow some options. Something like
492 ":cell-classes: col1 col2 col3" (either must match the number of
493 columns, or repeat to fill?) and ":row-classes: odd even" (repeat
494 to fill; body rows only, or header rows too?).
496 Probably per-table directive options are best. The "class" values
497 could be used by any writer, and applying such classes to all tables
498 in a document with writer options is too broad.
500 * Add file-specific settings support to config files, like::
505 Is this even possible? Should the criterion be the name of the
506 input file or the output file? Alternative (more explicit) syntax::
508 [source_file index.txt]
511 [dest_file index.html]
514 Or rather allow settings configuration from the rst source file?
516 * The "validator" support added to OptionParser is very similar to
517 "traits_" in SciPy_. Perhaps something could be done with them?
518 (Had I known about traits when I was implementing docutils.frontend,
519 I may have used them instead of rolling my own.)
521 .. _traits: http://code.enthought.com/traits/
522 .. _SciPy: http://www.scipy.org/
524 * tools/buildhtml.py: Extend the --prune option ("prune" config
525 setting) to accept file names (generic path) in addition to
526 directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
527 *not* be converted to HTML).
529 * Add support for _`plugins`.
531 * _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
532 /etc/docutils.conf are read as configuration files. Proposal: allow
533 ~/.docutils to be a a configuration *directory*, along with
534 /etc/docutils/ and ./docutils.conf/. Within these directories,
535 check for config.txt files. We can also have subdirectories here,
536 for plugins, S5 themes, components (readers/writers/parsers) etc.
538 Docutils will continue to support configuration files for backwards
541 * Add support for document decorations other than headers & footers?
542 For example, top/bottom/side navigation bars for web pages. Generic
545 Seems like a bad idea as long as it isn't independent from the ouput
546 format (for example, navigation bars are only useful for web pages).
548 * docutils_update: Check for a ``Makefile`` in a directory, and run
549 ``make`` if found? This would allow for variant processing on
550 specific source files, such as running rst2s5.py instead of
553 * Add a "disable table of contents" setting? The S5 writer could set
554 it as a default. Rationale:
556 The ``contents`` (table of contents) directive must not be used
557 [in S5/HTML documents]. It changes the CSS class of headings
558 and they won't show up correctly in the screen presentation.
560 -- `Easy Slide Shows With reStructuredText & S5
561 <../user/slide-shows.html>`_
563 Analogue to the ``sectnum_xform`` setting, it could be used by the
564 latex writer to switch to a LaTeX generated ToC (currently, the latex
565 writer calls it "use_latex_toc").
573 * Add a FAQ entry about using Docutils (with reStructuredText) on a
574 server and that it's terribly slow. See the first paragraphs in
575 <http://article.gmane.org/gmane.text.docutils.user/1584>.
577 * Add document about what Docutils has previously been used for
578 (web/use-cases.txt?).
580 * Improve index in docs/user/config.txt.
586 * Complete `Docutils Runtime Settings <../api/runtime-settings.html>`_.
588 * Improve the internal module documentation (docstrings in the code).
589 Specific deficiencies listed below.
591 - docutils.parsers.rst.states.State.build_table: data structure
592 required (including StringList).
594 - docutils.parsers.rst.states: more complete documentation of parser
597 * docs/ref/doctree.txt: DTD element structural relationships,
598 semantics, and attributes. In progress; element descriptions to be
601 * Document the ``pending`` elements, how they're generated and what
604 * Document the transforms (perhaps in docstrings?): how they're used,
605 what they do, dependencies & order considerations.
607 * Document the HTML classes used by html4css1.py.
609 * Write an overview of the Docutils architecture, as an introduction
610 for developers. What connects to what, why, and how. Either update
611 PEP 258 (see PEPs_ below) or as a separate doc.
613 * Give information about unit tests. Maybe as a howto?
615 * Document the docutils.nodes APIs.
617 * Complete the docs/api/publisher.txt docs.
623 * Creating Docutils Writers
625 * Creating Docutils Readers
627 * Creating Docutils Transforms
629 * Creating Docutils Parsers
631 * Using Docutils as a Library
637 * Complete PEP 258 Docutils Design Specification.
639 - Fill in the blanks in API details.
641 - Specify the nodes.py internal data structure implementation?
643 [Tibs:] Eventually we need to have direct documentation in
644 there on how it all hangs together - the DTD is not enough
645 (indeed, is it still meant to be correct? [Yes, it is.
648 * Rework PEP 257, separating style from spec from tools, wrt Docutils?
649 See Doc-SIG from 2001-06-19/20.
657 * Analyze Tony Ibbs' PySource code.
659 * Analyze Doug Hellmann's HappyDoc project.
661 * Investigate how POD handles literate programming.
663 * Take the best ideas and integrate them into Docutils.
667 * Ask Python-dev for opinions (GvR for a pronouncement) on special
668 variables (__author__, __version__, etc.): convenience vs. namespace
669 pollution. Ask opinions on whether or not Docutils should recognize
672 * If we can detect that a comment block begins with ``##``, a la
673 JavaDoc, it might be useful to indicate interspersed section headers
674 & explanatory text in a module. For example::
676 """Module docstring."""
689 class MyException(Exception): pass
693 * Should standalone strings also become (module/class) docstrings?
694 Under what conditions? We want to prevent arbitrary strings from
695 becomming docstrings of prior attribute assignments etc. Assume
696 that there must be no blank lines between attributes and attribute
697 docstrings? (Use lineno of NEWLINE token.)
699 Triple-quotes are sometimes used for multi-line comments (such as
700 commenting out blocks of code). How to reconcile?
702 * HappyDoc's idea of using comment blocks when there's no docstring
703 may be useful to get around the conflict between `additional
704 docstrings`_ and ``from __future__ import`` for module docstrings.
705 A module could begin like this::
707 #!/usr/bin/env python
709 # :Copyright: whatever
711 """This is the public module docstring (``__doc__``)."""
713 # More docs, in comments.
714 # All comments at the beginning of a module could be
715 # accumulated as docstrings.
716 # We can't have another docstring here, because of the
717 # ``__future__`` statement.
719 from __future__ import division
721 Using the JavaDoc convention of a doc-comment block beginning with
722 ``##`` is useful though. It allows doc-comments and implementation
725 .. _additional docstrings:
726 ../peps/pep-0258.html#additional-docstrings
728 * HappyDoc uses an initial comment block to set "parser configuration
729 values". Do the same thing for Docutils, to set runtime settings on
730 a per-module basis? I.e.::
732 # Docutils:setting=value
734 Could be used to turn on/off function parameter comment recognition
735 & other marginal features. Could be used as a general mechanism to
736 augment config files and command-line options (but which takes
739 * Multi-file output should be divisible at arbitrary level.
741 * Support all forms of ``import`` statements:
743 - ``import module``: listed as "module"
744 - ``import module as alias``: "alias (module)"
745 - ``from module import identifier``: "identifier (from module)"
746 - ``from module import identifier as alias``: "alias (identifier
748 - ``from module import *``: "all identifiers (``*``) from module"
750 * Have links to colorized Python source files from API docs? And
751 vice-versa: backlinks from the colorized source files to the API
754 * In summaries, use the first *sentence* of a docstring if the first
755 line is not followed by a blank line.
758 reStructuredText Parser
759 =======================
761 Also see the `... Or Not To Do?`__ list.
763 __ rst/alternatives.html#or-not-to-do
765 * Recognize unicode whitespace and punctuation. See
766 <http://thread.gmane.org/gmane.text.docutils.user/2765>.
768 * Allow embedded references and not only embedded URIs: ```link text
769 <reference_>`_``; see the second half of
770 <http://article.gmane.org/gmane.text.docutils.devel/3738>.
772 * Another list problem::
778 This ends up as a definition list. This is more of a usability
781 * This case is probably meant to be a nested list, but it ends up as a
782 list inside a block-quote without an error message::
788 It should probably just be an error.
790 The problem with this is that you don't notice easily in HTML that
791 it's not a nested list but a block-quote -- there's not much of a
794 * Treat enumerated lists that are not arabic and consist of only one
795 item in a single line as ordinary paragraphs. See
796 <http://article.gmane.org/gmane.text.docutils.user/2635>.
798 * The citation syntax could use some improvements. See
799 <http://thread.gmane.org/gmane.text.docutils.user/2499> (and the
801 <http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>,
802 and the follow-ups at
803 <http://thread.gmane.org/gmane.text.docutils.user/3087>,
804 <http://thread.gmane.org/gmane.text.docutils.user/3110>,
805 <http://thread.gmane.org/gmane.text.docutils.user/3114>),
806 <http://thread.gmane.org/gmane.text.docutils.user/2443>,
807 <http://thread.gmane.org/gmane.text.docutils.user/2715>,
808 <http://thread.gmane.org/gmane.text.docutils.user/3027>,
809 <http://thread.gmane.org/gmane.text.docutils.user/3120>,
810 <http://thread.gmane.org/gmane.text.docutils.user/3253>.
812 * The current list-recognition logic has too many false positives, as
819 Here ``V.`` is recognized as an enumerator, which leads to
820 confusion. We need to find a solution that resolves such problems
821 without complicating the spec to much.
823 See <http://thread.gmane.org/gmane.text.docutils.user/2524>.
825 * Add indirect links via citation references & footnote references.
828 `Goodger (2005)`_ is helpful.
830 .. _Goodger (2005): [goodger2005]_
831 .. [goodger2005] citation text
833 See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
835 * Change the specification so that more punctuation is allowed
836 before/after inline markup start/end string
837 (http://article.gmane.org/gmane.text.docutils.cvs/3824).
839 * Complain about bad URI characters
840 (http://article.gmane.org/gmane.text.docutils.user/2046) and
841 disallow internal whitespace
842 (http://article.gmane.org/gmane.text.docutils.user/2214).
844 * Create ``info``-level system messages for unnecessarily
845 backslash-escaped characters (as in ``"\something"``, rendered as
846 "something") to allow checking for errors which silently slipped
849 * Add (functional) tests for untested roles.
851 * Add test for ":figwidth: image" option of "figure" directive. (Test
852 code needs to check if PIL is available on the system.)
854 * Add support for CJK double-width whitespace (indentation) &
855 punctuation characters (markup; e.g. double-width "*", "-", "+")?
857 * Add motivation sections for constructs in spec.
859 * Support generic hyperlink references to _`targets in other
860 documents`? Not in an HTML-centric way, though (it's trivial to say
861 ``http://www.example.com/doc#name``, and useless in non-HTML
862 contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
865 * .. _adaptable file extensions:
867 In target URLs, it would be useful to not explicitly specify the
868 file extension. If we're generating HTML, then ".html" is
869 appropriate; if PDF, then ".pdf"; etc. How about using ".*" to
870 indicate "choose the most appropriate filename extension"? For
873 .. _Another Document: another.*
875 What is to be done for output formats that don't *have* hyperlinks?
876 For example, LaTeX targeted at print. Hyperlinks may be "called
877 out", as footnotes with explicit URLs. (Don't convert the links.)
879 But then there's also LaTeX targeted at PDFs, which *can* have
880 links. Perhaps a runtime setting for "*" could explicitly provide
881 the extension, defaulting to the output file's extension.
883 Should the system check for existing files? No, not practical.
885 Handle documents only, or objects (images, etc.) also?
887 If this handles images also, how to differentiate between document
888 and image links? Element context (within "image")? Which image
889 extension to use for which document format? Again, a runtime
890 setting would suffice.
892 This may not be just a parser issue; it may need framework support.
894 Mailing list threads: `Images in both HTML and LaTeX`__ (especially
895 `this summary of Lea's objections`__), `more-universal links?`__,
896 `Output-format-sensitive link targets?`__
898 __ http://thread.gmane.org/gmane.text.docutils.user/1239
899 __ http://article.gmane.org/gmane.text.docutils.user/1278
900 __ http://thread.gmane.org/gmane.text.docutils.user/1915
901 __ http://thread.gmane.org/gmane.text.docutils.user/2438
903 Idea from Jim Fulton: an external lookup table of targets:
905 I would like to specify the extension (e.g. .txt) [in the
906 source, rather than ``filename.*``], but tell the converter to
907 change references to the files anticipating that the files will
912 .. _Another Document: another.txt
914 rst2html.py --convert-links "another.txt bar.txt" foo.txt
916 That is, name the files for which extensions should be converted.
918 Note that I want to refer to original files in the original text
919 (another.txt rather than another.txt) because I want the
920 unconverted text to stand on its own.
922 Note that in most cases, people will be able to use globs::
924 rst2html.py --convert-link-extensions-for "`echo *.txt`" foo.txt
926 It might be nice to be able to use multiple arguments, as in::
928 rst2html.py --convert-link-extensions-for *.txt -- foo.txt
932 > What is to be done for output formats
933 > that don't have hyperlinks?
935 Don't convert the links.
939 > Handle documents only, or objects
940 > (images, etc.) also?
942 No, documents only, but there really is no need for gueswork.
943 Just get the file names as command-line arguments. EIBTI
944 [explicit is better than implicit].
946 For images, we probably need separate solution (which is being
947 worked on), whereas for documents, the issue is basically
948 interlinking between reStructuredText documents. IMO, this cries
949 for support for multiple input and output files, i.e. support for
950 documents which comprise multiple files. Adding adaptable file
951 extensions seems like a kludge. // FW
953 * Implement the header row separator modification to table.el. (Wrote
954 to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
955 support for "=====" header rows. On 2001-08-17 he replied, saying
956 he'd put it on his to-do list, but "don't hold your breath".)
958 * Fix the parser's indentation handling to conform with the stricter
959 definition in the spec. (Explicit markup blocks should be strict or
962 .. XXX What does this mean? Can you elaborate, David?
964 * Make the parser modular. Allow syntax constructs to be added or
965 disabled at run-time. Subclassing is probably not enough because it
966 makes it difficult to apply multiple extensions.
968 * Generalize the "doctest block" construct (which is overly
969 Python-centric) to other interactive sessions? "Doctest block"
970 could be renamed to "I/O block" or "interactive block", and each of
971 these could also be recognized as such by the parser:
976 A block beginning with a "$ " prompt is interpreted as a shell
977 session interactive block. As with Doctest blocks, the
978 interactive block ends with the first blank line, and wouldn't
981 - Root shell sessions::
984 A block beginning with a "# " prompt is interpreted as a root
985 shell session (the user is or has to be logged in as root)
986 interactive block. Again, the block ends with a blank line.
988 Other standard (and unambiguous) interactive session prompts could
989 easily be added (such as "> " for WinDOS).
991 Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
992 "docutils feedback").
994 * Add support for pragma (syntax-altering) directives.
996 Some pragma directives could be local-scope unless explicitly
997 specified as global/pragma using ":global:" options.
999 * Support whitespace in angle-bracketed standalone URLs according to
1000 Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
1003 .. _RFC 2396: http://www.rfc-editor.org/rfc/rfc2396.txt
1005 * Use the vertical spacing of the source text to determine the
1006 corresponding vertical spacing of the output?
1008 * [From Mark Nodine] For cells in simple tables that comprise a
1009 single line, the justification can be inferred according to the
1012 1. If the text begins at the leftmost column of the cell,
1013 then left justification, ELSE
1014 2. If the text begins at the rightmost column of the cell,
1015 then right justification, ELSE
1016 3. Center justification.
1018 The onus is on the author to make the text unambiguous by adding
1019 blank columns as necessary. There should be a parser setting to
1020 turn off justification-recognition (normally on would be fine).
1022 Decimal justification?
1024 All this shouldn't be done automatically. Only when it's requested
1025 by the user, e.g. with something like this::
1032 Otherwise it will break existing documents.
1034 * Generate a warning or info message for paragraphs which should have
1035 been lists, like this one::
1040 * Generalize the "target-notes" directive into a command-line option
1041 somehow? See docutils-develop 2003-02-13.
1043 * Allow a "::"-only paragraph (first line, actually) to introduce a
1044 _`literal block without a blank line`? (Idea from Paul Moore.) ::
1047 This is a literal block
1049 Is indentation enough to make the separation between a paragraph
1050 which contains just a ``::`` and the literal text unambiguous?
1051 (There's one problem with this concession: If one wants a definition
1052 list item which defines the term "::", we'd have to escape it.) It
1053 would only be reasonable to apply it to "::"-only paragraphs though.
1054 I think the blank line is visually necessary if there's text before
1057 The text in this paragraph needs separation
1058 from the literal block following::
1059 This doesn't look right.
1061 * Add new syntax for _`nested inline markup`? Or extend the parser to
1062 parse nested inline markup somehow? See the `collected notes
1063 <rst/alternatives.html#nested-inline-markup>`__.
1065 * Drop the backticks from embedded URIs with omitted reference text?
1066 Should the angle brackets be kept in the output or not? ::
1070 Probably not worth the trouble.
1072 * How about a syntax for alternative hyperlink behavior, such as "open
1073 in a new window" (as in HTML's ``<a target="_blank">``)?
1075 The MoinMoin wiki uses a caret ("^") at the beginning of the URL
1076 ("^" is not a legal URI character). That could work for both inline
1077 and explicit targets::
1079 The `reference docs <^url>`__ may be handy.
1083 This may be too specific to HTML. It hasn't been requested very
1086 * Add an option to add URI schemes at runtime.
1088 * _`Segmented lists`::
1090 : segment : segment : segment
1091 : segment : segment : very long
1093 : segment : segment : segment
1095 The initial colon (":") can be thought of as a type of bullet
1097 We could even have segment titles::
1099 :: title : title : title
1100 : segment : segment : segment
1101 : segment : segment : segment
1103 This would correspond well to DocBook's SegmentedList. Output could
1104 be tabular or "name: value" pairs, as described in DocBook's docs.
1106 * Allow backslash-escaped colons in field names::
1108 :Case Study\: Event Handling: This chapter will be dropped.
1110 * Enable grid _`tables inside XML comments`, where "--" ends comments.
1111 I see three implementation possibilities:
1113 1. Make the table syntax characters into "table" directive options.
1114 This is the most flexible but most difficult, and we probably
1115 don't need that much flexibility.
1117 2. Substitute "~" for "-" with a specialized directive option
1120 3. Make the standard table syntax recognize "~" as well as "-", even
1121 without a directive option. Individual tables would have to be
1122 internally consistent.
1124 Directive options are preferable to configuration settings, because
1125 tables are document-specific. A pragma directive would be another
1126 approach, to set the syntax once for a whole document.
1128 In the meantime, the list-table_ directive is a good replacement for
1129 grid tables inside XML comments.
1131 .. _list-table: ../ref/rst/directives.html#list-table
1133 * Generalize docinfo contents (bibliographic fields): remove specific
1134 fields, and have only a single generic "field"?
1140 We need a generic solution, that's applicable to any output format.
1141 Using a standard, such as MathML_, would be best. (For an overview of
1142 MathML implementations and tests, see e.g. the `mathweb wiki
1143 <http://www.mathweb.org/wiki/MathML>`__.)
1147 MathML in its full XML form was never thought to be usable as an
1148 input format: for a start it is far too verbose as necessitated by
1149 its intention to be expressive.
1151 -- http://www.w3.org/Math/Roadmap/
1153 Hence, with MathML, a different input format is needed. OTOH, LaTeX
1154 math syntax can be used for both, input and internal storage.
1160 * intended for input by a human, widely used, and well documented.
1162 * convertible to all supported output formats (building on
1163 existing extensions like `latex_math`_ (LaTeX2MathML) or the `math
1164 support in Sphinx`_ (see below for `HTML output`_).
1166 * The backtick cannot be used in a math role. Fortunately, in LaTeX
1167 math mode the ``\grave`` macro is used instead of ``\``` for the
1170 * Used for input and storage by the `Math support in Sphinx`_.
1172 * Unicode input supported by the "unicode-math" package for
1173 XeTeX/LuaTeX provides for a improved readability.
1176 Used, e.g., by MultiMarkdown__
1178 __ http://fletcherpenney.net/multimarkdown/
1180 `Unicode Nearly Plain Text Encoding of Mathematics`_
1181 format for lightly marked-up representation of mathematical
1182 expressions in Unicode.
1184 (Unicode Technical Note. Sole responsibility for its contents rests
1185 with the author(s). Publication does not imply any endorsement by
1186 the Unicode Consortium.)
1188 See `the culmination of a relevant discussion
1189 <http://article.gmane.org/gmane.text.docutils.user/118>`__.
1192 Try to be compatible with `Math support in Sphinx`_?
1194 * When the math is only one line of text, it can also be given as a
1199 Clashs with possible use of the directive argument for type of
1200 equation (``align``, ``equation``, ``equation*``, ...) or input
1201 format (``LaTeX``, ``MathML``, ``linear math``, ...).
1203 * Supports multiple equations, which should be separated by a blank
1206 * The ``:label:`` option selects a label for the equation, by which it
1207 can be cross-referenced, and causes an equation number to be issued.
1209 * Option ``:nowrap:`` prevents wrapping of the given math in a
1210 math environment (you have to specify the math environment in the
1216 Which equation environments should be supported by the math directive?
1220 + numbered: "equation"
1221 + unnumbered: "equation*" or ``\[ \]``?
1223 * multiline (test for ``\\`` outside of "array" or "cases")
1225 + numbered: "align" (number every line) or "split" in "equation"
1227 + unnumbered: "align*"
1229 + Sphinx math also supports "gather" (checking for blank lines in
1232 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
1238 There is no native math support in HTML.
1241 is the W3C recommendation. Browser support is finally becoming more
1242 widespread (Firefox, Opera, IE via free MathPlayer_ plugin).
1243 Others can be supported using a CSS MathML profile.
1244 See e.g. `viewing mathematics`__ and the `MathML Browser Test`_
1246 __ http://vismor.com/documents/site_implementation/viewing_mathematics/
1247 .. _MathML Browser Test:
1248 http://eyeasme.com/Joe/MathML/MathML_browser_test.html
1249 .. _MathPlayer: http://www.dessci.com/en/products/mathplayer/
1251 Converters from LaTeX to MathML include `latex_math`_ (LaTeX2MathML)
1252 in the Docutils sandbox, Blahtex_ (C++), MathToWeb_ (Java), TeX4ht_
1253 (TeX based), LaTeXML_ (Perl).
1256 uses CSS to style any MathML tags in an HTML page. Javascript is
1257 then used to tidy up the mathematics in an effort to achive typeset
1258 quality. MathHTML has been tested in Firefox, Safari, Chrome, Opera,
1259 and Internet Explorer 8.
1262 * a JavaScript-based engine for including TEX and MathML in HTML
1263 * Works across multiple browsers and platforms
1264 * Uses HTML/CSS, JavaScript, and unicode fonts for high-quality
1265 typesetting that is scalable and prints at full resolution.
1266 * MathJax is a joint project of the AMS, Design Science, Inc., and
1267 the Society for Industrial and Applied Mathematics.
1268 * There is a `MathJax extension`__ for Sphinx.
1270 __ http://bitbucket.org/kevindunn/sphinx-extension-mathjax
1273 format math in standard HTML enhanced by CSS rules
1274 (Overview__, `Examples and experiments`__):
1276 __ http://www.cs.tut.fi/~jkorpela/math/
1277 __ http://www.zipcon.net/~swhite/docs/math/math.html
1281 (PNG or SVG) like e.g. Wikipedia. (e.g. with dvisvgm_ or the
1282 pure-python MathML->SVG converter SVGMath_)
1288 * MathML_ can be imported by the Math module.
1290 However, putting MathML into an ODP file seems tricky:
1291 http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx
1292 http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx
1295 * OOoLaTeX__: "a set of macros designed to bring the power of LaTeX
1298 __ http://ooolatex.sourceforge.net/
1300 .. _latex_math: ../../../sandbox/jensj/latex_math/
1301 .. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
1302 .. _MathML: http://www.w3.org/TR/MathML2/
1303 .. _MathHTML: http://2020math.org/MathHTML/index.html
1304 .. _itex: http://pear.math.pitt.edu/mathzilla/itex2mmlItex.html
1305 .. _ASCIIMathML: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
1306 .. _MathJax: http://www.mathjax.org/
1307 .. _Unicode Nearly Plain Text Encoding of Mathematics:
1308 http://www.unicode.org/notes/tn28/
1309 .. _dvisvgm: http://dvisvgm.sourceforge.net/
1310 .. _Blahtex: http://gva.noekeon.org/blahtexml/
1311 .. _MathToWeb: http://www.mathtoweb.com/
1312 .. _TeX4ht: http://www.tug.org/applications/tex4ht/mn.html
1313 .. _LaTeXML: http://dlmf.nist.gov/LaTeXML/
1314 .. _SVGMath: http://www.grigoriev.ru/svgmath/
1320 Directives below are often referred to as "module.directive", the
1321 directive function. The "module." is not part of the directive name
1322 when used in a document.
1324 * Make the _`directive interface` object-oriented
1325 (http://article.gmane.org/gmane.text.docutils.user/1871).
1327 * Allow for field lists in list tables. See
1328 <http://thread.gmane.org/gmane.text.docutils.devel/3392>.
1332 Unify table implementations and unify options of table directives
1333 (http://article.gmane.org/gmane.text.docutils.user/1857).
1335 * Allow directives to be added at run-time?
1337 * Use the language module for directive option names?
1339 * Add "substitution_only" and "substitution_ok" function attributes,
1340 and automate context checking?
1342 * Change directive functions to directive classes? Superclass'
1343 ``__init__()`` could handle all the bookkeeping.
1345 * Implement options or features on existing directives:
1347 - Add a "name" option to directives, to set an author-supplied
1350 - All directives that produce titled elements should grow implicit
1351 reference names based on the titles.
1353 - Allow the _`:trim:` option for all directives when they occur in a
1354 substitution definition, not only the unicode_ directive.
1356 .. _unicode: ../ref/rst/directives.html#unicode-character-codes
1358 - Add the "class" option to the unicode directive. For example, you
1359 might want to get characters or strings with borders around them.
1361 - _`images.figure`: "title" and "number", to indicate a formal
1364 - _`parts.sectnum`: "local"?, "refnum"
1366 A "local" option could enable numbering for sections from a
1367 certain point down, and sections in the rest of the document are
1368 not numbered. For example, a reference section of a manual might
1369 be numbered, but not the rest. OTOH, an all-or-nothing approach
1370 would probably be enough.
1372 The "sectnum" directive should be usable multiple times in a
1373 single document. For example, in a long document with "chapter"
1374 and "appendix" sections, there could be a second "sectnum" before
1375 the first appendix, changing the sequence used (from 1,2,3... to
1376 A,B,C...). This is where the "local" concept comes in. This part
1377 of the implementation can be left for later.
1379 A "refnum" option (better name?) would insert reference names
1380 (targets) consisting of the reference number. Then a URL could be
1381 of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
1382 internal references by number? Allow name-based *and*
1383 number-based ids at the same time, or only one or the other (which
1384 would the table of contents use)? Usage issue: altering the
1385 section structure of a document could render hyperlinks invalid.
1387 - _`parts.contents`: Add a "suppress" or "prune" option? It would
1388 suppress contents display for sections in a branch from that point
1389 down. Or a new directive, like "prune-contents"?
1391 Add an option to include topics in the TOC? Another for sidebars?
1392 The "topic" directive could have a "contents" option, or the
1393 "contents" directive" could have an "include-topics" option. See
1394 docutils-develop 2003-01-29.
1396 - _`parts.header` & _`parts.footer`: Support multiple, named headers
1397 & footers? For example, separate headers & footers for odd, even,
1398 and the first page of a document.
1400 This may be too specific to output formats which have a notion of
1405 - Add a ``:parent:`` option for setting the parent's class
1406 (http://article.gmane.org/gmane.text.docutils.devel/3165).
1410 - Option to label lines?
1412 - How about an environment variable, say RSTINCLUDEPATH or
1413 RSTPATH, for standard includes (as in ``.. include:: <name>``)?
1414 This could be combined with a setting/option to allow
1415 user-defined include directories.
1417 - Add support for inclusion by URL? ::
1420 :url: http://www.example.org/inclusion.txt
1422 - Strip blank lines from begin and end of a literal included file or
1423 file section. This would correspond to the way a literal block is
1426 As nodes.literal_block expects (and we have) the text as a string
1427 (rather than a list of lines), using a regexp seems the way.
1429 - _`misc.raw`: add a "destination" option to the "raw" directive? ::
1436 It needs thought & discussion though, to come up with a consistent
1437 set of destination labels and consistent behavior.
1439 And placing HTML code inside the <head> element of an HTML
1440 document is rather the job of a templating system.
1442 - _`body.sidebar`: Allow internal section structure? Adornment
1443 styles would be independent of the main document.
1445 That is really complicated, however, and the document model
1446 greatly benefits from its simplicity.
1448 * Implement directives. Each of the list items below begins with an
1449 identifier of the form, "module_name.directive_function_name". The
1450 directive name itself could be the same as the
1451 directive_function_name, or it could differ.
1455 It has the disadvantage that it's only easily implementable for
1456 HTML, so it's specific to one output format.
1458 (For non-HTML writers, the imagemap would have to be replaced with
1461 - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
1463 - _`parts.citations`: See `Footnote & Citation Gathering`_.
1465 - _`misc.language`: Specify (= change) the language of a document at
1468 - _`misc.settings`: Set any(?) Docutils runtime setting from within
1469 a document? Needs much thought and discussion.
1471 Security concerns need to be taken into account (it shouldn't be
1472 possible to enable ``file_insertion_enabled`` from within a
1473 document), and settings that only would have taken effect before
1474 the directive (like ``tab-width``) shouldn't be accessible either.
1476 See this sub-thread:
1477 <http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649>
1479 - _`misc.gather`: Gather (move, or copy) all instances of a specific
1480 element. A generalization of the "endnotes" & "citations" ideas.
1482 - Add a custom "directive" directive, equivalent to "role"? For
1487 .. class:: incremental
1491 "``.. incr::``" above is equivalent to "``.. class:: incremental``".
1495 .. directive:: printed-links
1501 :class: print-inline
1503 This acts like macros. The directive contents will have to be
1504 evaluated when referenced, not when defined.
1506 * Needs a better name? "Macro", "substitution"?
1507 * What to do with directive arguments & options when the
1508 macro/directive is referenced?
1510 - Make the meaning of block quotes overridable? Only a 1-shot
1511 though; doesn't solve the general problem.
1513 - .. _conditional directives:
1515 Docutils already has the ability to say "use this content for
1516 Writer X" (via the "raw" directive), but it doesn't have the
1517 ability to say "use this content for any Writer other than X". It
1518 wouldn't be difficult to add this ability though.
1520 My first idea would be to add a set of conditional directives.
1521 Let's call them "writer-is" and "writer-is-not" for discussion
1522 purposes (don't worry about implemention details). We might
1525 .. writer-is:: text-only
1541 .. figure:: protocol_stack.eps
1543 .. writer-is-not:: text-only pdf
1545 .. figure:: protocol_stack.png
1547 This could be an interface to the Filter transform
1548 (docutils.transforms.components.Filter).
1550 The ideas in `adaptable file extensions`_ above may also be
1553 SVG's "switch" statement may provide inspiration.
1555 Here's an example of a directive that could produce multiple
1556 outputs (*both* raw troff pass-through *and* a GIF, for example)
1557 and allow the Writer to select. ::
1564 %sum from i=o to inf c sup i~=~lim from {m -> inf}
1565 sum from i=0 to m sup i%
1570 - _`body.example`: Examples; suggested by Simon Hefti. Semantics as
1571 per Docbook's "example"; admonition-style, numbered, reference,
1572 with a caption/title.
1574 - _`body.index`: Index targets.
1576 See `Index Entries & Indexes
1577 <./rst/alternatives.html#index-entries-indexes>`__.
1579 - _`body.literal`: Literal block, possibly "formal" (see `object
1580 numbering and object references`_ above). Possible options:
1582 - "highlight" a range of lines
1584 - include only a specified range of lines
1586 - "number" or "line-numbers"
1588 - "styled" could indicate that the directive should check for
1589 style comments at the end of lines to indicate styling or
1592 Specific derivatives (i.e., a "python-interactive" directive)
1593 could interpret style based on cues, like the ">>> " prompt and
1594 "input()"/"raw_input()" calls.
1596 See docutils-users 2003-03-03.
1598 - _`body.listing`: Code listing with title (to be numbered
1599 eventually), equivalent of "figure" and "table" directives.
1601 - _`colorize.python`: Colorize Python code. Fine for HTML output,
1602 but what about other formats? Revert to a literal block? Do we
1603 need some kind of "alternate" mechanism? Perhaps use a "pending"
1604 transform, which could switch its output based on the "format" in
1605 use. Use a factory function "transformFF()" which returns either
1606 "HTMLTransform()" instance or "GenericTransform" instance?
1608 If we take a Python-to-HTML pretty-printer and make it output a
1609 Docutils internal doctree (as per nodes.py) instead of HTML, then
1610 each output format's stylesheet (or equivalent) mechanism could
1611 take care of the rest. The pretty-printer code could turn this
1614 <literal_block xml:space="preserve">
1615 print 'This is Python code.'
1620 into something like this ("</>" is end-tag shorthand)::
1622 <literal_block xml:space="preserve" class="python">
1623 <keyword>print</> <string>'This is Python code.'</>
1624 <keyword>for</> <identifier>i</> <keyword
1625 >in</> <expression>range(10)</>:
1626 <keyword>print</> <expression>i</>
1629 But I'm leaning toward adding a single new general-purpose
1630 element, "phrase", equivalent to HTML's <span>. Here's the
1631 example rewritten using the generic "phrase"::
1633 <literal_block xml:space="preserve" class="python">
1634 <phrase class="keyword">print</> <phrase
1635 class="string">'This is Python code.'</>
1636 <phrase class="keyword">for</> <phrase
1637 class="identifier">i</> <phrase class="keyword">in</> <phrase
1638 class="expression">range(10)</>:
1639 <phrase class="keyword">print</> <phrase
1640 class="expression">i</>
1643 It's more verbose but more easily extensible and more appropriate
1644 for the case at hand. It allows us to edit style sheets to add
1645 support for new formats, not the Docutils code itself.
1647 Perhaps a single directive with a format parameter would be
1650 .. colorize:: python
1652 print 'This is Python code.'
1656 But directives can have synonyms for convenience. "format::
1657 python" was suggested, but "format" seems too generic.
1659 - _`pysource.usage`: Extract a usage message from the program,
1660 either by running it at the command line with a ``--help`` option
1661 or through an exposed API. [Suggestion for Optik.]
1667 Interpreted text is entirely a reStructuredText markup construct, a
1668 way to get around built-in limitations of the medium. Some roles are
1669 intended to introduce new doctree elements, such as "title-reference".
1670 Others are merely convenience features, like "RFC".
1672 All supported interpreted text roles must already be known to the
1673 Parser when they are encountered in a document. Whether pre-defined
1674 in core/client code, or in the document, doesn't matter; the roles
1675 just need to have already been declared. Adding a new role may
1676 involve adding a new element to the DTD and may require extensive
1677 support, therefore such additions should be well thought-out. There
1678 should be a limited number of roles.
1680 The only place where no limit is placed on variation is at the start,
1681 at the Reader/Parser interface. Transforms are inserted by the Reader
1682 into the Transformer's queue, where non-standard elements are
1683 converted. Once past the Transformer, no variation from the standard
1684 Docutils doctree is possible.
1686 An example is the Python Source Reader, which will use interpreted
1687 text extensively. The default role will be "Python identifier", which
1688 will be further interpreted by namespace context into <class>,
1689 <method>, <module>, <attribute>, etc. elements (see pysource.dtd),
1690 which will be transformed into standard hyperlink references, which
1691 will be processed by the various Writers. No Writer will need to have
1692 any knowledge of the Python-Reader origin of these elements.
1694 * Add explicit interpreted text roles for the rest of the implicit
1695 inline markup constructs: named-reference, anonymous-reference,
1696 footnote-reference, citation-reference, substitution-reference,
1697 target, uri-reference (& synonyms).
1699 * Add directives for each role as well? This would allow indirect
1702 This text contains |nested inline markup|.
1704 .. |nested inline markup| emphasis::
1706 nested ``inline`` markup
1710 - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
1711 around role contents.
1713 For example, the following reStructuredText source ... ::
1715 .. role:: red(raw-formatting)
1717 :html: <font color="red">
1718 :latex: {\color{red}
1725 ... will yield the following document fragment::
1729 <inline classes="red">
1732 <raw format="latex">
1734 <inline classes="red">
1738 <raw format="latex">
1741 Possibly without the intermediate "inline" node.
1743 - _`"acronym" and "abbreviation"`: Associate the full text with a
1744 short form. Jason Diamond's description:
1746 I want to translate ```reST`:acronym:`` into ``<acronym
1747 title='reStructuredText'>reST</acronym>``. The value of the
1748 title attribute has to be defined out-of-band since you can't
1749 parameterize interpreted text. Right now I have them in a
1750 separate file but I'm experimenting with creating a directive
1751 that will use some form of reST syntax to let you define them.
1753 Should Docutils complain about undefined acronyms or
1756 What to do if there are multiple definitions? How to
1757 differentiate between CSS (Content Scrambling System) and CSS
1758 (Cascading Style Sheets) in a single document? David Priest
1761 The short answer is: you don't. Anyone who did such a thing
1762 would be writing very poor documentation indeed. (Though I
1763 note that `somewhere else in the docs`__, there's mention of
1764 allowing replacement text to be associated with the
1765 abbreviation. That takes care of the duplicate
1766 acronyms/abbreviations problem, though a writer would be
1767 foolish to ever need it.)
1769 __ `inline parameter syntax`_
1771 How to define the full text? Possibilities:
1773 1. With a directive and a definition list? ::
1780 Docstring Processing System
1782 Would this list remain in the document as a glossary, or would
1783 it simply build an internal lookup table? A "glossary"
1784 directive could be used to make the intention clear.
1785 Acronyms/abbreviations and glossaries could work together.
1787 Then again, a glossary could be formed by gathering individual
1788 definitions from around the document.
1790 2. Some kind of `inline parameter syntax`_? ::
1792 `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
1793 see is what you get>`:acronym: plaintext markup.
1795 .. _inline parameter syntax:
1796 rst/alternatives.html#parameterized-interpreted-text
1798 3. A combination of 1 & 2?
1800 The multiple definitions issue could be handled by establishing
1801 rules of priority. For example, directive-based lookup tables
1802 have highest priority, followed by the first inline definition.
1803 Multiple definitions in directive-based lookup tables would
1804 trigger warnings, similar to the rules of `implicit hyperlink
1807 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
1809 4. Using substitutions? ::
1811 .. |reST| acronym:: reST
1812 :text: reStructuredText
1814 What do we do for other formats than HTML which do not support
1815 tool tips? Put the full text in parentheses?
1817 - "figure", "table", "listing", "chapter", "page", etc: See `object
1818 numbering and object references`_ above.
1820 - "glossary-term": This would establish a link to a glossary. It
1821 would require an associated "glossary-entry" directive, whose
1822 contents could be a definition list::
1831 This would allow entries to be defined anywhere in the document,
1832 and collected (via a "glossary" directive perhaps) at one point.
1838 The number of doctree nodes can be reduced by "normalizing" some related
1839 nodes. This makes the document model and the writers somewhat simpler.
1841 * The "doctest" element should go away. The construct could simply be
1842 a front-end to generic literal blocks. We could immediately (in 0.7)
1843 remove the doctest node from the doctree, but leave the
1844 syntax in reST. The reST parser could represent doctest blocks as
1845 literal blocks with a class attribute. The syntax could be left in
1846 reST (for a set period of time?).
1848 * Always use _`transforms.writer_aux.Admonitions` to "normalize" special
1849 admonitions (note, hint, warning, ...). There is no need to keep them in
1850 the doctree specification.
1852 Keep the special admonition directives in reStructuredText syntax?
1854 * _`Line numbers` and "source" in system messages:
1856 - Add "source" and "line" keyword arguments to all Reporter calls?
1857 This would require passing source/line arguments along all
1858 intermediate functions (where currently only `line` is used).
1860 Or rather specify "line" only if actually needed?
1862 Currently, `document.reporter` uses a state machine instance to
1863 determine the "source" and "line" info from
1864 `statemachine.input_lines` if not given explicitely. Except for
1865 special cases, the "line" argument is not needed because,
1866 `document.statemachine` keeps record of the current line number.
1868 - For system messages generated after the parsing is completed (i.e. by
1869 transforms or the writer) "line" info must be present in the doctree
1872 Elements' .line assignments should be checked. (Assign to .source
1873 too? Add a set_info method? To what?)
1875 The "source" (and line number in the source) can either be added
1876 explicitely to the elements or determined from the “raw” line
1877 number by `document.statemachine.get_source_and_line`.
1879 - Some line numbers in elements are not being set properly
1880 (explicitly), just implicitly/automatically. See rev. 1.74 of
1881 docutils/parsers/rst/states.py for an example of how to set.
1883 - The line numbers of definition list items are wrong::
1885 $ rst2pseudoxml.py --expose-internal-attribute line
1894 <document source="<stdin>">
1896 <definition_list_item internal:line="3">
1900 <paragraph internal:line="2">
1903 <definition_list_item internal:line="6">
1907 <paragraph internal:line="6">
1913 Quite a few nodes are getting a "None" source attribute as well. In
1914 particular, see the bodies of definition lists.
1918 Unimplemented Transforms
1919 ========================
1921 * _`Footnote & Citation Gathering`
1923 Collect and move footnotes & citations to the end of a document or the
1924 place of a "footnotes" or "citations" directive
1925 (see `<./ref/rst/directives.html>_`)
1928 Collect all footnotes that are referenced in the document before the
1929 directive (and after an eventually preceding ``.. footnotes::``
1930 directive) and insert at this place.
1932 Allows "endnotes" at a configurable place.
1935 Collect citations that are referenced ...
1939 a) defined in the document as citation elements
1941 b) auto-generated from entries in a bibliographic database.
1943 + based on bibstuff_?
1944 + also have a look at
1946 * CrossTeX_, a backwards-compatible, improved bibtex
1947 re-implementation in Python (including HTML export).
1948 (development stalled since 2 years)
1950 * Pybtex_,a drop-in replacement for BibTeX written in Python.
1952 * BibTeX styles & (experimental) pythonic style API.
1953 * Database in BibTeX, BibTeXML and YAML formats.
1954 * full Unicode support.
1955 * Write to TeX, HTML and plain text.
1957 * Automatically insert a "References" heading?
1959 .. _CrossTeX: http://www.cs.cornell.edu/people/egs/crosstex/
1960 .. _Pybtex: http://pybtex.sourceforge.net/
1962 * _`Reference Merging`
1964 When merging two or more subdocuments (such as docstrings),
1965 conflicting references may need to be resolved. There may be:
1967 * duplicate reference and/or substitution names that need to be made
1969 * duplicate footnote numbers that need to be renumbered.
1971 Should this be done before or after reference-resolving transforms
1972 are applied? What about references from within one subdocument to
1975 * _`Document Splitting`
1977 If the processed document is written to multiple files (possibly in
1978 a directory tree), it will need to be split up. Internal references
1979 will have to be adjusted.
1981 (HTML only? Initially, yes. Eventually, anything should be
1986 - Insert a "destination" attribute into the root element of each
1987 split-out document, containing the path/filename. The Output
1988 object or Writer will recognize this attribute and split out the
1989 files accordingly. Must allow for common headers & footers,
1990 prev/next, breadcrumbs, etc.
1992 - Transform a single-root document into a document containing
1993 multiple subdocuments, recursively. The content model of the
1994 "document" element would have to change to::
1997 ( (title, subtitle?)?,
1999 (docinfo, transition?)?,
2003 (I.e., add the last line -- 0 or more document elements.)
2005 Let's look at the case of hierarchical (directories and files)
2006 HTML output. Each document element containing further document
2007 elements would correspond to a directory (with an index.html file
2008 for the content preceding the subdocuments). Each document
2009 element containing no subdocuments (i.e., structure model elements
2010 only) corresponds to a concrete file with no directory.
2012 The natural transform would be to map sections to subdocuments,
2013 but possibly only a given number of levels deep.
2017 If a document is split up, each segment will need navigation links:
2018 parent, children (small TOC), previous (preorder), next (preorder).
2019 Part of `Document Splitting`_?
2021 * _`List of System Messages`
2023 The ``system_message`` elements are inserted into the document tree,
2024 adjacent to the problems themselves where possible. Some (those
2025 generated post-parse) are kept until later, in
2026 ``document.messages``, and added as a special final section,
2027 "Docutils System Messages".
2029 Docutils could be made to generate hyperlinks to all known
2030 system_messages and add them to the document, perhaps to the end of
2031 the "Docutils System Messages" section.
2033 Fred L. Drake, Jr. wrote:
2035 I'd like to propose that both parse- and transformation-time
2036 messages are included in the "Docutils System Messages" section.
2037 If there are no objections, I can make the change.
2039 The advantage of the current way of doing things is that parse-time
2040 system messages don't require a transform; they're already in the
2041 document. This is valuable for testing (unit tests,
2042 tools/quicktest.py). So if we do decide to make a change, I think
2043 the insertion of parse-time system messages ought to remain as-is
2044 and the Messages transform ought to move all parse-time system
2045 messages (remove from their originally inserted positions, insert in
2046 System Messages section).
2048 * _`Index Generation`
2052 Convert quotes and dashes to typographically correct entities.
2053 Sphinx does this with ``smartypants.py``.
2055 Write a generic version that uses Unicode chars
2056 (let the writer replace these if required).
2061 * Make it easier to find out fragment names (#foo-bar) of ``_`inline
2062 targets```. Currently you have to either look at the source or
2065 For example, we could add support for self-referencing targets
2066 (i.e. inline targets would [unobtrusively] link to themselves, so
2067 that you can just click them and then copy the address). Or we
2068 could add support for titles that display the fragment name (as in
2069 <http://subversion.tigris.org/mailing-list-guidelines.html>; just
2070 hover the paragraphs).
2072 Either way it should be optional and deactivated by default.
2074 This would be useful for documents like Docutils' bug list or to-do
2077 * Make the _`list compacting` logic more generic: For example, allow
2078 for literal blocks or line blocks inside of compact list items.
2080 This is not implementable as long as list compacting is done by
2081 omitting ``<p>`` tags. List compacting would need to be done by
2082 adjusting CSS margins instead.
2084 * Idea for field-list rendering: hanging indent::
2086 Field name (bold): First paragraph of field body begins
2087 with the field name inline.
2089 If the first item of a field body is not a paragraph,
2090 it would begin on the following line.
2092 * Add more support for <link> elements, especially for navigation
2095 The framework does not have a notion of document relationships, so
2096 probably raw.destination_ should be used.
2098 We'll have framework support for document relationships when support
2099 for `multiple output files`_ is added. The HTML writer could
2100 automatically generate <link> elements then.
2102 .. _raw.destination: misc.raw_
2104 * Base list compaction on the spacing of source list? Would require
2105 parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
2107 * Add a tool tip ("title" attribute?) to footnote back-links
2108 identifying them as such. Text in Docutils language module.
2114 * Remove the generic style information (duplicated from html4css1.css)
2115 from pep.css to avoid redundancy.
2117 Needs support for multiple stylesheets in the PEP writer
2118 (is this inherited from HTML?).
2124 * Add a way to begin an untitled slide.
2126 * Add a way to begin a new slide, continuation, using the same title
2127 as the previous slide? (Unnecessary?) You need that if you have a
2128 lot of items in one section which don't fit on one slide.
2130 Maybe either this item or the previous one can be realized using
2133 * Have a timeout on incremental items, so the colour goes away after 1
2136 * Add an empty, black last slide (optionally). Currently the handling
2137 of the last slide is not very nice, it re-cycles through the
2138 incremental items on the last slide if you hit space-bar after the
2141 * Add a command-line option to disable advance-on-click.
2143 * Add a speaker's master document, which would contain a small version
2144 of the slide text with speaker's notes interspersed. The master
2145 document could use ``target="whatever"`` to direct links to a
2146 separate window on a second monitor (e.g., a projector).
2148 .. Note:: This item and the following items are partially
2149 accomplished by the S5 1.2 code (currently in alpha), which has
2150 not yet been integrated into Docutils.
2152 * Speaker's notes -- how to intersperse? Could use reST comments
2153 (".."), but make them visible in the speaker's master document. If
2154 structure is necessary, we could use a "comment" directive (to avoid
2155 nonsensical DTD changes, the "comment" directive could produce an
2156 untitled topic element).
2158 The speaker's notes could (should?) be separate from S5's handout
2161 * The speaker's master document could use frames for easy navigation:
2162 TOC on the left, content on the right.
2164 - It would be nice if clicking in the TOC frame simultaneously
2165 linked to both the speaker's notes frame and to the slide window,
2166 synchronizing both. Needs JavaScript?
2168 - TOC would have to be tightly formatted -- minimal indentation.
2170 - TOC auto-generated, as in the PEP Reader. (What if there already
2171 is a "contents" directive in the document?)
2173 - There could be another frame on the left (top-left or bottom-left)
2174 containing a single "Next" link, always pointing to the next slide
2175 (synchronized, of course). Also "Previous" link? FF/Rew go to
2176 the beginning of the next/current parent section? First/Last
2177 also? Tape-player-style buttons like ``|<< << < > >> >>|``?
2182 Add epub as an output format.
2184 Pack the output of a HTML writer and supporting files (e.g. images)
2185 into one single epub document.
2187 epub is an open file format for ebooks based on HTML, specified by the
2188 `International Digital Publishing Forum`_. Thus, documents in epub
2189 format are suited to be read with `electronic reading devices`_. The
2190 epub format comprises:
2192 * `Open Publication Structure (OPS)
2193 <http://www.idpf.org/2007/ops/OPS_2.0_final_spec.html>`_
2194 * `Open Packaging Format (OPF)
2195 <http://www.idpf.org/2007/opf/OPF_2.0_final_spec.html>`_
2196 * `OEBPS Container Format (OCF)
2197 <http://www.idpf.org/ocf/ocf1.0/download/ocf10.htm>`_
2201 There is a project for epub support with sphinx providing a
2202 (hopefully) reusable framework.
2204 .. _rst2epub: http://bitbucket.org/wierob/rst2epub/
2205 .. _International Digital Publishing Forum: http://www.idpf.org/
2206 .. _electronic reading devices:
2207 http://en.wikipedia.org/wiki/List_of_e-book_readers
2213 Also see the Problems__ section in the `latex writer documentation`_.
2215 __ ../user/latex.html#problems
2217 .. _latex writer documentation: ../user/latex.html
2220 ../../../sandbox/latex-variants/README.html
2225 * A multirow cell in a table expects empty cells in the spanned rows while
2226 the doctree contains only the remaining cells ("Exchange Table Model", see
2227 docs/ref/soextblx.dtd).
2229 Needs bookkeeping of "open" multirow cells (how many how long) and
2230 insertion of additional '&'s.
2232 See `<../../test/functional/input/data/latex.txt>`__
2234 * Too deeply nested lists fail: generate a warning and provide
2237 * Spaces in inline literal text::
2240 spacing between the words of this sentence (words
2241 should be grouped in pairs).
2243 Discuss the desired behaviour and implement a consistent one.
2245 * An enumerated list in the docinfo fails (\newcounter definition inside
2248 Generate clean and configurable LaTeX source
2249 ----------------------------------------------
2251 * Check the generated source with package `nag`.
2253 Configurable placement of figure and table floats
2254 `````````````````````````````````````````````````
2256 * Special class argument to individually place figures?
2260 placement-<optional arg> -> \figure[<optional arg>]{...}
2262 e.g. ``.. class:: placement-htb``,
2267 :h: place-here-if-possible
2270 :p: place-on-extra-page
2272 e.g.: ``.. class:: place-here-if-possible place-top place-bottom``
2274 Maybe support both variants?
2277 LaTeX constructs and packages instead of re-implementations
2278 ```````````````````````````````````````````````````````````
2280 Which packages do we want to use?
2282 + base and "recommended" packages
2284 (packages that should be in a "reasonably sized and reasonably modern
2285 LaTeX installation like the `texlive-latex-recommended` Debian package,
2288 + No "fancy" or "exotic" requirements.
2290 + pointers to advanced packages and their use in the `latex writer
2293 * ``alltt`` environment for literal block.
2297 + True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
2298 (also for target-footnotes):
2300 - attach footnote text to footnote-symobol node
2301 - write \footnote{<footnote text>}
2302 - consider cases where LaTeX does not support footnotes
2303 (inside tables, headings, ...)?
2304 - consider multiple footnote refs to common footnote text.
2308 If the symbol you want is not one of the ones listed, you'll need to
2309 redefine ``\@fnsymbol`` and add it, e.g. perhaps like::
2311 \def\@fnsymbol#1{\ifcase#1\hbox{}\or *\or \dagger\or \ddagger\or
2312 \mathchar "278\or \mathchar "27B\or \|\or **\or \dagger\dagger \or
2313 \ddagger\ddagger \or \mathchar"27C \else\@ctrerr\fi\relax}
2315 which would allow \symbolfootnote[10]{footnote} to have a club as its
2318 + document customization (links to how-to and packages):
2320 .. Footnote packages:
2322 :footnote: texlive-latex-recommended % savenotes environment
2323 :footmisc: texlive-latex-extra % formatting options
2324 :manyfoot: texlive-latex-extra
2325 :bigfoot: texlive-latex-extra
2326 :perpage: texlive-latex-extra
2327 :ftnxtra: new on CTAN
2328 fixes the issue of footnote inside \caption{},
2329 tabular environment and \section{} like commands.
2333 http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf
2337 `Footnotes whose texts are identical
2338 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=repfootnote>`__
2340 * label per hand or use footmisc
2342 `More than one sequence of footnotes
2343 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot>`__
2347 `Footnotes in tables
2348 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab>`__
2350 * `tabularx` and longtable allow footnotes.
2351 * `footnote` provides a "savenotes" environment which collects all
2352 footnotes and emits them at ``end{savenotes}``
2354 `Footnotes in LaTeX section headings
2355 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect>`__
2357 * Take advantage of the fact that the mandatory argument doesn't
2358 move if the optional argument is present::
2360 \section[title] {title\footnote{title ftnt}}
2362 * Use the footmisc package, with package option stable - this modifies
2363 footnotes so that they softly and silently vanish away if used in a
2368 `Footnotes numbered per page
2369 <http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footnpp>`__
2371 * perpage provides a general mechanism for resetting counters per page
2372 * footmisc provides a package option perpage
2374 * enumeration environment, field list
2376 * use `mdwlist` from texlive-latex-recommended?
2378 * use `eqlist` (texlive-latex-extra) for field-lists?
2381 * ``--use-latex-when-possible`` »super option« that would set the
2384 --no-section-numbering
2387 --use-latex-abstract
2388 --use-latex-footnotes
2389 --use-latex-citations
2391 ? (My preference is to default to use-latex-* whenever possible [GM])
2397 * Use italic instead of slanted for titlereference?
2399 * Start a new paragraph after lists (as currently)
2400 or continue (no blank line in source, no parindent in output)?
2404 * continue if the `compound paragraph`_ directive is used, or
2405 * force a new paragraph with an empty comment.
2407 * Sidebar handling (environment with `framed`, `marginnote`, `wrapfig`,
2410 * Use optionlist for docinfo?
2412 * Keep literal-blocks together on a page, avoid pagebreaks.
2414 Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
2417 Should be possible with ``--literal-block-env==lstlistings`` and some
2420 * More space between title and subtitle? ::
2423 + \\[0.5em] % subtitle%
2425 .. _PSNFSS documentation:
2426 http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
2427 .. _compound paragraph:
2428 ../ref/rst/directives.html#compound-paragraph
2430 http://mirror.ctan.org/help/Catalogue/entries/fixltx2e.html
2435 * Improve/simplify logic to set the column width in the output.
2437 + Assumed reST line length for table width setting configurable, or
2438 + use `ltxtable` (a combination of `tabularx` (auto-width) and
2439 `longtable` (page breaks)), or
2440 + use tabularx column type ``X`` and let LaTeX decide width, or
2443 * csv-tables do not have a colwidth.
2445 * Add more classes or options, e.g. for
2447 + column width set by latex,
2448 + horizontal alignment and rules.
2449 + long table vs. tabular (see next item).
2451 * Use tabular instead of longtable for tables in legends or generally
2454 Alternatively, default to tabular and use longtable only if specified
2455 by config setting or class argument (analogue to booktable)?
2457 * Table heads and footer for longtable (firstpage lastpage ..)?
2459 * In tools.txt the option tables right column, there should be some more
2460 spacing between the description and the next paragraph "Default:".
2462 * Paragraph separation in tables is hairy.
2463 see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
2465 - The strut solution did not work.
2466 - setting extrarowheight added ad top of row not between paragraphs in
2467 a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
2468 - baselineskip/stretch does not help.
2470 * Should there be two hlines after table head and on table end?
2472 * Place titled tables in a float ('table' environment)?
2474 The 'table', 'csv-table', and 'list-table' directives support an (optional)
2475 table title. In analogy to the 'figure' directive this should map to a
2479 http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=tabulary
2482 Image and figure directives
2483 ```````````````````````````
2485 * compare the test case in:
2487 + `<../../test/functional/input/data/standard.txt>`__
2488 + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
2489 + `<../../test/functional/expected/standalone_rst_latex.tex>`__
2491 * According to the HTML standard
2492 http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG a right- or
2493 left-aligned image should be floated alongside the paragraph.
2495 + Use this default also for LaTeX?
2497 + Wrap text around figures/images with class argument "wrap"
2498 (like the odt writer)?
2500 Use `wrapfig` (or other recommended) package.
2502 * support more graphic formats (especially SVG, the only standard
2503 vector format for HTML)
2505 There is a `SWF package`_ at CTAN.
2508 http://mirror.ctan.org/macros/latex/contrib/flashmovie
2514 * support "figwidth" argument for figures.
2516 As the 'figwidth' argument is still ignored and the "natural width" of
2517 a figure in LaTeX is 100 % of the text width, setting the 'align'
2518 argument has currently no effect on the LaTeX output.
2521 * Let `meta` directive insert PDF-keywords into header?
2523 * Multiple author entries in docinfo (same thing as in html).
2526 * Consider supporting the "compact" option and class argument (from
2527 rst2html) as some lists look better compact and others need the space.
2529 * Better citation support
2530 (see `Footnote & Citation Gathering`_).
2532 * If ``use-latex-citations`` is used, a bibliography is inserted right at the
2533 end of the document.
2535 Put in place of the to-be-implemented "citations" directive
2536 (see `Footnote & Citation Gathering`_).
2542 The `LyX <http://www.lyx.org>`_ document processor has a comprehensive
2543 Unicode to LaTeX conversion feature with a file called ``unicodesymbols``
2544 that lists LaTeX counterparts for a wide range of Unicode characters.
2546 * Use this in the LaTeXTranslator?
2547 Think of copyright issues!
2549 * The "ucs" package has many translations in ...doc/latex/ucs/config/
2551 * The bibstuff_ tool ships a `latex_codec` Python module!
2553 .. _bibstuff: http://code.google.com/p/bibstuff/
2555 Allow choice between utf8 (standard) and utf8x (extended) encodings
2556 ```````````````````````````````````````````````````````````````````
2558 * Allow the user to select *utf8* or *utf8x* LaTeX encoding. (Docutil's
2559 output encoding becomes LaTeX's input encoding.)
2561 The `ucs` package provides extended support for UTF-8 encoding in LaTeX
2562 via the `inputenc`-option ``utf8x``. It is, however, a non-standard
2563 extension and no longer developed.
2566 a) Python has 4 names for the UTF-8 encoding (``utf_8, U8, UTF, utf8``)
2567 give a special meaning to one of the aliases,
2569 b) scan "stylesheets" and "latex-preamble" options and use ``utf8x``
2570 if it contains ``ucs``
2575 * Glyphs missing in the font are left out in the PDF without warning
2576 (e.g. ⇔ left-right double arrow in the functional test output).
2578 * Disable word-wrap (hyphenation) in literal text locally with
2579 ``providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}``?
2585 * ^^ LaTeX's special syntax for characters results in "strange" replacements
2586 (both with \href and \url).
2588 `file with ^^ <../strange^^name>`__:
2589 `<../strange^^name>`__
2591 * Unbalanced braces, { or }, will fail (both with \href and \url)::
2593 `file with { <../strange{name>`__
2594 `<../strange{name>`__
2596 Currently, a warning is written to the error output stream.
2598 For correct printing, we can
2600 * use the \href command with "normal" escaped name argument, or
2601 * define a url-command in the preamble ::
2603 \urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
2605 but need to find a way to insert it as href argument.
2607 The following fails::
2609 \href{http://www.w3.org/XML/Schema^^dev}{\fragileURLi}
2611 Use %-replacement like http://nowhere/url_with%28parens%29 ?
2613 -> does not work for file paths (with pdflatex and xpdf).
2616 add-stylesheet option
2617 `````````````````````
2619 From http://article.gmane.org/gmane.text.docutils.devel/3429/
2621 The problem is that since we have a default value, we have to
2622 differentiate between adding another stylesheet and replacing the
2623 default. I suggest that the existing --stylesheet & --stylesheet-path
2624 options keep their semantics to replace the existing settings. We
2625 could introduce new --add-stylesheet & --add-stylesheet-path options,
2626 which accumulate; further --stylesheet/--stylesheet-path options would
2627 clear these lists. The stylesheet or stylesheet_path setting (only
2628 one may be set), plus the added_stylesheets and added_stylesheet_paths
2629 settings, describe the combined styles.
2631 For example, this run will have only one custom stylesheet:
2633 rstpep2html.py --stylesheet-path custom.css ...
2635 This run will use the default stylesheet, and the custom one:
2637 rstpep2html.py --add-stylesheet-path custom.css ...
2639 This run will use the default stylesheet, a custom local stylesheet,
2640 and an external stylesheet:
2642 rstpep2html.py --add-stylesheet-path custom.css \
2643 --add-stylesheet http://www.example.org/external.css ...
2645 This run will use only the second custom stylesheet:
2647 rstpep2html.py --add-stylesheet-path custom.css \
2648 --stylesheet-path second.css ...
2656 * What about if we don't know which Reader and/or Writer we are
2657 going to use? If the Reader/Writer is specified on the
2658 command-line? (Will this ever happen?)
2660 Perhaps have different types of front ends:
2662 a) _`Fully qualified`: Reader and Writer are hard-coded into the
2663 front end (e.g. ``pep2html [options]``, ``pysource2pdf
2666 b) _`Partially qualified`: Reader is hard-coded, and the Writer is
2667 specified a sub-command (e.g. ``pep2 html [options]``,
2668 ``pysource2 pdf [options]``). The Writer is known before option
2669 processing happens, allowing the OptionParser to be built
2670 dynamically. Alternatively, the Writer could be hard-coded and
2671 the Reader specified as a sub-command (e.g. ``htmlfrom pep
2674 c) _`Unqualified`: Reader and Writer are specified as subcommands
2675 (e.g. ``publish pep html [options]``, ``publish pysource pdf
2676 [options]``). A single front end would be sufficient, but
2677 probably only useful for testing purposes.
2679 d) _`Dynamic`: Reader and/or Writer are specified by options, with
2680 defaults if unspecified (e.g. ``publish --writer pdf
2681 [options]``). Is this possible? The option parser would have
2682 to be told about new options it needs to handle, on the fly.
2683 Component-specific options would have to be specified *after*
2684 the component-specifying option.
2686 Allow common options before subcommands, as in CVS? Or group all
2687 options together? In the case of the `fully qualified`_
2688 front ends, all the options will have to be grouped together
2689 anyway, so there's no advantage (we can't use it to avoid
2690 conflicts) to splitting common and component-specific options
2693 * Parameterize help text & defaults somehow? Perhaps a callback? Or
2694 initialize ``settings_spec`` in ``__init__`` or ``init_options``?
2696 * Disable common options that don't apply?
2697 (This should now be easier with ``frontend.filter_settings_spec``.)
2699 * Add ``--section-numbering`` command line option. The "sectnum"
2700 directive should override the ``--no-section-numbering`` command
2703 * Create a single dynamic_ or unqualified_ front end that can be
2710 indent-tabs-mode: nil
2711 sentence-end-double-space: t