1 .. include:: ../header.txt
7 :Author: David Goodger (with input from many); open to all Docutils
9 :Contact: docutils-develop@lists.sourceforge.net
12 :Copyright: This document has been placed in the public domain.
14 .. _Docutils: https://docutils.sourceforge.io/
19 Priority items are marked with "@" symbols. The more @s, the higher
20 the priority. Items in question form (containing "?") are ideas which
21 require more thought and debate; they are potential to-do's.
23 Many of these items are awaiting champions. If you see something
24 you'd like to tackle, please do!
25 Please see also the Bugs_ document for a list of bugs in Docutils.
27 .. _bugs: ../../BUGS.html
30 Minimum Requirements for Python Standard Library Candidacy
31 ==========================================================
33 Below are action items that must be added and issues that must be
34 addressed before Docutils can be considered suitable to be proposed
35 for inclusion in the Python standard library.
37 Many of these are now handled by Sphinx_
39 * Support for `document splitting`_. May require some major code
42 * Support for subdocuments (see `large documents`_).
44 * `Object numbering and object references`_.
46 * `Nested inline markup`_.
48 * `Python Source Reader`_.
50 * The HTML writer needs to be rewritten (or a second HTML writer
51 added) to allow for custom classes, and for arbitrary splitting
54 * Documentation_ of the architecture. Other docs too.
58 * Suitability for `Python module documentation
59 <https://docutils.sourceforge.io/sandbox/README.html#documenting-python>`_.
61 .. _Sphinx: http://www.sphinx-doc.org/
66 Move to a Git repository.
68 * This is a long standing `feature request`__
69 (with pointers to Sphinx issues and discussion).
71 __ https://sourceforge.net/p/docutils/feature-requests/58/
73 * From a `post by David Goodger`__
75 An absolute requirement, for me, is that such a change be complete.
76 We can't lose any data or have to refer to the old system as an
77 "archive". So all the SVN history, all branches, and the full sandbox
78 need to be converted at the same time.
80 __ https://sourceforge.net/p/docutils/mailman/message/31878077/
82 Convert with reposurgeon_?
84 If you are doing a full import rather than gatewaying, reposurgeon is
85 probably what you want. It has been tested against a lot of large, old,
86 nasty repositories and is thus known to be robust in the presence of
87 repository malformations (a property regularly checked by a test suite
88 that is a rogue's gallery of Subversion botches).
92 The comprehensive `Reposurgeon documentation`_ comes with
93 `a guide to repository conversion`__
94 as well as info about `reading Subversion repositories`__.
95 Converting from an SVN dump file is faster than from a checkout.
97 .. _reposurgeon: http://www.catb.org/esr/reposurgeon/
98 .. _reposurgeon documentation:
99 http://www.catb.org/esr/reposurgeon/repository-editing.html
100 __ https://git.wiki.kernel.org/index.php/
101 Interfaces,_frontends,_and_tools#Subversion
102 __ http://www.catb.org/esr/reposurgeon/repository-editing.html#conversion
103 __ http://www.catb.org/esr/reposurgeon/repository-editing.html
104 #_reading_subversion_repositories
107 Adam Turner wrote a conversion Makefile and ``.lift`` scripts that
108 downloads the repo from SF with rsync, converts it to a SVN mirror and
109 finally to Git, splitting sandbox, prest, and web from docutils.
112 Sourceforge supports multiple Git repositories per project, so we can
113 switch the version control system independent of the decision on an
114 eventual switch of the host.
115 Cf. https://sourceforge.net/p/forge/documentation/Git/
124 Code cleanup and modernization:
125 Use flake8_? See also the configuration in `<../../tox.ini>`__.
127 Check and solve issue from :PEP:`290` - Code Migration and Modernization.
128 (Covers issues up to Python 2.4, is there an equivalent for more recent
131 Ensure `backwards compatibility`_!
133 .. _flake8: https://pypi.org/project/flake8/
134 .. _backwards compatibility: policies.html#backwards-compatibility-policy
136 * Improve handling on Windows:
138 - Get graphical installer.
139 - Make rst2html.py an .exe file using py2exe.
140 (Is this still required after we have "console scripts" entry points?
145 The user interface is very difficult to use for most Windows users;
146 you can't really expect them to use the command line. We need some
147 kind of GUI that can launch ``rst2html``, and save the HTML output to
148 a file, and launch a browser. What's important is that we get
149 settings to work with the GUI. So we need some way to dynamically
150 generate a list of settings for the GUI. The current settings_spec
151 for OptionParser doesn't seem to be usable for this for the
154 - It's biased toward the command line -- there are *two* options for
157 - You cannot have both a one-line description and a longer
158 description for tooltips/help-texts.
160 - It doesn't provide hints for the input type. You cannot easily
161 infer the type of a setting from its validator, because any
162 component can add new validators. In fact, it may be necessary to
163 have both a hint about the input type (e.g. string) and a
164 validator (valid ID), or it may be necessary to have a different
165 set of choices for the CLI (1, INFO, 2, ...) and for the GUI
166 (INFO, WARNING, ...).
168 - It's coupled to the OptionParser. We want to be able to change
169 the underlying system without breaking everything.
171 - It's a bunch of primitive structures. We want an extensible (thus
172 object-oriented) interface.
174 So we probably need to create a class for storing all the settings,
175 and auto-generate the OptionParser data from that.
177 I talked to Stephan Deibel about getting Docutils integrated into
178 Wing IDE. He said it's possible, and he'd be willing to help.
179 There's a scripting interface to Wing, which we'd use. We can
180 dynamically generate a list of preferences and not worry too much
181 about the rendering (from what I understood); Wing's whole GUI is
182 dynamic anyway. The interface could be made usable for other GUIs.
183 For example, we could try to get option support for DocFactory. //
186 * Allow different report levels for STDERR and system_messages inside
189 * Change the docutils-update script (in sandbox/infrastructure), to
190 support arbitrary branch snapshots.
192 * Move some general-interest sandboxes out of individuals'
193 directories, into subprojects?
195 * Add option for file (and URL) access restriction to make Docutils
196 usable in Wikis and similar applications.
198 2005-03-21: added ``file_insertion_enabled`` & ``raw_enabled``
199 settings. These partially solve the problem, allowing or disabling
200 **all** file accesses, but not limited access.
202 * Configuration_ file handling needs discussion:
204 - There should be some error checking on the contents of config
205 files. How much checking should be done? How loudly should
206 Docutils complain if it encounters an error/problem?
208 - Docutils doesn't complain when it doesn't find a configuration
209 file supplied with the ``--config`` option. Should it? (If yes,
212 * Internationalization:
214 - I18n needs refactoring, the language dictionaries are difficult to
215 maintain. Maybe have a look at gettext or similar tools.
217 (This would make a nice Google Summer of Code project)
219 - Language modules: in accented languages it may be useful to have
220 both accented and unaccented entries in the
221 ``bibliographic_fields`` mapping for versatility.
223 - Add a "--strict-language" option & setting: no English fallback
224 for language-dependent features.
226 Make this the default for output (as opposed to input)?
227 Throw an error with a helpful message, e.g.
229 Default "contents" title for language %s missing, please specify
234 "attention" title for language %s missing, please use a generic
235 admonition with explicit title.
237 - Add internationalization to _`footer boilerplate text` (resulting
238 from "--generator", "--source-link", and "--date" etc.), allowing
242 * Add validation? See http://pytrex.sourceforge.net, RELAX NG, pyRXP.
244 * In ``docutils.readers.get_reader_class`` (& ``parsers`` &
245 ``writers`` too), should we be importing "standalone" or
246 "docutils.readers.standalone"? (This would avoid importing
247 top-level modules if the module name is not in docutils/readers.
248 Potential nastiness.)
250 * Perhaps store a _`name-to-id mapping file`? This could be stored
251 permanently, read by subsequent processing runs, and updated with
252 new entries. ("Persistent ID mapping"?)
254 * Perhaps the ``Component.supports`` method should deal with
255 individual features ("meta" etc.) instead of formats ("html" etc.)?
256 Currently, it is not used at all.
258 Do we need it at all? Or rather let the writers just ignore some
259 nodes (like we already do for "class" values)?
261 The current implementation of the framework also leads to bug
262 `bug #241`__ "doctree-based publishing != publish_string".
263 The "components.Filter" transform is run by publish_doctree(). When
264 filtering based on the output format, it should be run by
265 publish_from_doctree() instead because only then the writer is
268 So we need to either remove or fix the framework.
270 __ https://sourceforge.net/p/docutils/bugs/241/
273 * Think about _`large documents` made up of multiple subdocument
274 files. Issues: continuity (`persistent sequences`_ above),
275 cross-references (`name-to-id mapping file`_ above and `targets in
276 other documents`_ below), splitting (`document splitting`_ below).
278 When writing a book, the author probably wants to split it up into
279 files, perhaps one per chapter (but perhaps even more detailed).
280 However, we'd like to be able to have references from one chapter to
281 another, and have continuous numbering (pages and chapters, as
282 applicable). Of course, none of this is implemented yet. There has
283 been some thought put into some aspects; see `the "include"
284 directive`__ and the `Reference Merging`_ transform below.
286 When I was working with SGML in Japan, we had a system where there
287 was a top-level coordinating file, book.sgml, which contained the
288 top-level structure of a book: the <book> element, containing the
289 book <title> and empty component elements (<preface>, <chapter>,
290 <appendix>, etc.), each with filename attributes pointing to the
291 actual source for the component. Something like this::
294 <title>Title of the Book</title>
295 <preface inrefid="pr01"></preface>
296 <chapter inrefid="ch01"></chapter>
297 <chapter inrefid="ch02"></chapter>
298 <chapter inrefid="ch03"></chapter>
299 <appendix inrefid="ap01"></appendix>
302 (The "inrefid" attribute stood for "insertion reference ID".)
304 The processing system would process each component separately, but
305 it would recognize and use the book file to coordinate chapter and
306 page numbering, and keep a persistent ID to (title, page number)
307 mapping database for cross-references. Docutils could use a similar
308 system for large-scale, multipart documents.
310 __ ../ref/rst/directives.html#including-an-external-document-fragment
326 As I said earlier in chapter :chapter:`Objects.txt`, the
327 reference count gets increased every time a binding is made.
331 As I said earlier in chapter 2, the
332 reference count gets increased every time a binding is made.
334 The ToC in this form doesn't even need to be references to actual
335 reST documents; I'm simply doing it that way for a minimum of
336 future-proofing, in case I do want to add the ability to pick up
337 references within external chapters.
339 Perhaps, instead of ToC (which would overload the "contents"
340 directive concept already in use), we could use "manifest". A
341 "manifest" directive might associate local reference names with
345 intro: Introduction.txt
350 Then the sample becomes::
352 .. include:: manifest.txt
354 As I said earlier in chapter :chapter:`objects`, the
355 reference count gets increased every time a binding is made.
357 * Add support for _`multiple output files` and _`generic data
360 It should be possible for a component to **emit or reference** data
361 to be either **included or referenced** in the output document.
362 Examples of such data are stylesheets or images.
364 For this, we need a "data" object which stores the data either
365 inline or by referring to a file. The Docutils framework is
366 responsible for either:
368 * storing the data in the appropriate location (e.g. in the
369 directory of the output file, or in a user-specified directory)
370 and providing the paths of the stored files to the writer, *or*
372 * providing the data itself to the writer so that it can be embedded
373 in the output document.
375 This approach decouples data handling from the data source (which
376 can either be embedded or referenced) and the destination (which can
377 either be embedded or referenced as well).
379 See <http://article.gmane.org/gmane.text.docutils.devel/3631>.
381 * Add testing for Docutils' front end tools?
383 * Publisher: "Ordinary setup" shouldn't require specific ordering; at
384 the very least, there ought to be error checking higher up in the
387 ``Publisher.get_settings`` requires that all components be set up
388 before it's called. Perhaps the I/O *objects* shouldn't be set, but
389 I/O *classes*. Then options are set up (``.set_options``), and
390 ``Publisher.set_io`` (or equivalent code) is called with source &
391 destination paths, creating the I/O objects.
393 Perhaps I/O objects shouldn't be instantiated until required. For
394 split output, the Writer may be called multiple times, once for each
395 doctree, and each doctree should have a separate Output object (with
396 a different path). Is the "Builder" pattern applicable here?
398 * Perhaps I/O objects should become full-fledged components (i.e.
399 subclasses of ``docutils.Component``, as are Readers, Parsers, and
400 Writers now), and thus have associated option/setting specs and
403 * Multiple file I/O suggestion from Michael Hudson: use a file-like
404 object or something you can iterate over to get file-like objects.
406 * Add an "--input-language" option & setting? Specify a different
407 language module for input (bibliographic fields, directives) than
408 for output. The "--language" option would set both input & output
411 * Auto-generate reference tables for language-dependent features?
412 Could be generated from the source modules. A special command-line
413 option could be added to Docutils front ends to do this. (Idea from
416 * Enable feedback of some kind from internal decisions, such as
417 reporting the successful input encoding. Modify runtime settings?
418 System message? Simple stderr output?
420 * Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.
422 * Add an "--include file" command-line option (config setting too?),
423 equivalent to ".. include:: file" as the first line of the doc text?
424 Especially useful for character entity sets, text transform specs,
427 * Support "include" as embedded inline-compatible directive in substitution
430 .. |version| include:: version.txt
432 This document describes version |version| of ...
434 (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
436 * Add an ``:optional: <replacement text>`` option to the "include"
437 directive? This would not throw an error for a missing file, instead a
438 warning is given and ``<replacement text>`` is used instead. It would be
439 the responsibility of the author to ensure the missing file does not lead
440 to problems later in the document.
444 + Standard rST syntax to replace Sphinx's "literalinclude"::
446 .. include:: blah.cpp
448 :optional: file ``blah.cpp`` not found
450 + Variable content taken from a file, e.g.
454 .. |version| replace:: 3.1
458 .. include:: version.txt
459 :optional: .. |version| replace:: unknown
461 This document describes version |version| of ...
463 (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel)
465 * Parameterize the Reporter object or class? See the `2004-02-18
466 "rest checking and source path"`_ thread.
468 .. _2004-02-18 "rest checking and source path":
469 http://thread.gmane.org/gmane.text.docutils.user/1112
471 * Add a "disable_transforms" setting? Would allow for easy syntax
472 checking. Where ("null" writer, generic, parser(s))?
473 Cf. the `2004-02-18 "rest checking and source path"`_ thread.
475 * Add a generic meta-stylesheet mechanism? An external file could
476 associate style names ("class" attributes) with specific elements.
477 Could be generalized to arbitrary output attributes; useful for HTML
478 & XMLs. Aahz implemented something like this in
479 sandbox/aahz/Effective/EffMap.py.
481 * .. _classes for table cells:
483 William Dode suggested that table cells be assigned "class"
484 attributes by columns, so that stylesheets can affect text
485 alignment. Unfortunately, there doesn't seem to be a way (in HTML
486 at least) to leverage the "colspec" elements (HTML "col" tags) by
487 adding classes to them. The resulting HTML is very verbose::
489 <td class="col1">111</td>
490 <td class="col2">222</td>
493 At the very least, it should be an option. People who don't use it
494 shouldn't be penalized by increases in their HTML file sizes.
496 Table rows could also be assigned classes (like odd/even). That
497 would be easier to implement.
499 How should it be implemented?
501 * There could be writer options (column classes & row classes) with
504 * The table directive could grow some options. Something like
505 ":cell-classes: col1 col2 col3" (either must match the number of
506 columns, or repeat to fill?) and ":row-classes: odd even" (repeat
507 to fill; body rows only, or header rows too?).
509 Probably per-table directive options are best. The "class" values
510 could be used by any writer, and applying such classes to all tables
511 in a document with writer options is too broad.
513 See also the `table_styling Sphinx extension`_ which defines
515 :widths: also in Docutils core (but different implementation)
516 :column-alignment: Sets per-column text alignment
517 :column-wrapping: Sets per-column text wrapping
518 :column-dividers: Add dividers between columns
519 :column-classes: Add per-column css classes.
520 :header-columns: Specify number of “stub” columns
522 .. _table_styling Sphinx extension: https://pythonhosted.org/cloud_sptheme/
523 lib/cloud_sptheme.ext.table_styling.html
525 * Add file-specific settings support to config files, like::
530 Is this even possible? Should the criterion be the name of the
531 input file or the output file? Alternative (more explicit) syntax::
533 [source_file index.txt]
536 [dest_file index.html]
539 Or rather allow settings configuration from the rst source file
540 (see misc.settings_ directive)?
542 * The "validator" support added to OptionParser is very similar to
543 "traits_" in SciPy_. Perhaps something could be done with them?
544 (Had I known about traits when I was implementing docutils.frontend,
545 I may have used them instead of rolling my own.)
547 .. _traits: http://code.enthought.com/traits/
548 .. _SciPy: http://www.scipy.org/
550 * tools/buildhtml.py: Extend the --prune option ("prune" config
551 setting) to accept file names (generic path) in addition to
552 directories (e.g. --prune=docs/user/rst/cheatsheet.txt, which should
553 *not* be converted to HTML).
555 * Add support for _`plugins`.
557 * _`Config directories`: Currently, ~/.docutils, ./docutils.conf/, &
558 /etc/docutils.conf are read as configuration_ files. Proposal: allow
559 ~/.docutils to be a a configuration *directory*, along with
560 /etc/docutils/ and ./docutils.conf/. Within these directories,
561 check for config.txt files. We can also have subdirectories here,
562 for plugins, S5 themes, components (readers/writers/parsers) etc.
564 Docutils will continue to support configuration files for backwards
567 * Add support for document decorations other than headers & footers?
568 For example, top/bottom/side navigation bars for web pages. Generic
571 Seems like a bad idea as long as it isn't independent from the output
572 format (for example, navigation bars are only useful for web pages).
574 * docutils_update: Check for a ``Makefile`` in a directory, and run
575 ``make`` if found? This would allow for variant processing on
576 specific source files, such as running ``rst2s5`` instead of
579 * Add a "disable table of contents" setting? The S5 writer could set
580 it as a default. Rationale:
582 The ``contents`` (table of contents) directive must not be used
583 [in S5/HTML documents]. It changes the CSS class of headings
584 and they won't show up correctly in the screen presentation.
586 -- `Easy Slide Shows With reStructuredText & S5
587 <../user/slide-shows.html>`_
589 Analogue to the ``sectnum_xform`` setting, it could be used by the
590 latex writer to switch to a LaTeX generated ToC (currently, the latex
591 writer calls it "use_latex_toc").
593 object numbering and object references
594 --------------------------------------
596 For equations, tables & figures.
598 These would be the equivalent of DocBook's "formal" elements.
600 In LaTeX, automatic counters are implemented for sections, equations and
601 floats (figures, tables) (configurable via stylesheets or in the
602 latex-preamble). Objects can be given `reference names`_ with the
603 ``\label{<refname}`` command, ``\ref{<refname>}`` inserts the
604 corresponding number.
606 No such mechanism exists in HTML.
608 * We need _`persistent sequences`, similar to chapter and footnote
609 numbers. See `OpenOffice.org XML`_ "fields".
611 - Should the sequences be automatic or manual (user-specifyable)?
613 * It is already possible to give `reference names`_ to objects via
614 internal hyperlink targets or the "name" directive option::
618 .. figure:: image.png
622 .. figure:: image.png
625 Improve the mapping of "phrase references" to IDs/labels with Literal
626 transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just
627 stripping the accents and other non-ASCII chars. See also the feature
628 request `allow more characters when transforming "names" to "ids"`__.
630 A "table" directive has been implemented, supporting table titles.
632 Perhaps the name could derive from the title/caption?
634 .. _reference names: ../ref/rst/restructuredtext.html#reference-names
635 __ https://sourceforge.net/p/docutils/feature-requests/66/
637 * We need syntax for object references. Cf. `OpenOffice.org XML`_
640 - Parameterized substitutions are too complicated
641 (cf. `or not to do`: `object references`_)
643 - An interpreted text approach is simpler and better::
645 See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
647 - "equation", "figure", and "page" roles could generate appropriate
650 See :figure:`figure name` on :page:`figure name`.
652 See `Interpreted Text`_ below.
654 Reference boilerplate could be specified in the document
655 (defaulting to nothing)::
658 :prefix-ref: "Figure "
659 :prefix-caption: "Fig. "
662 The position of the role (prefix or suffix) could also be utilized
664 .. _OpenOffice.org XML: http://xml.openoffice.org/
665 .. _object references: rst/alternatives.html#object-references
674 * Add a FAQ entry about using Docutils (with reStructuredText) on a
675 server and that it's terribly slow. See the first paragraphs in
676 <http://article.gmane.org/gmane.text.docutils.user/1584>.
678 * Add document about what Docutils has previously been used for
679 (web/use-cases.txt?).
681 * Improve index in docs/user/config.txt.
687 * Improve the internal module documentation (docstrings in the code).
688 Specific deficiencies listed below.
690 - docutils.parsers.rst.states.State.build_table: data structure
691 required (including StringList).
693 - docutils.parsers.rst.states: more complete documentation of parser
696 * docs/ref/doctree.txt: DTD element structural relationships,
697 semantics, and attributes. In progress; element descriptions to be
700 * Document the ``pending`` elements, how they're generated and what
703 * Document the transforms_ (perhaps in docstrings?): how they're used,
704 what they do, dependencies & order considerations.
706 * Document the HTML classes used by html4css1.py.
708 * Write an overview of the Docutils architecture, as an introduction
709 for developers. What connects to what, why, and how. Either update
710 PEP 258 (see PEPs_ below) or as a separate doc.
712 * Give information about unit tests. Maybe as a howto?
714 * Document the docutils.nodes APIs.
716 * Complete the docs/api/publisher.txt docs.
722 * Creating Docutils Writers
724 * Creating Docutils Readers
726 * Creating Docutils Transforms_
728 * Creating Docutils Parsers
730 * Using Docutils as a Library
736 * Complete PEP 258 Docutils Design Specification.
738 - Fill in the blanks in API details.
740 - Specify the nodes.py internal data structure implementation?
742 [Tibs:] Eventually we need to have direct documentation in
743 there on how it all hangs together - the DTD is not enough
744 (indeed, is it still meant to be correct? [Yes, it is.
747 * Rework PEP 257, separating style from spec from tools, wrt Docutils?
748 See Doc-SIG from 2001-06-19/20.
756 * Analyze Tony Ibbs' PySource code.
758 * Analyze Doug Hellmann's HappyDoc project.
760 * Investigate how POD handles literate programming.
762 * Take the best ideas and integrate them into Docutils.
766 * Ask Python-dev for opinions (GvR for a pronouncement) on special
767 variables (__author__, __version__, etc.): convenience vs. namespace
768 pollution. Ask opinions on whether or not Docutils should recognize
771 * If we can detect that a comment block begins with ``##``, a la
772 JavaDoc, it might be useful to indicate interspersed section headers
773 & explanatory text in a module. For example::
775 """Module docstring."""
788 class MyException(Exception): pass
792 * Should standalone strings also become (module/class) docstrings?
793 Under what conditions? We want to prevent arbitrary strings from
794 becoming docstrings of prior attribute assignments etc. Assume
795 that there must be no blank lines between attributes and attribute
796 docstrings? (Use lineno of NEWLINE token.)
798 Triple-quotes are sometimes used for multi-line comments (such as
799 commenting out blocks of code). How to reconcile?
801 * HappyDoc's idea of using comment blocks when there's no docstring
802 may be useful to get around the conflict between `additional
803 docstrings`_ and ``from __future__ import`` for module docstrings.
804 A module could begin like this::
806 #!/usr/bin/env python
808 # :Copyright: whatever
810 """This is the public module docstring (``__doc__``)."""
812 # More docs, in comments.
813 # All comments at the beginning of a module could be
814 # accumulated as docstrings.
815 # We can't have another docstring here, because of the
816 # ``__future__`` statement.
818 from __future__ import division
820 Using the JavaDoc convention of a doc-comment block beginning with
821 ``##`` is useful though. It allows doc-comments and implementation
824 .. _additional docstrings:
825 ../peps/pep-0258.html#additional-docstrings
827 * HappyDoc uses an initial comment block to set "parser configuration
828 values". Do the same thing for Docutils, to set runtime settings on
829 a per-module basis? I.e.::
831 # Docutils:setting=value
833 Could be used to turn on/off function parameter comment recognition
834 & other marginal features. Could be used as a general mechanism to
835 augment config files and command-line options (but which takes
838 * Multi-file output should be divisible at arbitrary level.
840 * Support all forms of ``import`` statements:
842 - ``import module``: listed as "module"
843 - ``import module as alias``: "alias (module)"
844 - ``from module import identifier``: "identifier (from module)"
845 - ``from module import identifier as alias``: "alias (identifier
847 - ``from module import *``: "all identifiers (``*``) from module"
849 * Have links to colorized Python source files from API docs? And
850 vice-versa: backlinks from the colorized source files to the API
853 * In summaries, use the first *sentence* of a docstring if the first
854 line is not followed by a blank line.
857 reStructuredText Parser
858 =======================
860 Also see the `... Or Not To Do?`__ list.
862 __ rst/alternatives.html#or-not-to-do
867 * A container directive with ``:class:`` option gets the spurious
873 * Another list problem::
879 This ends up as a definition list. This is more of a usability
882 * This case is probably meant to be a nested list, but it ends up as a
883 list inside a block-quote without an error message::
889 It should probably just be an error.
891 The problem with this is that you don't notice easily in HTML that
892 it's not a nested list but a block-quote -- there's not much of a
895 * Treat enumerated lists that are not arabic and consist of only one
896 item in a single line as ordinary paragraphs. See
897 <http://article.gmane.org/gmane.text.docutils.user/2635>.
899 * The citation syntax could use some improvements. See
900 <http://thread.gmane.org/gmane.text.docutils.user/2499> (and the
902 <http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028>,
903 and the follow-ups at
904 <http://thread.gmane.org/gmane.text.docutils.user/3087>,
905 <http://thread.gmane.org/gmane.text.docutils.user/3110>,
906 <http://thread.gmane.org/gmane.text.docutils.user/3114>),
907 <http://thread.gmane.org/gmane.text.docutils.user/2443>,
908 <http://thread.gmane.org/gmane.text.docutils.user/2715>,
909 <http://thread.gmane.org/gmane.text.docutils.user/3027>,
910 <http://thread.gmane.org/gmane.text.docutils.user/3120>,
911 <http://thread.gmane.org/gmane.text.docutils.user/3253>.
913 * The current list-recognition logic has too many false positives, as
920 Here ``V.`` is recognized as an enumerator, which leads to
921 confusion. We need to find a solution that resolves such problems
922 without complicating the spec to much.
924 See <http://thread.gmane.org/gmane.text.docutils.user/2524>.
926 * Add indirect links via citation references & footnote references.
929 `Goodger (2005)`_ is helpful.
931 .. _Goodger (2005): [goodger2005]_
932 .. [goodger2005] citation text
934 See <http://thread.gmane.org/gmane.text.docutils.user/2499>.
936 * Complain about bad URI characters
937 (http://article.gmane.org/gmane.text.docutils.user/2046) and
938 disallow internal whitespace
939 (http://article.gmane.org/gmane.text.docutils.user/2214).
941 * Create ``info``-level system messages for unnecessarily
942 backslash-escaped characters (as in ``"\something"``, rendered as
943 "something") to allow checking for errors which silently slipped
946 * Add (functional) tests for untested roles.
948 * Add test for ":figwidth: image" option of "figure" directive. (Test
949 code needs to check if PIL is available on the system.)
951 * Add support for CJK double-width whitespace (indentation) &
952 punctuation characters (markup; e.g. double-width "*", "-", "+")?
954 * Add motivation sections for constructs in spec.
956 * Support generic hyperlink references to _`targets in other
957 documents`? Not in an HTML-centric way, though (it's trivial to say
958 ``https://www.example.org/doc#name``, and useless in non-HTML
959 contexts). XLink/XPointer? ``.. baseref::``? See Doc-SIG
962 * Implement the header row separator modification to table.el. (Wrote
963 to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting
964 support for "=====" header rows. On 2001-08-17 he replied, saying
965 he'd put it on his to-do list, but "don't hold your breath".)
967 * Fix the parser's indentation handling to conform with the stricter
968 definition in the spec. (Explicit markup blocks should be strict or
971 .. XXX What does this mean? Can you elaborate, David?
973 * Make the parser modular. Allow syntax constructs to be added or
974 disabled at run-time. Subclassing is probably not enough because it
975 makes it difficult to apply multiple extensions.
977 * Generalize the "doctest block" construct (which is overly
978 Python-centric) to other interactive sessions? "Doctest block"
979 could be renamed to "I/O block" or "interactive block", and each of
980 these could also be recognized as such by the parser:
985 A block beginning with a "$ " prompt is interpreted as a shell
986 session interactive block. As with Doctest blocks, the
987 interactive block ends with the first blank line, and wouldn't
990 - Root shell sessions::
993 A block beginning with a "# " prompt is interpreted as a root
994 shell session (the user is or has to be logged in as root)
995 interactive block. Again, the block ends with a blank line.
997 Other standard (and unambiguous) interactive session prompts could
998 easily be added (such as "> " for WinDOS).
1000 Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread
1001 "docutils feedback").
1003 * Add support for pragma (syntax-altering) directives.
1005 Some pragma directives could be local-scope unless explicitly
1006 specified as global/pragma using ":global:" options.
1008 * Support whitespace in angle-bracketed standalone URLs according to
1009 Appendix E ("Recommendations for Delimiting URI in Context") of `RFC
1012 .. _RFC 2396: https://www.rfc-editor.org/rfc/rfc2396.txt
1014 * Use the vertical spacing of the source text to determine the
1015 corresponding vertical spacing of the output?
1017 * [From Mark Nodine] For cells in simple tables that comprise a
1018 single line, the justification can be inferred according to the
1021 1. If the text begins at the leftmost column of the cell,
1022 then left justification, ELSE
1023 2. If the text begins at the rightmost column of the cell,
1024 then right justification, ELSE
1025 3. Center justification.
1027 The onus is on the author to make the text unambiguous by adding
1028 blank columns as necessary. There should be a parser setting to
1029 turn off justification-recognition (normally on would be fine).
1031 Decimal justification?
1033 All this shouldn't be done automatically. Only when it's requested
1034 by the user, e.g. with something like this::
1041 Otherwise it will break existing documents.
1043 * Generate a warning or info message for paragraphs which should have
1044 been lists, like this one::
1049 * Generalize the "target-notes" directive into a command-line option
1050 somehow? See docutils-develop 2003-02-13.
1052 * Allow a "::"-only paragraph (first line, actually) to introduce a
1053 _`literal block without a blank line`? (Idea from Paul Moore.) ::
1056 This is a literal block
1058 Is indentation enough to make the separation between a paragraph
1059 which contains just a ``::`` and the literal text unambiguous?
1060 (There's one problem with this concession: If one wants a definition
1061 list item which defines the term "::", we'd have to escape it.) It
1062 would only be reasonable to apply it to "::"-only paragraphs though.
1063 I think the blank line is visually necessary if there's text before
1066 The text in this paragraph needs separation
1067 from the literal block following::
1068 This doesn't look right.
1070 * Add new syntax for _`nested inline markup`? Or extend the parser to
1071 parse nested inline markup somehow? See the `collected notes
1072 <rst/alternatives.html#nested-inline-markup>`__.
1074 * Drop the backticks from embedded URIs with omitted reference text?
1075 Should the angle brackets be kept in the output or not? ::
1079 Probably not worth the trouble.
1081 * How about a syntax for alternative hyperlink behavior, such as "open
1082 in a new window" (as in HTML's ``<a target="_blank">``)?
1084 The MoinMoin wiki uses a caret ("^") at the beginning of the URL
1085 ("^" is not a legal URI character). That could work for both inline
1086 and explicit targets::
1088 The `reference docs <^url>`__ may be handy.
1092 This may be too specific to HTML. It hasn't been requested very
1095 * Add an option to add URI schemes at runtime.
1097 * _`Segmented lists`::
1099 : segment : segment : segment
1100 : segment : segment : very long
1102 : segment : segment : segment
1104 The initial colon (":") can be thought of as a type of bullet
1106 We could even have segment titles::
1108 :: title : title : title
1109 : segment : segment : segment
1110 : segment : segment : segment
1112 This would correspond well to DocBook's SegmentedList. Output could
1113 be tabular or "name: value" pairs, as described in DocBook's docs.
1115 * Enable grid _`tables inside XML comments`, where "``--``" ends comments.
1117 Implementation possibilities:
1119 1. Make the table syntax characters into "table" directive options.
1120 This is the most flexible but most difficult, and we probably
1121 don't need that much flexibility.
1123 2. Substitute "~" for "-" with a specialized directive option
1126 3. Make the standard table syntax recognize "~" as well as "-", even
1127 without a directive option. Individual tables would have to be
1128 internally consistent.
1130 4. Allow Unicode box characters for table markup
1131 (`feature request [6]`_)
1133 Directive options are preferable to configuration settings, because
1134 tables are document-specific. A pragma directive would be another
1135 approach, to set the syntax once for a whole document.
1137 Unicode box character markup would kill two birds with one stone.
1139 In the meantime, the list-table_ directive is a good replacement for
1140 grid tables inside XML comments.
1142 .. _feature request [6]:
1143 https://sourceforge.net/p/docutils/feature-requests/6
1144 .. _list-table: ../ref/rst/directives.html#list-table
1147 * Generalize docinfo contents (bibliographic fields): remove specific
1148 fields, and have only a single generic "field"?
1150 * _`Line numbers` and "source" in system messages:
1152 - Add "source" and "line" keyword arguments to all Reporter calls?
1153 This would require passing source/line arguments along all
1154 intermediate functions (where currently only `line` is used).
1156 Or rather specify "line" only if actually needed?
1158 Currently, `document.reporter` uses a state machine instance to
1159 determine the "source" and "line" info from
1160 `statemachine.input_lines` if not given explicitly. Except for
1161 special cases, the "line" argument is not needed because,
1162 `document.statemachine` keeps record of the current line number.
1164 - For system messages generated after the parsing is completed (i.e. by
1165 transforms or the writer) "line" info must be present in the doctree
1168 Elements' .line assignments should be checked. (Assign to .source
1169 too? Add a set_info method? To what?)
1171 The "source" (and line number in the source) can either be added
1172 explicitly to the elements or determined from the “raw” line
1173 number by `document.statemachine.get_source_and_line`.
1175 - Some line numbers in elements are not being set properly
1176 (explicitly), just implicitly/automatically. See rev. 1.74 of
1177 docutils/parsers/rst/states.py for an example of how to set.
1179 - The line numbers of definition list items are wrong::
1181 $ rst2pseudoxml --expose-internal-attribute line
1190 <document source="<stdin>">
1192 <definition_list_item internal:line="3">
1196 <paragraph internal:line="2">
1199 <definition_list_item internal:line="6">
1203 <paragraph internal:line="6">
1209 Quite a few nodes are getting a "None" source attribute as well. In
1210 particular, see the bodies of definition lists.
1213 Adaptable file extensions
1214 -------------------------
1219 Should Docutils support adaptable file extensions in hyperlinks?
1221 In the rST source, sister documents are ".txt" files. If we're
1222 generating HTML, then ".html" is appropriate; if PDF, then ".pdf";
1225 Handle documents only, or objects (images, etc.) also?
1227 Different output formats support different sets of image formats (HTML
1228 supports ".svg" but not ".pdf", pdfLaTeX supports ".pdf" but not ".svg",
1229 LaTeX supports only ".eps").
1231 This is less urgent 2020 than 2004, as `pdflatex` and `lualatex` are
1232 now standard and support most image formats. Also, a wrapper like
1233 `rubber`__ that provides on-the-fly image conversion depends on the
1234 "wrong" extension in the LaTeX source.
1236 __ https://pypi.org/project/rubber/
1238 At what point should the extensions be substituted?
1241 Fits well in the `Reader → Transformer → Writer`__ processing framework.
1243 * Filename/URL extension replacement can be done walking over the
1244 Document tree transforming the document tree from a valid state
1245 to another valid state.
1247 * Writer-specific configuration is still possible in the
1248 respective sections of the configuration_ file.
1250 __ ../peps/pep-0258.html#id24
1252 Pre- or post-processing:
1253 Can be implemented independent of Docutils -- keeps Docutils simple.
1255 ... those who need more sophisticated filename extension
1256 tweaking can simply use regular expressions, which isn't too
1257 difficult due to the determinability of the writers. So there
1258 is no need to add a complex filename-extension-handling feature
1261 --- `Lea Wiemann in docutils-users 2004-06-04`__
1263 __ https://sourceforge.net/p/docutils/mailman/message/6918089/
1269 How about using ".*" to indicate "choose the most appropriate filename
1270 extension"? For example::
1272 .. _Another Document: another.*
1274 * My point about using ``.*`` is that any other mechanism inside reST
1275 leads to too many ambiguities in reading reST documents; at least
1276 with ``.*`` it's clear that some kind of substitution is going on.
1280 * What is to be done for output formats that don't *have* hyperlinks?
1281 For example, LaTeX targeted at print. Hyperlinks may be "called
1282 out", as footnotes with explicit URLs. (Don't convert the links.)
1284 But then there's also LaTeX targeted at PDFs, which *can* have
1285 links. Perhaps a runtime setting for "*" could explicitly provide
1286 the extension, defaulting to the output file's extension.
1288 * If this handles images also, how to differentiate between document
1289 and image links? Element context (within "image")? Which image
1290 extension to use for which document format? For HTML output, there
1291 is no reliable way of determining which extension to use (svg, png,
1292 jpg, jpeg, gif, ...).
1294 Should the system check for existing files? No, not practical (the
1295 image files may be not available when the document is processed to HTML).
1297 Mailing list threads: `Images in both HTML and LaTeX`__ (especially
1298 `this summary of Lea's objections`__).
1300 __ https://sourceforge.net/p/docutils/mailman/docutils-users/thread/40BAA4B7.5020801%40python.org/#msg6918066
1301 __ https://sourceforge.net/p/docutils/mailman/message/6918089/
1303 Chris Liechti suggests a new ``:link:`` role in `more-universal
1306 .. role:: link(rewrite)
1307 :transform: .txt|.html
1309 and then to use it::
1311 for more information see :link:`README.txt`
1313 it would be useful if it supported an additional option
1314 ``:format: html`` so that separate rules for each format can be
1315 defined. (like the "raw" role)
1317 __ https://sourceforge.net/p/docutils/mailman/message/6919484/
1320 Idea from Jim Fulton: an external lookup table of targets:
1322 I would like to specify the extension (e.g. .txt) [in the
1323 source, rather than ``filename.*``], but tell the converter to
1324 change references to the files anticipating that the files will
1329 .. _Another Document: another.txt
1331 rst2html --convert-links "another.txt bar.txt" foo.txt
1333 That is, name the files for which extensions should be converted.
1335 Note that I want to refer to original files in the original text
1336 (another.txt rather than another.*) because I want the
1337 unconverted text to stand on its own.
1339 Note that in most cases, people will be able to use globs::
1341 rst2html --convert-link-extensions-for "`echo *.txt`" foo.txt
1343 It might be nice to be able to use multiple arguments, as in::
1345 rst2html --convert-link-extensions-for *.txt -- foo.txt
1347 > Handle documents only, or objects (images, etc.) also?
1349 No, documents only, but there really is no need for guesswork.
1350 Just get the file names as command-line arguments. EIBTI
1351 [explicit is better than implicit].
1353 In `Patch #169`__ `Hyperlink extension rewriting`, John L. Clark
1354 suggests command line options that map to-be-changed file extensions, e.g.::
1356 rst2html --map-extension rst html --map-extension jpg png \
1359 __ https://sourceforge.net/p/docutils/patches/169/
1361 Specifying the mapping as regular expressions would make this
1362 approach more generic and easier to implement (use ``re.replace``
1363 and refer to the "re" module's documentation instead of coding and
1364 documenting a home-grown extraction and mapping procedure).
1370 Since Docutils 0.8, a "math" role and directive using LaTeX math
1371 syntax as input format is part of reStructuredText.
1375 * Use a "Transform" for math format conversions as extensively discussed in
1376 the "math directive issues" thread in May 2008
1377 (http://osdir.com/ml/text.docutils.devel/2008-05/threads.html)?
1379 * Generic `math-output setting`_ (currently specific to HTML).
1380 (List of math-output preferences?)
1382 * Try to be compatible with `Math support in Sphinx`_?
1384 * The ``:label:`` option selects a label for the equation, by which it
1385 can be cross-referenced, and causes an equation number to be issued.
1386 In Docutils, the option ``:name:`` sets the label.
1387 Equation numbering is not implemented yet.
1389 * Option ``:nowrap:`` prevents wrapping of the given math in a
1390 math environment (you have to specify the math environment in the
1393 .. _Math support in Sphinx: http://sphinx.pocoo.org/ext/math.html
1395 * Equation numbering and references. (see the section on
1396 `object numbering and object references` for equations,
1397 formal tables, and images.)
1399 .. _math-output setting: ../user/config.html#math-output
1402 alternative input formats
1403 `````````````````````````
1405 Use a directive option to specify an alternative input format, e.g. (but not
1409 Not for hand-written code but maybe useful when pasted in (or included
1412 For an overview of MathML implementations and tests, see, e.g.,
1413 the `mathweb wiki`_ or the `ConTeXT MathML page`_.
1415 .. _MathML: https://www.w3.org/TR/MathML2/
1416 .. _mathweb wiki: http://www.mathweb.org/wiki/MathML
1417 .. _ConTeXT MathML page: http://wiki.contextgarden.net/MathML
1419 A MathML to LaTeX XSLT sheet:
1420 https://github.com/davidcarlisle/web-xslt/tree/master/pmml2tex
1424 Simple, ASCII based math input language (see also `ASCIIMath tutorial`_).
1426 * The Python module ASCIIMathML_ translates a string with ASCIIMath into a
1427 MathML tree. Used, e.g., by MultiMarkdown__.
1429 A more comprehensive implementation is ASCIIMathPython_ by
1430 Paul Trembley (also used in his sandbox projects).
1432 * For conversion to LaTeX, there is
1434 - a JavaScript script at
1435 http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js
1437 - The javascript `asciimath-to-latex` AsciiMath to LaTex converter at
1438 the node package manager
1439 https://www.npmjs.com/package/asciimath-to-latex
1440 and at GitHub https://github.com/tylerlong/asciimath-to-latex
1442 - a javascript and a PHP converter script at GitHub
1443 https://github.com/asciimath/asciimathml/tree/master/asciimath-based
1445 .. _ASCIIMath: http://www1.chapman.edu/~jipsen/mathml/asciimath.html
1446 .. _ASCIIMath tutorial:
1447 http://www.wjagray.co.uk/maths/ASCIIMathTutorial.html
1448 .. _ASCIIMathML: http://pypi.python.org/pypi/asciimathml/
1449 .. _ASCIIMathPython: https://github.com/paulhtremblay/asciimathml
1450 __ http://fletcherpenney.net/multimarkdown/
1452 `Unicode Nearly Plain Text Encoding of Mathematics`_
1453 format for lightly marked-up representation of mathematical
1454 expressions in Unicode.
1456 (Unicode Technical Note. Sole responsibility for its contents rests
1457 with the author(s). Publication does not imply any endorsement by
1458 the Unicode Consortium.)
1460 .. _Unicode Nearly Plain Text Encoding of Mathematics:
1461 https://www.unicode.org/notes/tn28/
1464 See `the culmination of a relevant discussion in 2003
1465 <http://article.gmane.org/gmane.text.docutils.user/118>`__.
1472 Which equation environments should be supported by the math directive?
1476 + numbered: `equation`
1477 + unnumbered: `equation*`
1479 * multiline (test for ``\\`` outside of a nested environment
1480 (e.g. `array` or `cases`)
1482 + numbered: `align` (number every line)
1484 (To give one common number to all lines, put them in a `split`
1485 environment. Docutils then places it in an `equation` environment.)
1487 + unnumbered: `align*`
1489 + Sphinx math also supports `gather` (checking for blank lines in
1490 the content). Docutils puts content blocks separated by blank
1491 lines in separate math-block doctree nodes. (The only difference of
1492 `gather` to two consecutive "normal" environments seems to be that
1493 page-breaks between the two are prevented.)
1495 See http://www.math.uiuc.edu/~hildebr/tex/displays.html.
1501 There is no native math support in HTML4. HTML5 has built-in support for
1502 MathML. MathML is supported by all major browsers since 2023.
1504 For supported math output variants see the `math-output setting`_.
1507 Additional converters from LaTeX to MathML
1509 * TeX4ht_ (TeX based)
1510 * `MathJax for Node`_
1512 .. _MathML: https://www.w3.org/TR/MathML2/
1513 .. _TeX4ht: http://www.tug.org/applications/tex4ht/mn.html
1514 .. _MathJax for Node: https://github.com/mathjax/MathJax-node
1518 format math in standard HTML enhanced by CSS rules
1519 (`Examples and experiments`__).
1520 The ``math-output=html`` option uses the converter from eLyXer_
1521 (included with Docutils).
1523 Alternatives: LaTeX-math to HTML/CSS converters include
1525 * Hevea_ (Objective Caml)
1526 * `MathJax for Node`_
1529 __ http://www.zipcon.net/~swhite/docs/math/math.html
1530 .. _elyxer: http://elyxer.nongnu.org/
1531 .. _Hevea: http://para.inria.fr/~maranget/hevea/
1532 .. _KaTeX: https://katex.org
1534 client side JavaScript conversion
1535 Use TeX notation in the web page and JavaScript in the displaying browser.
1536 (implemented as `math-output setting`_ "mathjax").
1538 * jqMath_ (faster and lighter than MathJax_)
1540 .. _MathJax: http://www.mathjax.org/
1541 .. _jqMath: http://mathscribe.com/author/jqmath.html
1546 * The `OpenDocument standard`_ version 1.1 says:
1548 Mathematical content is represented by MathML 2.0
1550 However, putting MathML into an ODP file seems tricky as these
1551 (maybe outdated) links suppose:
1552 http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx
1553 http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx
1555 .. _OpenDocument standard:
1556 http://www.oasis-open.org/standards#opendocumentv1.1
1558 * OOoLaTeX__: "a set of macros designed to bring the power of LaTeX
1561 __ http://ooolatex.sourceforge.net/
1567 Directives below are often referred to as "module.directive", the
1568 directive function. The "module." is not part of the directive name
1569 when used in a document.
1571 * Allow for field lists in list tables. See
1572 <http://thread.gmane.org/gmane.text.docutils.devel/3392>.
1576 Unify table implementations and unify options of table directives
1577 (http://article.gmane.org/gmane.text.docutils.user/1857).
1579 * Allow directives to be added at run-time?
1581 * Use the language module for directive option names?
1583 * Add "substitution_only" and "substitution_ok" function attributes,
1584 and automate context checking?
1586 * Implement options or features on existing directives:
1588 - All directives that produce titled elements should grow implicit
1589 reference names based on the titles.
1591 - Allow the _`:trim:` option for all directives when they occur in a
1592 substitution definition, not only the unicode_ directive.
1594 .. _unicode: ../ref/rst/directives.html#unicode-character-codes
1596 - Add the "class" option to the unicode_ directive. For example, you
1597 might want to get characters or strings with borders around them.
1599 - _`images.figure`: "title" and "number", to indicate a formal
1602 - _`parts.sectnum`: "local"?, "refnum"
1604 A "local" option could enable numbering for sections from a
1605 certain point down, and sections in the rest of the document are
1606 not numbered. For example, a reference section of a manual might
1607 be numbered, but not the rest. OTOH, an all-or-nothing approach
1608 would probably be enough.
1610 The "sectnum" directive should be usable multiple times in a
1611 single document. For example, in a long document with "chapter"
1612 and "appendix" sections, there could be a second "sectnum" before
1613 the first appendix, changing the sequence used (from 1,2,3... to
1614 A,B,C...). This is where the "local" concept comes in. This part
1615 of the implementation can be left for later.
1617 A "refnum" option (better name?) would insert reference names
1618 (targets) consisting of the reference number. Then a URL could be
1619 of the form ``http://host/document.html#2.5`` (or "2-5"?). Allow
1620 internal references by number? Allow name-based *and*
1621 number-based ids at the same time, or only one or the other (which
1622 would the table of contents use)? Usage issue: altering the
1623 section structure of a document could render hyperlinks invalid.
1625 - _`parts.contents`: Add a "suppress" or "prune" option? It would
1626 suppress contents display for sections in a branch from that point
1627 down. Or a new directive, like "prune-contents"?
1629 Add an option to include topics in the TOC? Another for sidebars?
1630 The "topic" directive could have a "contents" option, or the
1631 "contents" directive" could have an "include-topics" option. See
1632 docutils-develop 2003-01-29.
1634 - _`parts.header` & _`parts.footer`: Support multiple, named headers
1635 & footers? For example, separate headers & footers for odd, even,
1636 and the first page of a document.
1638 This may be too specific to output formats which have a notion of
1643 - Add a ``:parent:`` option for setting the parent's class
1644 (http://article.gmane.org/gmane.text.docutils.devel/3165).
1648 - Option to label lines?
1650 - How about an environment variable, say RSTINCLUDEPATH or
1651 RSTPATH, for standard includes (as in ``.. include:: <name>``)?
1652 This could be combined with a setting/option to allow
1653 user-defined include directories.
1655 - Add support for inclusion by URL? ::
1658 :url: https://www.example.org/inclusion.txt
1660 - Strip blank lines from begin and end of a literal included file or
1661 file section. This would correspond to the way a literal block is
1664 As nodes.literal_block expects (and we have) the text as a string
1665 (rather than a list of lines), using a regexp seems the way.
1667 - _`misc.raw`: add a "destination" option to the "raw" directive? ::
1674 It needs thought & discussion though, to come up with a consistent
1675 set of destination labels and consistent behavior.
1677 And placing HTML code inside the <head> element of an HTML
1678 document is rather the job of a templating system.
1680 - _`body.sidebar`: Allow internal section structure? Adornment
1681 styles would be independent of the main document.
1683 That is really complicated, however, and the document model
1684 greatly benefits from its simplicity.
1686 * Implement directives. Each of the list items below begins with an
1687 identifier of the form, "module_name.directive_function_name". The
1688 directive name itself could be the same as the
1689 directive_function_name, or it could differ.
1693 It has the disadvantage that it's only easily implementable for
1694 HTML, so it's specific to one output format.
1696 (For non-HTML writers, the imagemap would have to be replaced with
1699 - _`parts.endnotes` (or "footnotes"): See `Footnote & Citation Gathering`_.
1701 - _`parts.citations`: See `Footnote & Citation Gathering`_.
1703 - _`misc.language`: Specify (= change) the language of a document at
1706 * The misc.settings_ directive suggested below offers a more generic
1709 * The language of document parts can be indicated by the "special class
1710 value" ``"language-"`` + `BCP 47`_ language code. Class arguments to
1711 the title are attached to the document's base node - hence titled
1712 documents can be given a different language at parse time. However,
1713 "language by class attribute" does not change parsing (localized
1714 directives etc.), only supporting writers.
1716 .. _BCP 47: https://www.rfc-editor.org/rfc/bcp/bcp47.txt
1719 - _`misc.settings`: Set any(?) Docutils runtime setting from within
1720 a document? Needs much thought and discussion.
1722 Security concerns need to be taken into account (it shouldn't be
1723 possible to enable ``file_insertion_enabled`` from within a
1724 document), and settings that only would have taken effect before
1725 the directive (like ``tab-width``) shouldn't be accessible either.
1727 See this sub-thread:
1728 <http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649>
1730 - _`misc.gather`: Gather (move, or copy) all instances of a specific
1731 element. A generalization of the `Footnote & Citation Gathering`_
1734 - Add a custom "directive" directive, equivalent to "role"? For
1739 .. class:: incremental
1743 "``.. incr::``" above is equivalent to "``.. class:: incremental``".
1747 .. directive:: printed-links
1753 :class: print-inline
1755 This acts like macros. The directive contents will have to be
1756 evaluated when referenced, not when defined.
1758 * Needs a better name? "Macro", "substitution"?
1759 * What to do with directive arguments & options when the
1760 macro/directive is referenced?
1762 - Make the meaning of block quotes overridable? Only a 1-shot
1763 though; doesn't solve the general problem.
1765 - _`conditional directives`:
1767 .. note:: See also the implementation in Sphinx_.
1769 Docutils already has the ability to say "use this content for
1770 Writer X" via the "raw" directive. It also does have the ability
1771 to say "use this content for any Writer other than X" via the
1772 "strip-elements with class" config value. However, using "raw"
1773 input just to select a special writer is inconvenient in many
1775 It wouldn't be difficult to get more straightforward support, though.
1777 My first idea would be to add a set of conditional directives.
1778 Let's call them "writer-is" and "writer-is-not" for discussion
1779 purposes (don't worry about implementation details). We might
1782 .. writer-is:: text-only
1798 .. figure:: protocol_stack.eps
1800 .. writer-is-not:: text-only pdf
1802 .. figure:: protocol_stack.png
1804 This could be an interface to the Filter transform
1805 (docutils.transforms.components.Filter).
1807 The ideas in the `adaptable file extensions`_ section above may
1808 also be applicable here.
1810 SVG's "switch" statement may provide inspiration.
1812 Here's an example of a directive that could produce multiple
1813 outputs (*both* raw troff pass-through *and* a GIF, for example)
1814 and allow the Writer to select. ::
1821 %sum from i=o to inf c sup i~=~lim from {m -> inf}
1822 sum from i=0 to m sup i%
1827 - _`body.example`: Examples; suggested by Simon Hefti. Semantics as
1828 per Docbook's "example"; admonition-style, numbered, reference,
1829 with a caption/title.
1831 - _`body.index`: Index targets.
1833 See `Index Entries & Indexes
1834 <./rst/alternatives.html#index-entries-indexes>`__.
1836 - _`body.literal`: Literal block, possibly "formal" (see `object
1837 numbering and object references`_ above). Possible options:
1839 - "highlight" a range of lines
1841 - include only a specified range of lines
1843 - "number" or "line-numbers"? (since 0.9 available with "code" directive)
1845 - "styled" could indicate that the directive should check for
1846 style comments at the end of lines to indicate styling or
1849 Specific derivatives (i.e., a "python-interactive" directive)
1850 could interpret style based on cues, like the ">>> " prompt and
1851 "input()"/"raw_input()" calls.
1853 See docutils-users 2003-03-03.
1855 - _`body.listing`: Code listing with title (to be numbered
1856 eventually), equivalent of "figure" and "table" directives.
1858 - _`pysource.usage`: Extract a usage message from the program,
1859 either by running it at the command line with a ``--help`` option
1860 or through an exposed API. [Suggestion for Optik.]
1862 - _`body.float`: Generic float that can be used for figures, tables,
1863 code listings, flowcharts, ...
1865 There is a Sphinx extension by Ignacio Fernández Galván <jellby@gmail.com>
1867 I implemented something for generic floats in sphinx, and submitted a
1868 pull request that is still waiting::
1872 :caption: My caption
1874 https://github.com/sphinx-doc/sphinx/pull/1858
1880 Interpreted text is entirely a reStructuredText markup construct, a
1881 way to get around built-in limitations of the medium. Some roles are
1882 intended to introduce new doctree elements, such as "title-reference".
1883 Others are merely convenience features, like "RFC".
1885 All supported interpreted text roles must already be known to the
1886 Parser when they are encountered in a document. Whether pre-defined
1887 in core/client code, or in the document, doesn't matter; the roles
1888 just need to have already been declared. Adding a new role may
1889 involve adding a new element to the DTD and may require extensive
1890 support, therefore such additions should be well thought-out. There
1891 should be a limited number of roles.
1893 The only place where no limit is placed on variation is at the start,
1894 at the Reader/Parser interface. Transforms are inserted by the Reader
1895 into the Transformer's queue, where non-standard elements are
1896 converted. Once past the Transformer, no variation from the standard
1897 Docutils doctree is possible.
1899 An example is the Python Source Reader, which will use interpreted
1900 text extensively. The default role will be "Python identifier", which
1901 will be further interpreted by namespace context into <class>,
1902 <method>, <module>, <attribute>, etc. elements (see pysource.dtd),
1903 which will be transformed into standard hyperlink references, which
1904 will be processed by the various Writers. No Writer will need to have
1905 any knowledge of the Python-Reader origin of these elements.
1907 * Add explicit interpreted text roles for the rest of the implicit
1908 inline markup constructs: named-reference, anonymous-reference,
1909 footnote-reference, citation-reference, substitution-reference,
1910 target, uri-reference (& synonyms).
1912 * Add directives for each role as well? This would allow indirect
1915 This text contains |nested inline markup|.
1917 .. |nested inline markup| emphasis::
1919 nested ``inline`` markup
1923 - "_`raw-wrapped`" (or "_`raw-wrap`"): Base role to wrap raw text
1924 around role contents.
1926 For example, the following reStructuredText source ... ::
1928 .. role:: red(raw-formatting)
1930 :html: <font color="red">
1931 :latex: {\color{red}
1938 ... will yield the following document fragment::
1942 <inline classes="red">
1945 <raw format="latex">
1947 <inline classes="red">
1951 <raw format="latex">
1954 Possibly without the intermediate "inline" node.
1956 - _`"acronym" and "abbreviation"`: Associate the full text with a
1957 short form. Jason Diamond's description:
1959 I want to translate ```reST`:acronym:`` into ``<acronym
1960 title='reStructuredText'>reST</acronym>``. The value of the
1961 title attribute has to be defined out-of-band since you can't
1962 parameterize interpreted text. Right now I have them in a
1963 separate file but I'm experimenting with creating a directive
1964 that will use some form of reST syntax to let you define them.
1966 Should Docutils complain about undefined acronyms or
1969 What to do if there are multiple definitions? How to
1970 differentiate between CSS (Content Scrambling System) and CSS
1971 (Cascading Style Sheets) in a single document? David Priest
1974 The short answer is: you don't. Anyone who did such a thing
1975 would be writing very poor documentation indeed. (Though I
1976 note that `somewhere else in the docs`__, there's mention of
1977 allowing replacement text to be associated with the
1978 abbreviation. That takes care of the duplicate
1979 acronyms/abbreviations problem, though a writer would be
1980 foolish to ever need it.)
1982 __ `inline parameter syntax`_
1984 How to define the full text? Possibilities:
1986 1. With a directive and a definition list? ::
1993 Docstring Processing System
1995 Would this list remain in the document as a glossary, or would
1996 it simply build an internal lookup table? A "glossary"
1997 directive could be used to make the intention clear.
1998 Acronyms/abbreviations and glossaries could work together.
2000 Then again, a glossary could be formed by gathering individual
2001 definitions from around the document.
2003 2. Some kind of `inline parameter syntax`_? ::
2005 `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
2006 see is what you get>`:acronym: plaintext markup.
2008 .. _inline parameter syntax:
2009 rst/alternatives.html#parameterized-interpreted-text
2011 3. A combination of 1 & 2?
2013 The multiple definitions issue could be handled by establishing
2014 rules of priority. For example, directive-based lookup tables
2015 have highest priority, followed by the first inline definition.
2016 Multiple definitions in directive-based lookup tables would
2017 trigger warnings, similar to the rules of `implicit hyperlink
2020 __ ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
2022 4. Using substitutions? ::
2024 .. |reST| acronym:: reST
2025 :text: reStructuredText
2027 What do we do for other formats than HTML which do not support
2028 tool tips? Put the full text in parentheses?
2030 - "figure", "table", "listing", "chapter", "page", etc: See `object
2031 numbering and object references`_ above.
2033 - "glossary-term": This would establish a link to a glossary. It
2034 would require an associated "glossary-entry" directive, whose
2035 contents could be a definition list::
2044 This would allow entries to be defined anywhere in the document,
2045 and collected (via a "glossary" directive perhaps) at one point.
2051 [DG 2017-01-02: These are not definitive to-dos, just one developer's
2052 opinion. Added 2009-10-13 by Günter Milde, in r6178.]
2053 [Updated by GM 2017-02-04]
2055 The number of doctree nodes can be reduced by "normalizing" some related
2056 nodes. This makes the document model and the writers somewhat simpler.
2058 * The "doctest" element can be replaced by literal blocks with a class
2059 attribute (similar to the "code" directive output).
2060 The syntax shall be left in reST.
2062 [DG 2017-01-02:] +0.
2065 The syntax could be left in reST (for a set period of time?).
2067 [DG 2017-01-02:] The syntax must be left in reST, practically
2068 forever. Removing it would introduce a huge backwards
2069 incompatibility. Any syntax removal must be preceded by a thorough
2070 review and planning, including a deprecation warning process. My
2071 opinion: it's not worth it.
2073 * "Normalize" special admonitions (note, hint, warning, ...) during parsing
2074 (similar to _`transforms.writer_aux.Admonitions`). There is no need to
2075 keep them as distinct elements in the doctree specification.
2077 [DG 2017-01-02:] -1: <note>{body}</> is much more concise and
2078 expressive than <admonition><title>Note</>{body}</>, and the title
2079 translation can be put off until much later in the process.
2083 -0 for <admonition class=note><title>Note</>... instead of <note>:
2084 a document is rarely printed/used as doctree or XML.
2086 +1 reduce the complexity of the doctree
2087 (there is no 1:1 rST syntax element <-> doctree node mapping anyway).
2089 +2 every writer needs 9 visit_*/depart_* method pairs to handle the 9
2090 subtypes of an admonition, i.e. we could but also remove 36 redundant
2091 methods (HTML, LaTeX, Manpage, ODF).
2093 -1 the most unfortunately named of these directives will survive. [#]_
2095 .. [#] with "biblical touch" and hard to translate:
2097 :admonition: | Ermahnung; Verweis; Warnung; Rüge
2098 | (exhortation; censure; warning; reprimand, rebuke)
2101 Keep the special admonition directives in reStructuredText syntax.
2103 [DG 2017-01-02:] We must definitely keep the syntax. Removing it
2104 would introduce a huge backwards incompatibility.
2107 Unimplemented Transforms
2108 ========================
2110 * _`Footnote & Citation Gathering`
2112 Collect and move footnotes & citations to the end of a document or the
2113 place of a "footnotes" or "citations" directive
2114 (see `<./ref/rst/directives.html>_`)
2117 Collect all footnotes that are referenced in the document before the
2118 directive (and after an eventually preceding ``.. footnotes::``
2119 directive) and insert at this place.
2121 Allows "endnotes" at a configurable place.
2124 Collect citations that are referenced ...
2128 a) defined in the document as citation elements
2130 b) auto-generated from entries in a bibliographic database.
2132 + based on bibstuff_?
2133 + also have a look at
2135 * CrossTeX_, a backwards-compatible, improved bibtex
2136 re-implementation in Python (including HTML export).
2137 (development stalled since 2 years)
2139 * Pybtex_,a drop-in replacement for BibTeX written in Python.
2141 * BibTeX styles & (experimental) pythonic style API.
2142 * Database in BibTeX, BibTeXML and YAML formats.
2143 * full Unicode support.
2144 * Write to TeX, HTML and plain text.
2146 * `Zotero plain <http://e6h.org/%7Eegh/hg/zotero-plain/>`__
2147 supports Zotero databases and CSL_ styles with Docutils with an
2150 * `sphinxcontrib-bibtex`_ Sphinx extension with "bibliography"
2151 directive and "cite" role supporting BibTeX databases.
2153 * `Modified rst2html
2154 <http://www.loria.fr/~rougier/coding/article/rst2html.py>`__ by
2158 * Automatically insert a "References" heading?
2160 .. _CrossTeX: http://www.cs.cornell.edu/people/egs/crosstex/
2161 .. _Pybtex: http://pybtex.sourceforge.net/
2162 .. _CSL: http://www.citationstyles.org/
2163 .. _sphinxcontrib-bibtex: http://sphinxcontrib-bibtex.readthedocs.org/
2165 * _`Reference Merging`
2167 When merging two or more subdocuments (such as docstrings),
2168 conflicting references may need to be resolved. There may be:
2170 * duplicate reference and/or substitution names that need to be made
2172 * duplicate footnote numbers that need to be renumbered.
2174 Should this be done before or after reference-resolving transforms
2175 are applied? What about references from within one subdocument to
2178 * _`Document Splitting`
2180 If the processed document is written to multiple files (possibly in
2181 a directory tree), it will need to be split up. Internal references
2182 will have to be adjusted.
2184 (HTML only? Initially, yes. Eventually, anything should be
2189 - Insert a "destination" attribute into the root element of each
2190 split-out document, containing the path/filename. The Output
2191 object or Writer will recognize this attribute and split out the
2192 files accordingly. Must allow for common headers & footers,
2193 prev/next, breadcrumbs, etc.
2195 - Transform a single-root document into a document containing
2196 multiple subdocuments, recursively. The content model of the
2197 "document" element would have to change to::
2200 ( (title, subtitle?)?,
2202 (docinfo, transition?)?,
2206 (I.e., add the last line -- 0 or more document elements.)
2208 Let's look at the case of hierarchical (directories and files)
2209 HTML output. Each document element containing further document
2210 elements would correspond to a directory (with an index.html file
2211 for the content preceding the subdocuments). Each document
2212 element containing no subdocuments (i.e., structure model elements
2213 only) corresponds to a concrete file with no directory.
2215 The natural transform would be to map sections to subdocuments,
2216 but possibly only a given number of levels deep.
2220 If a document is split up, each segment will need navigation links:
2221 parent, children (small TOC), previous (preorder), next (preorder).
2222 Part of `Document Splitting`_?
2224 * _`List of System Messages`
2226 The ``system_message`` elements are inserted into the document tree,
2227 adjacent to the problems themselves where possible. Some (those
2228 generated post-parse) are kept until later, in
2229 ``document.messages``, and added as a special final section,
2230 "Docutils System Messages".
2232 Docutils could be made to generate hyperlinks to all known
2233 system_messages and add them to the document, perhaps to the end of
2234 the "Docutils System Messages" section.
2236 Fred L. Drake, Jr. wrote:
2238 I'd like to propose that both parse- and transformation-time
2239 messages are included in the "Docutils System Messages" section.
2240 If there are no objections, I can make the change.
2242 The advantage of the current way of doing things is that parse-time
2243 system messages don't require a transform; they're already in the
2244 document. This is valuable for testing (unit tests,
2245 tools/dev/quicktest.py). So if we do decide to make a change, I think
2246 the insertion of parse-time system messages ought to remain as-is
2247 and the Messages transform ought to move all parse-time system
2248 messages (remove from their originally inserted positions, insert in
2249 System Messages section).
2251 * _`Index Generation`
2257 * Make the _`list compacting` logic more generic: For example, allow
2258 for literal blocks or line blocks inside of compact list items.
2260 This is not implementable as long as list compacting is done by
2261 omitting ``<p>`` tags. List compacting would need to be done by
2262 adjusting CSS margins instead.
2264 :2015-04-02: The new html writer no longer strips <p> tags but adds the
2265 class value ``simple`` to the list.
2266 Formatting is done by CSS --- configurable by a custom style
2269 Auto-compactization can be overridden by the ``open`` vs.
2270 ``compact`` class arguments.
2272 * Idea for field-list rendering: hanging indent::
2274 Field name (bold): First paragraph of field body begins
2275 with the field name inline.
2277 If the first item of a field body is not a paragraph,
2278 it would begin on the following line.
2280 :2015-04-02: The new html writer writes field-lists as definition lists
2281 with class ``field-list``.
2282 Formatting is done by CSS --- configurable by a custom style
2283 sheet. The default style sheet has some examples, including a
2284 run-in field-list style.
2286 * Add more support for <link> elements, especially for navigation
2289 The framework does not have a notion of document relationships, so
2290 probably raw.destination_ should be used.
2292 We'll have framework support for document relationships when support
2293 for `multiple output files`_ is added. The HTML writer could
2294 automatically generate <link> elements then.
2296 .. _raw.destination: misc.raw_
2298 * Base list compaction on the spacing of source list? Would require
2299 parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)
2301 * Add a tool tip ("title" attribute?) to footnote back-links
2302 identifying them as such. Text in Docutils language module.
2304 * Set HTML "width" and "height" attributes with the original size (read
2305 from the image) to prevent *layout shifts*:
2307 Layout shifts are very disrupting to the user, especially if you have
2308 already started reading the article and suddenly you are thrown off
2309 by a jolt of movement, and you have to find your place again.
2311 -- `Setting Height And Width On Images Is Important Again`__
2313 - If there are no size options (``:widht:``, ``:height:``, ``:scale:``)
2314 in the "image" directive and
2315 the image is *local* and can be read and interpreted by PIM.
2316 (if not, silently skip).
2318 - Alternatively, if the only size option is ``:scale: 100%`` and the
2319 image can be read with urllib (*opt-in* for the "costly" variant).
2321 __ https://www.smashingmagazine.com/2020/03/setting-height-width-images-important-again/.
2327 * Remove the generic style information (duplicated from html4css1.css)
2328 from pep.css to avoid redundancy.
2330 Set ``stylesheet-path`` to "html4css.css,pep.css" and the
2331 ``stylesheet-dirs`` accordingly instead. (See the xhtml11 writer for an
2338 * Add a way to begin an untitled slide.
2340 * Add a way to begin a new slide, continuation, using the same title
2341 as the previous slide? (Unnecessary?) You need that if you have a
2342 lot of items in one section which don't fit on one slide.
2344 Maybe either this item or the previous one can be realized using
2347 * Have a timeout on incremental items, so the colour goes away after 1
2350 * Add an empty, black last slide (optionally). Currently the handling
2351 of the last slide is not very nice, it re-cycles through the
2352 incremental items on the last slide if you hit space-bar after the
2355 * Add a command-line option to disable advance-on-click.
2357 * Add a speaker's master document, which would contain a small version
2358 of the slide text with speaker's notes interspersed. The master
2359 document could use ``target="whatever"`` to direct links to a
2360 separate window on a second monitor (e.g., a projector).
2362 .. Note:: This item and the following items are partially
2363 accomplished by the S5 1.2 code (currently in alpha), which has
2364 not yet been integrated into Docutils.
2366 * Speaker's notes -- how to intersperse? Could use reST comments
2367 (".."), but make them visible in the speaker's master document. If
2368 structure is necessary, we could use a "comment" directive (to avoid
2369 nonsensical DTD changes, the "comment" directive could produce an
2370 untitled topic element).
2372 The speaker's notes could (should?) be separate from S5's handout
2375 * The speaker's master document could use frames for easy navigation:
2376 TOC on the left, content on the right.
2378 - It would be nice if clicking in the TOC frame simultaneously
2379 linked to both the speaker's notes frame and to the slide window,
2380 synchronizing both. Needs JavaScript?
2382 - TOC would have to be tightly formatted -- minimal indentation.
2384 - TOC auto-generated, as in the PEP Reader. (What if there already
2385 is a "contents" directive in the document?)
2387 - There could be another frame on the left (top-left or bottom-left)
2388 containing a single "Next" link, always pointing to the next slide
2389 (synchronized, of course). Also "Previous" link? FF/Rew go to
2390 the beginning of the next/current parent section? First/Last
2391 also? Tape-player-style buttons like ``|<< << < > >> >>|``?
2396 Add epub as an output format.
2398 epub is an open file format for ebooks based on HTML, specified by the
2399 `International Digital Publishing Forum`_. Thus, documents in epub
2400 format are suited to be read with `electronic reading devices`_.
2402 Pack the output of a HTML writer and supporting files (e.g. images)
2403 into one single epub document.
2405 There are `links to two 3rd party ePub writers`__ in the Docutils link list.
2406 Test and consider moving the better one into the docutils core.
2408 __ ../user/links.html#ePub
2409 .. _International Digital Publishing Forum: http://www.idpf.org/
2410 .. _electronic reading devices:
2411 https://en.wikipedia.org/wiki/List_of_e-book_readers
2417 Also see the Problems__ section in the `latex writer documentation`_.
2419 __ ../user/latex.html#problems
2421 .. _latex writer documentation: ../user/latex.html
2424 ../../../sandbox/latex-variants/README.html
2429 * Too deeply nested lists fail: generate a warning and provide
2432 2017-02-09 this is fixed for enumeration in 0.13.1
2434 for others, cf. sandbox/latex-variants/tests/rst-levels.txt
2436 * File names of included graphics (see also `grffile` package).
2438 * Paragraph following field-list or table in compound is indented.
2440 This is a problem with the current DUfieldlist definition and with the
2441 use of "longtable" for tables. See `other LaTeX constructs and packages
2442 instead of re-implementations`_ for alternatives.
2445 Generate clean and configurable LaTeX source
2446 ----------------------------------------------
2448 Which packages do we want to use?
2450 + base and "recommended" packages
2452 (packages that should be in a "reasonably sized and reasonably modern
2453 LaTeX installation like the `texlive-latex-recommended` Debian package,
2456 + No "fancy" or "exotic" requirements.
2458 + pointers to advanced packages and their use in the `latex writer
2461 Configurable placement of figure and table floats
2462 `````````````````````````````````````````````````
2464 * Special class argument to individually place figures?
2469 :class: place-here-if-possible place-top place-bottom
2471 would be written as ``\figure[htb]{...}`` with
2475 :h: place-here-if-possible
2478 :p: place-on-extra-page
2480 Alternative: class value = "place-" + optional arg, e.g. ``:class:
2486 + True footnotes with LaTeX auto-numbering (as option ``--latex-footnotes``)
2487 (also for target-footnotes):
2488 Write ``\footnote{<footnote content>}`` at the place of the
2489 ``<footnote_reference>`` node.
2493 - Load hyperref_ with option "hyperfootnotes" and/or
2494 package footnotebackref_ or leave this to the user?
2496 - Consider cases where LaTeX does not support footnotes
2497 (inside tables__, headings__, caption, ...).
2498 Use ftnxtra_, tabularx_, tabulary_, longtable_?
2500 __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab
2501 __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect
2503 - Consider `multiple footnote refs to common footnote text`__.
2505 KOMA-script classes and the KOMA scrextend_ package provide
2506 ``\footref`` that can be used for additional references to a
2507 ``\label``-ed footnote. Since 2021-05-01, ``\footref`` is provided
2508 by the LaTeX core, too.
2510 __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot
2512 - Consider numbered vs. symbolic footnotes.
2514 + document customization (links to how-to and packages)
2516 .. Footnote packages at CTAN (www.ctan.org/pkg/<packagename>):
2518 :footnote: provides a "savenotes" environment which collects all
2519 footnotes and emits them at ``end{savenotes}``
2520 (texlive-latex-recommended)
2522 :ftnxtra_: fixes the issue of footnote inside \caption{},
2523 tabular environment and \section{} like commands.
2525 :footnotebackref_: bidirectional links to/from footnote mark to
2528 .. Footnote Discussion:
2531 <http://www2.informatik.hu-berlin.de/~ahamann/studies/footnotes.pdf>`__
2533 `wikibooks: footnote workarounds
2534 <https://en.wikibooks.org/wiki/LaTeX/Footnotes_and_Margin_Notes#Common_problems_and_workarounds>`__
2536 .. _footnotebackref: https://www.ctan.org/pkg/footnotebackref
2537 .. _ftnxtra: https://www.ctan.org/pkg/ftnxtra
2538 .. _hyperref: https://www.ctan.org/pkg/hyperref
2539 .. _longtable: https://www.ctan.org/pkg/longtable
2540 .. _scrextend: https://www.ctan.org/pkg/longtable
2541 .. _tabularx: https://www.ctan.org/pkg/tabularx
2544 Other LaTeX constructs and packages instead of re-implementations
2545 `````````````````````````````````````````````````````````````````
2547 * Check the generated source with package `nag`.
2549 * enumitem_ (texlive-latex-extra) for field-lists?
2551 .. _enumitem: https://www.ctan.org/pkg/enumitem
2556 * Use italic instead of slanted for titlereference?
2558 * Start a new paragraph after lists (as currently)
2559 or continue (no blank line in source, no parindent in output)?
2563 * continue if the `compound paragraph`_ directive is used (as currently),
2565 * force a new paragraph with an empty comment.
2567 * Sidebar handling (environment with `framed`, `marginnote`, `wrapfig`,
2570 * Use optionlist for docinfo?
2572 * Keep literal-blocks together on a page, avoid pagebreaks.
2574 Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
2577 Should be possible with ``--literal-block-env==lstlistings`` and some
2580 * More space between title and subtitle? ::
2583 + \\[0.5em] % subtitle%
2585 .. _compound paragraph:
2586 ../ref/rst/directives.html#compound-paragraph
2591 * Improve/simplify logic to set the column width in the output.
2593 + Assumed reST line length for table width setting configurable, or
2594 + use `ltxtable` (a combination of `tabularx` (auto-width) and
2595 `longtable` (page breaks)), or
2596 + use tabularx column type ``X`` and let LaTeX decide width, or
2599 .. _tabulary: https://www.ctan.org/pkg/tabulary
2601 * From comp.text.tex (13. 4. 2011):
2603 When using fixed width columns, you should ensure that the total
2604 width does not exceed \linewidth: if the first column is p{6cm}
2605 the second one should be p{\dimexpr\linewidth-6cm-4\tabcolsep}
2606 because the glue \tabcolsep is added twice at every column edge.
2607 You may also consider to set \tabcolsep to a different value...
2609 * csv-tables do not have a colwidth.
2611 * Add more classes or options, e.g. for
2613 + horizontal alignment and rules.
2614 + long table vs. tabular (see next item).
2616 * Use tabular instead of longtable for tables in legends or generally
2619 Alternatively, default to tabular and use longtable only if specified
2620 by config setting or class argument (analogue to booktable)?
2622 * Table heads and footer for longtable (firstpage lastpage ..)?
2624 * In tools.txt the option tables right column, there should be some more
2625 spacing between the description and the next paragraph "Default:".
2627 * Paragraph separation in tables is hairy.
2628 see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
2630 - The strut solution did not work.
2631 - setting extrarowheight added ad top of row not between paragraphs in
2632 a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
2633 - baselineskip/stretch does not help.
2635 * Should there be two hlines after table head and on table end?
2637 * Place titled tables in a float ('table' environment)?
2639 The 'table', 'csv-table', and 'list-table' directives support an (optional)
2640 table title. In analogy to the 'figure' directive this should map to a
2643 Image and figure directives
2644 ```````````````````````````
2646 * compare the test case in:
2648 + `<../../test/functional/input/data/standard.txt>`__
2649 + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
2650 + `<../../test/functional/expected/standalone_rst_latex.tex>`__
2652 * The default CSS styling for HTML output (plain.css, default.css) lets
2653 text following a right- or left-aligned image float to the side of the
2656 + Use this default also for LaTeX?
2658 + Wrap text around figures/images with class argument "wrap"
2659 (like the odt writer)?
2661 Use `wrapfig` (or other recommended) package.
2663 * support more graphic formats (especially SVG, the only standard
2664 vector format for HTML)
2670 * support "figwidth" argument for figures.
2672 As the 'figwidth' argument is still ignored and the "natural width" of
2673 a figure in LaTeX is 100 % of the text width, setting the 'align'
2674 argument has currently no effect on the LaTeX output.
2676 * Multiple author entries in docinfo (same thing as in html).
2678 * Consider supporting the "compact" option and class argument (from
2679 rst2html) as some lists look better compact and others need the space.
2681 * Better citation support
2682 (see `Footnote & Citation Gathering`_).
2684 * If ``use-latex-citations`` is used, a bibliography is inserted right at the
2685 end of the document.
2687 Put in place of the to-be-implemented "citations" directive
2688 (see `Footnote & Citation Gathering`_).
2694 The `LyX <http://www.lyx.org>`_ document processor has a comprehensive
2695 Unicode to LaTeX conversion feature with a file called ``unicodesymbols``
2696 that lists LaTeX counterparts for a wide range of Unicode characters.
2698 * Use this in the LaTeXTranslator?
2699 Think of copyright issues!
2701 * The "ucs" package has many translations in ...doc/latex/ucs/config/
2703 * The bibstuff_ tool ships a `latex_codec` Python module!
2705 .. _bibstuff: http://code.google.com/p/bibstuff/
2711 * Glyphs missing in the font are left out in the PDF without warning
2712 (e.g. ⇔ left-right double arrow in the functional test output).
2714 * Disable word-wrap (hyphenation) in literal text locally with
2715 ``providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}``?
2721 * ^^ LaTeX's special syntax for characters results in "strange" replacements
2722 (both with \href and \url).
2724 `file with ^^ <../strange^^name>`__:
2725 `<../strange^^name>`__
2727 * Unbalanced braces, { or }, will fail (both with \href and \url)::
2729 `file with { <../strange{name>`__
2730 `<../strange{name>`__
2732 Currently, a warning is written to the error output stream.
2734 For correct printing, we can
2736 * use the \href command with "normal" escaped name argument, or
2737 * define a url-command in the preamble ::
2739 \urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}
2741 but need to find a way to insert it as href argument.
2743 The following fails::
2745 \href{https://www.w3.org/XML/Schema^^dev}{\fragileURLi}
2747 Use %-replacement like http://nowhere/url_with%28parens%29 ?
2749 -> does not work for file paths (with pdflatex and xpdf).
2752 add-stylesheet option
2753 `````````````````````
2755 From http://article.gmane.org/gmane.text.docutils.devel/3429/
2757 The problem is that since we have a default value, we have to
2758 differentiate between adding another stylesheet and replacing the
2759 default. I suggest that the existing --stylesheet & --stylesheet-path
2760 options keep their semantics to replace the existing settings. We
2761 could introduce new --add-stylesheet & --add-stylesheet-path options,
2762 which accumulate; further --stylesheet/--stylesheet-path options would
2763 clear these lists. The stylesheet or stylesheet_path setting (only
2764 one may be set), plus the added_stylesheets and added_stylesheet_paths
2765 settings, describe the combined styles.
2767 For example, this run will have only one custom stylesheet:
2769 rstpep2html.py --stylesheet-path custom.css ...
2771 This run will use the default stylesheet, and the custom one:
2773 rstpep2html.py --add-stylesheet-path custom.css ...
2775 This run will use the default stylesheet, a custom local stylesheet,
2776 and an external stylesheet:
2778 rstpep2html.py --add-stylesheet-path custom.css \
2779 --add-stylesheet https://www.example.org/external.css ...
2781 This run will use only the second custom stylesheet:
2783 rstpep2html.py --add-stylesheet-path custom.css \
2784 --stylesheet-path second.css ...
2792 * Parameterize help text & defaults somehow? Perhaps a callback? Or
2793 initialize ``settings_spec`` in ``__init__`` or ``init_options``?
2795 * Disable common options that don't apply?
2796 (This should now be easier with ``frontend.filter_settings_spec``.)
2798 * Add ``--section-numbering`` command line option. The "sectnum"
2799 directive should override the ``--no-section-numbering`` command
2802 * Implement the following suggestions from clig.dev?
2804 Display output on success, but keep it brief.
2805 provide a --quiet option to suppress all non-essential output.
2807 Consider chaining several args as input and use --output
2808 (or redirection) for output.
2810 -- https://clig.dev/#help
2812 .. _partial parsing:
2813 https://docs.python.org/3/library/argparse.html#partial-parsing
2815 .. _configuration: ../user/config.html
2816 .. _transforms: ../api/transforms.html
2824 indent-tabs-mode: nil
2825 sentence-end-double-space: t