CINXE.COM

<!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta charset="utf-8" /> <meta name="generator" content="Docutils 0.22b.dev: https://docutils.sourceforge.io/" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="author" content="David Goodger (with input from many); open to all Docutils developers" /> <meta name="dcterms.date" content="2024-08-15" /> <meta name="dcterms.rights" content="This document has been placed in the public domain." /> <title>Docutils To Do List</title> <link rel="schema.dcterms" href="http://purl.org/dc/terms/"/> <link rel="stylesheet" href="../../docutils/writers/html5_polyglot/minimal.css" type="text/css" /> <link rel="stylesheet" href="../../docutils/writers/html5_polyglot/responsive.css" type="text/css" /> <link rel="stylesheet" href="../../docutils/writers/html5_polyglot/italic-field-names.css" type="text/css" /> </head> <body class="with-toc"> <header> <a class="reference external" href="https://docutils.sourceforge.io">Docutils</a> | <a class="reference external" href="../index.html">Overview</a> | <a class="reference external" href="../index.html#project-fundamentals">About</a> | <a class="reference external" href="../index.html#user">Users</a> | <a class="reference external" href="../index.html#ref">Reference</a> | <a class="reference external" href="../index.html#howto">Developers</a> </header> <main id="docutils-to-do-list"> <h1 class="title"><a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> To Do List</h1> <dl class="docinfo"> <dt class="author">Author:</dt> <dd class="author">David Goodger (with input from many); open to all Docutils developers</dd> <dt class="contact">Contact:</dt> <dd class="contact"><a class="reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></dd> <dt class="date">Date:</dt> <dd class="date">2024-08-15</dd> <dt class="revision">Revision:</dt> <dd class="revision">9906</dd> <dt class="copyright">Copyright:</dt> <dd class="copyright">This document has been placed in the public domain.</dd> </dl>  <nav class="contents" id="contents" role="doc-toc"> <a class="reference internal" href="#top">Contents</a> <ul class="simple"> <li><a class="reference internal" href="#minimum-requirements-for-python-standard-library-candidacy" id="toc-entry-1">Minimum Requirements for Python Standard Library Candidacy</a></li> <li><a class="reference internal" href="#repository" id="toc-entry-2">Repository</a></li> <li><a class="reference internal" href="#general" id="toc-entry-3">General</a> <ul> <li><a class="reference internal" href="#miscellaneous" id="toc-entry-4">Miscellaneous</a></li> <li><a class="reference internal" href="#object-numbering-and-object-references" id="toc-entry-5">object numbering and object references</a></li> </ul> </li> <li><a class="reference internal" href="#documentation" id="toc-entry-6">Documentation</a> <ul> <li><a class="reference internal" href="#user-docs" id="toc-entry-7">User Docs</a></li> <li><a class="reference internal" href="#developer-docs" id="toc-entry-8">Developer Docs</a></li> <li><a class="reference internal" href="#how-tos" id="toc-entry-9">How-Tos</a></li> <li><a class="reference internal" href="#peps" id="toc-entry-10">PEPs</a></li> </ul> </li> <li><a class="reference internal" href="#python-source-reader" id="toc-entry-11">Python Source Reader</a></li> <li><a class="reference internal" href="#restructuredtext-parser" id="toc-entry-12">reStructuredText Parser</a> <ul> <li><a class="reference internal" href="#bugs-1" id="toc-entry-13">Bugs</a></li> <li><a class="reference internal" href="#misc" id="toc-entry-14">Misc</a></li> <li><a class="reference internal" href="#adaptable-file-extensions" id="toc-entry-15">Adaptable file extensions</a> <ul> <li><a class="reference internal" href="#questions" id="toc-entry-16">Questions</a></li> <li><a class="reference internal" href="#proposals" id="toc-entry-17">Proposals</a></li> </ul> </li> <li><a class="reference internal" href="#math-markup" id="toc-entry-18">Math Markup</a> <ul> <li><a class="reference internal" href="#alternative-input-formats" id="toc-entry-19">alternative input formats</a></li> <li><a class="reference internal" href="#latex-output" id="toc-entry-20">LaTeX output</a></li> <li><a class="reference internal" href="#html-output" id="toc-entry-21">HTML output</a></li> <li><a class="reference internal" href="#openoffice-output" id="toc-entry-22">OpenOffice output</a></li> </ul> </li> <li><a class="reference internal" href="#directives" id="toc-entry-23">Directives</a></li> <li><a class="reference internal" href="#interpreted-text" id="toc-entry-24">Interpreted Text</a></li> <li><a class="reference internal" href="#doctree-pruning" id="toc-entry-25">Doctree pruning</a></li> </ul> </li> <li><a class="reference internal" href="#unimplemented-transforms" id="toc-entry-26">Unimplemented Transforms</a></li> <li><a class="reference internal" href="#html-writer" id="toc-entry-27">HTML Writer</a></li> <li><a class="reference internal" href="#pep-html-writer" id="toc-entry-28">PEP/HTML Writer</a></li> <li><a class="reference internal" href="#s5-html-writer" id="toc-entry-29">S5/HTML Writer</a></li> <li><a class="reference internal" href="#epub-html-writer" id="toc-entry-30">Epub/HTML Writer</a></li> <li><a class="reference internal" href="#latex-writer" id="toc-entry-31">LaTeX writer</a> <ul> <li><a class="reference internal" href="#bug-fixes" id="toc-entry-32">Bug fixes</a></li> <li><a class="reference internal" href="#generate-clean-and-configurable-latex-source" id="toc-entry-33">Generate clean and configurable LaTeX source</a> <ul> <li><a class="reference internal" href="#configurable-placement-of-figure-and-table-floats" id="toc-entry-34">Configurable placement of figure and table floats</a></li> <li><a class="reference internal" href="#footnotes" id="toc-entry-35">Footnotes</a></li> <li><a class="reference internal" href="#other-latex-constructs-and-packages-instead-of-re-implementations" id="toc-entry-36">Other LaTeX constructs and packages instead of re-implementations</a></li> </ul> </li> <li><a class="reference internal" href="#default-layout" id="toc-entry-37">Default layout</a> <ul> <li><a class="reference internal" href="#tables" id="toc-entry-38">Tables</a></li> <li><a class="reference internal" href="#image-and-figure-directives" id="toc-entry-39">Image and figure directives</a></li> </ul> </li> <li><a class="reference internal" href="#missing-features" id="toc-entry-40">Missing features</a> <ul> <li><a class="reference internal" href="#unicode-to-latex" id="toc-entry-41">Unicode to LaTeX</a></li> <li><a class="reference internal" href="#xetex-writer" id="toc-entry-42">XeTeX writer</a></li> <li><a class="reference internal" href="#problematic-urls" id="toc-entry-43">problematic URLs</a></li> <li><a class="reference internal" href="#add-stylesheet-option" id="toc-entry-44">add-stylesheet option</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#front-end-tools" id="toc-entry-45">Front-End Tools</a></li> </ul> </nav> Priority items are marked with "@" symbols. The more @s, the higher the priority. Items in question form (containing "?") are ideas which require more thought and debate; they are potential to-do's. Many of these items are awaiting champions. If you see something you'd like to tackle, please do! Please see also the <a class="reference external" href="../../BUGS.html">Bugs</a> document for a list of bugs in Docutils. <section id="minimum-requirements-for-python-standard-library-candidacy"> <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Minimum Requirements for Python Standard Library Candidacy</a><a class="self-link" title="link to this section" href="#minimum-requirements-for-python-standard-library-candidacy"></a></h2> Below are action items that must be added and issues that must be addressed before Docutils can be considered suitable to be proposed for inclusion in the Python standard library. Many of these are now handled by <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a> <ul class="simple"> <li>Support for <a class="reference internal" href="#document-splitting">document splitting</a>. May require some major code rework.</li> <li>Support for subdocuments (see <a class="reference internal" href="#large-documents">large documents</a>).</li> <li><a class="reference internal" href="#object-numbering-and-object-references">Object numbering and object references</a>.</li> <li><a class="reference internal" href="#nested-inline-markup">Nested inline markup</a>.</li> <li><a class="reference internal" href="#python-source-reader">Python Source Reader</a>.</li> <li>The HTML writer needs to be rewritten (or a second HTML writer added) to allow for custom classes, and for arbitrary splitting (stack-based?).</li> <li><a class="reference internal" href="#documentation">Documentation</a> of the architecture. Other docs too.</li> <li>Plugin support.</li> <li>Suitability for <a class="reference external" href="https://docutils.sourceforge.io/sandbox/README.html#documenting-python">Python module documentation</a>.</li> </ul> </section> <section id="repository"> <h2><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Repository</a><a class="self-link" title="link to this section" href="#repository"></a></h2> Move to a Git repository. <ul> <li>This is a long standing <a class="reference external" href="https://sourceforge.net/p/docutils/feature-requests/58/">feature request</a> (with pointers to Sphinx issues and discussion). </li> <li>From a <a class="reference external" href="https://sourceforge.net/p/docutils/mailman/message/31878077/">post by David Goodger</a> <blockquote> An absolute requirement, for me, is that such a change be complete. We can't lose any data or have to refer to the old system as an "archive". So all the SVN history, all branches, and the full sandbox need to be converted at the same time. </blockquote> </li> </ul> Convert with <a class="reference external" href="http://www.catb.org/esr/reposurgeon/">reposurgeon</a>? <blockquote> If you are doing a full import rather than gatewaying, reposurgeon is probably what you want. It has been tested against a lot of large, old, nasty repositories and is thus known to be robust in the presence of repository malformations (a property regularly checked by a test suite that is a rogue's gallery of Subversion botches). —<a class="reference external" href="https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools#Subversion">Git Wiki</a> </blockquote> The comprehensive <a class="reference external" href="http://www.catb.org/esr/reposurgeon/repository-editing.html">Reposurgeon documentation</a> comes with <a class="reference external" href="http://www.catb.org/esr/reposurgeon/repository-editing.html#conversion">a guide to repository conversion</a> as well as info about <a class="reference external" href="http://www.catb.org/esr/reposurgeon/repository-editing.html#_reading_subversion_repositories">reading Subversion repositories</a>. Converting from an SVN dump file is faster than from a checkout. Adam Turner wrote a conversion Makefile and .lift scripts that downloads the repo from SF with rsync, converts it to a SVN mirror and finally to Git, splitting sandbox, prest, and web from docutils. Sourceforge supports multiple Git repositories per project, so we can switch the version control system independent of the decision on an eventual switch of the host. Cf. <a class="reference external" href="https://sourceforge.net/p/forge/documentation/Git/">https://sourceforge.net/p/forge/documentation/Git/</a> </section> <section id="general"> <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">General</a><a class="self-link" title="link to this section" href="#general"></a></h2> <section id="miscellaneous"> <h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Miscellaneous</a><a class="self-link" title="link to this section" href="#miscellaneous"></a></h3> <dl> <dt>Code cleanup and modernization:</dt> <dd>Use <a class="reference external" href="https://pypi.org/project/flake8/">flake8</a>? See also the configuration in <a class="reference external" href="../../tox.ini">../../tox.ini</a>. Check and solve issue from <a class="reference external" href="https://peps.python.org/pep-0290">PEP 290</a> - Code Migration and Modernization. (Covers issues up to Python 2.4, is there an equivalent for more recent modernizations?) Ensure <a class="reference external" href="policies.html#backwards-compatibility-policy">backwards compatibility</a>! </dd> </dl> <ul> <li>Improve handling on Windows: <ul class="simple"> <li>Get graphical installer.</li> <li>Make rst2html.py an .exe file using py2exe. (Is this still required after we have "console scripts" entry points? GM 2023-06-25)</li> </ul> </li> <li>The user interface is very difficult to use for most Windows users; you can't really expect them to use the command line. We need some kind of GUI that can launch rst2html, and save the HTML output to a file, and launch a browser. What's important is that we get settings to work with the GUI. So we need some way to dynamically generate a list of settings for the GUI. The current settings_spec for OptionParser doesn't seem to be usable for this for the following reasons: <ul class="simple"> <li>It's biased toward the command line -- there are two options for one boolean setting.</li> <li>You cannot have both a one-line description and a longer description for tooltips/help-texts.</li> <li>It doesn't provide hints for the input type. You cannot easily infer the type of a setting from its validator, because any component can add new validators. In fact, it may be necessary to have both a hint about the input type (e.g. string) and a validator (valid ID), or it may be necessary to have a different set of choices for the CLI (1, INFO, 2, ...) and for the GUI (INFO, WARNING, ...).</li> <li>It's coupled to the OptionParser. We want to be able to change the underlying system without breaking everything.</li> <li>It's a bunch of primitive structures. We want an extensible (thus object-oriented) interface.</li> </ul> So we probably need to create a class for storing all the settings, and auto-generate the OptionParser data from that. I talked to Stephan Deibel about getting Docutils integrated into Wing IDE. He said it's possible, and he'd be willing to help. There's a scripting interface to Wing, which we'd use. We can dynamically generate a list of preferences and not worry too much about the rendering (from what I understood); Wing's whole GUI is dynamic anyway. The interface could be made usable for other GUIs. For example, we could try to get option support for DocFactory. // FW </li> <li>Allow different report levels for STDERR and system_messages inside the document?</li> <li>Change the docutils-update script (in sandbox/infrastructure), to support arbitrary branch snapshots.</li> <li>Move some general-interest sandboxes out of individuals' directories, into subprojects?</li> <li>Add option for file (and URL) access restriction to make Docutils usable in Wikis and similar applications. 2005-03-21: added file_insertion_enabled & raw_enabled settings. These partially solve the problem, allowing or disabling all file accesses, but not limited access. </li> <li><a class="reference external" href="../user/config.html">Configuration</a> file handling needs discussion: <ul class="simple"> <li>There should be some error checking on the contents of config files. How much checking should be done? How loudly should Docutils complain if it encounters an error/problem?</li> <li>Docutils doesn't complain when it doesn't find a configuration file supplied with the --config option. Should it? (If yes, error or warning?)</li> </ul> </li> <li>Internationalization: <ul> <li>I18n needs refactoring, the language dictionaries are difficult to maintain. Maybe have a look at gettext or similar tools. (This would make a nice Google Summer of Code project) </li> <li>Language modules: in accented languages it may be useful to have both accented and unaccented entries in the bibliographic_fields mapping for versatility.</li> <li>Add a "--strict-language" option & setting: no English fallback for language-dependent features. Make this the default for output (as opposed to input)? Throw an error with a helpful message, e.g. <blockquote> Default "contents" title for language %s missing, please specify an explicit title. </blockquote> or <blockquote> "attention" title for language %s missing, please use a generic admonition with explicit title. </blockquote> </li> <li>Add internationalization to footer boilerplate text (resulting from "--generator", "--source-link", and "--date" etc.), allowing translations.</li> </ul> </li> <li>Add validation? See <a class="reference external" href="http://pytrex.sourceforge.net">http://pytrex.sourceforge.net</a>, RELAX NG, pyRXP.</li> <li>In docutils.readers.get_reader_class (& parsers & writers too), should we be importing "standalone" or "docutils.readers.standalone"? (This would avoid importing top-level modules if the module name is not in docutils/readers. Potential nastiness.)</li> <li>Perhaps store a name-to-id mapping file? This could be stored permanently, read by subsequent processing runs, and updated with new entries. ("Persistent ID mapping"?)</li> <li>Perhaps the Component.supports method should deal with individual features ("meta" etc.) instead of formats ("html" etc.)? Currently, it is not used at all. Do we need it at all? Or rather let the writers just ignore some nodes (like we already do for "class" values)? The current implementation of the framework also leads to bug <a class="reference external" href="https://sourceforge.net/p/docutils/bugs/241/">bug #241</a> "doctree-based publishing != publish_string". The "components.Filter" transform is run by publish_doctree(). When filtering based on the output format, it should be run by publish_from_doctree() instead because only then the writer is known. So we need to either remove or fix the framework. </li> <li>Think about large documents made up of multiple subdocument files. Issues: continuity (<a class="reference internal" href="#persistent-sequences">persistent sequences</a> above), cross-references (<a class="reference internal" href="#name-to-id-mapping-file">name-to-id mapping file</a> above and <a class="reference internal" href="#targets-in-other-documents">targets in other documents</a> below), splitting (<a class="reference internal" href="#document-splitting">document splitting</a> below). When writing a book, the author probably wants to split it up into files, perhaps one per chapter (but perhaps even more detailed). However, we'd like to be able to have references from one chapter to another, and have continuous numbering (pages and chapters, as applicable). Of course, none of this is implemented yet. There has been some thought put into some aspects; see <a class="reference external" href="../ref/rst/directives.html#including-an-external-document-fragment">the "include" directive</a> and the <a class="reference internal" href="#reference-merging">Reference Merging</a> transform below. When I was working with SGML in Japan, we had a system where there was a top-level coordinating file, book.sgml, which contained the top-level structure of a book: the <book> element, containing the book <title> and empty component elements (<preface>, <chapter>, <appendix>, etc.), each with filename attributes pointing to the actual source for the component. Something like this: <pre class="literal-block"><book id="bk01"> <title>Title of the Book</title> <preface inrefid="pr01"></preface> <chapter inrefid="ch01"></chapter> <chapter inrefid="ch02"></chapter> <chapter inrefid="ch03"></chapter> <appendix inrefid="ap01"></appendix> </book></pre> (The "inrefid" attribute stood for "insertion reference ID".) The processing system would process each component separately, but it would recognize and use the book file to coordinate chapter and page numbering, and keep a persistent ID to (title, page number) mapping database for cross-references. Docutils could use a similar system for large-scale, multipart documents. Aahz's idea: <blockquote> First the ToC: <pre class="literal-block">.. ToC-list:: Introduction.rst Objects.rst Data.rst Control.rst</pre> Then a sample use: <pre class="literal-block">.. include:: ToC.rst As I said earlier in chapter :chapter:`Objects.rst`, the reference count gets increased every time a binding is made.</pre> Which produces: <pre class="literal-block">As I said earlier in chapter 2, the reference count gets increased every time a binding is made.</pre> The ToC in this form doesn't even need to be references to actual reST documents; I'm simply doing it that way for a minimum of future-proofing, in case I do want to add the ability to pick up references within external chapters. </blockquote> Perhaps, instead of ToC (which would overload the "contents" directive concept already in use), we could use "manifest". A "manifest" directive might associate local reference names with files: <pre class="literal-block">.. manifest:: intro: Introduction.rst objects: Objects.rst data: Data.rst control: Control.rst</pre> Then the sample becomes: <pre class="literal-block">.. include:: manifest.rst As I said earlier in chapter :chapter:`objects`, the reference count gets increased every time a binding is made.</pre> </li> <li>Add support for multiple output files and generic data handling: It should be possible for a component to emit or reference data to be either included or referenced in the output document. Examples of such data are stylesheets or images. For this, we need a "data" object which stores the data either inline or by referring to a file. The Docutils framework is responsible for either: <ul class="simple"> <li>storing the data in the appropriate location (e.g. in the directory of the output file, or in a user-specified directory) and providing the paths of the stored files to the writer, or</li> <li>providing the data itself to the writer so that it can be embedded in the output document.</li> </ul> This approach decouples data handling from the data source (which can either be embedded or referenced) and the destination (which can either be embedded or referenced as well). See <<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3631">http://article.gmane.org/gmane.text.docutils.devel/3631</a>>. </li> <li>Add testing for Docutils' front end tools?</li> <li>Publisher: "Ordinary setup" shouldn't require specific ordering; at the very least, there ought to be error checking higher up in the call chain. [Aahz] Publisher.get_settings requires that all components be set up before it's called. Perhaps the I/O objects shouldn't be set, but I/O classes. Then options are set up (.set_options), and Publisher.set_io (or equivalent code) is called with source & destination paths, creating the I/O objects. Perhaps I/O objects shouldn't be instantiated until required. For split output, the Writer may be called multiple times, once for each doctree, and each doctree should have a separate Output object (with a different path). Is the "Builder" pattern applicable here? </li> <li>Perhaps I/O objects should become full-fledged components (i.e. subclasses of docutils.Component, as are Readers, Parsers, and Writers now), and thus have associated option/setting specs and transforms.</li> <li>Multiple file I/O suggestion from Michael Hudson: use a file-like object or something you can iterate over to get file-like objects.</li> <li>Add an "--input-language" option & setting? Specify a different language module for input (bibliographic fields, directives) than for output. The "--language" option would set both input & output languages.</li> <li>Auto-generate reference tables for language-dependent features? Could be generated from the source modules. A special command-line option could be added to Docutils front ends to do this. (Idea from Engelbert Gruber.)</li> <li>Enable feedback of some kind from internal decisions, such as reporting the successful input encoding. Modify runtime settings? System message? Simple stderr output?</li> <li>Rationalize Writer settings (HTML/LaTeX/PEP) -- share settings.</li> <li>Add an "--include file" command-line option (config setting too?), equivalent to ".. include:: file" as the first line of the doc text? Especially useful for character entity sets, text transform specs, boilerplate, etc.</li> <li>Support "include" as embedded inline-compatible directive in substitution definitions, e.g. <pre class="literal-block">.. |version| include:: version.rst This document describes version |version| of ...</pre> (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel) </li> <li>Add an :optional: <replacement text> option to the "include" directive? This would not throw an error for a missing file, instead a warning is given and <replacement text> is used instead. It would be the responsibility of the author to ensure the missing file does not lead to problems later in the document. Use cases: <ul> <li>Standard rST syntax to replace Sphinx's "literalinclude": <pre class="literal-block">.. include:: blah.cpp :literal: :optional: file ``blah.cpp`` not found</pre> </li> <li>Variable content taken from a file, e.g. version.rst: <pre class="literal-block">.. |version| replace:: 3.1</pre> optionally used as: <pre class="literal-block">.. include:: version.rst :optional: .. |version| replace:: unknown This document describes version |version| of ...</pre> (cf. Grzegorz Adam Hankiewicz's post from 2014-10-01 in docutils-devel) </li> </ul> </li> <li>Parameterize the Reporter object or class? See the <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1112">2004-02-18 "rest checking and source path"</a> thread. </li> <li>Add a "disable_transforms" setting? Would allow for easy syntax checking. Where ("null" writer, generic, parser(s))? Cf. the <a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/1112">2004-02-18 "rest checking and source path"</a> thread.</li> <li>Add a generic meta-stylesheet mechanism? An external file could associate style names ("class" attributes) with specific elements. Could be generalized to arbitrary output attributes; useful for HTML & XMLs. Aahz implemented something like this in sandbox/aahz/Effective/EffMap.py.</li> <li>William Dode suggested that table cells be assigned "class" attributes by columns, so that stylesheets can affect text alignment. Unfortunately, there doesn't seem to be a way (in HTML at least) to leverage the "colspec" elements (HTML "col" tags) by adding classes to them. The resulting HTML is very verbose: <pre class="literal-block"><td class="col1">111</td> <td class="col2">222</td> ...</pre> At the very least, it should be an option. People who don't use it shouldn't be penalized by increases in their HTML file sizes. Table rows could also be assigned classes (like odd/even). That would be easier to implement. How should it be implemented? <ul class="simple"> <li>There could be writer options (column classes & row classes) with standard values.</li> <li>The table directive could grow some options. Something like ":cell-classes: col1 col2 col3" (either must match the number of columns, or repeat to fill?) and ":row-classes: odd even" (repeat to fill; body rows only, or header rows too?).</li> </ul> Probably per-table directive options are best. The "class" values could be used by any writer, and applying such classes to all tables in a document with writer options is too broad. See also the <a class="reference external" href="https://pythonhosted.org/cloud_sptheme/lib/cloud_sptheme.ext.table_styling.html">table_styling Sphinx extension</a> which defines <dl class="field-list simple"> <dt>widths:</dt> <dd>also in Docutils core (but different implementation) </dd> <dt>column-alignment:</dt> <dd>Sets per-column text alignment </dd> <dt>column-wrapping:</dt> <dd>Sets per-column text wrapping </dd> <dt>column-dividers:</dt> <dd>Add dividers between columns </dd> <dt>column-classes:</dt> <dd>Add per-column css classes. </dd> <dt>header-columns:</dt> <dd>Specify number of “stub” columns </dd> </dl> </li> <li>Add file-specific settings support to config files, like: <pre class="literal-block">[file index.rst] compact-lists: no</pre> Is this even possible? Should the criterion be the name of the input file or the output file? Alternative (more explicit) syntax: <pre class="literal-block">[source_file index.rst] ... [dest_file index.html] ...</pre> Or rather allow settings configuration from the rst source file (see <a class="reference internal" href="#misc-settings">misc.settings</a> directive)? </li> <li>The "validator" support added to OptionParser is very similar to "<a class="reference external" href="http://code.enthought.com/traits/">traits</a>" in <a class="reference external" href="http://www.scipy.org/">SciPy</a>. Perhaps something could be done with them? (Had I known about traits when I was implementing docutils.frontend, I may have used them instead of rolling my own.) </li> <li>tools/buildhtml.py: Extend the --prune option ("prune" config setting) to accept file names (generic path) in addition to directories (e.g. --prune=docs/user/rst/cheatsheet.rst, which should not be converted to HTML).</li> <li>Add support for plugins.</li> <li>Config directories: Currently, ~/.docutils, ./docutils.conf/, & /etc/docutils.conf are read as <a class="reference external" href="../user/config.html">configuration</a> files. Proposal: allow ~/.docutils to be a a configuration directory, along with /etc/docutils/ and ./docutils.conf/. Within these directories, check for config.rst files. We can also have subdirectories here, for plugins, S5 themes, components (readers/writers/parsers) etc. Docutils will continue to support configuration files for backwards compatibility. </li> <li>Add support for document decorations other than headers & footers? For example, top/bottom/side navigation bars for web pages. Generic decorations? Seems like a bad idea as long as it isn't independent from the output format (for example, navigation bars are only useful for web pages). </li> <li>docutils_update: Check for a Makefile in a directory, and run make if found? This would allow for variant processing on specific source files, such as running rst2s5 instead of rst2html.</li> <li>Add a "disable table of contents" setting? The S5 writer could set it as a default. Rationale: <blockquote> The contents (table of contents) directive must not be used [in S5/HTML documents]. It changes the CSS class of headings and they won't show up correctly in the screen presentation. —<a class="reference external" href="../user/slide-shows.html">Easy Slide Shows With reStructuredText & S5</a> </blockquote> Analogue to the sectnum_xform setting, it could be used by the latex writer to switch to a LaTeX generated ToC (currently, the latex writer calls it "use_latex_toc"). </li> </ul> </section> <section id="object-numbering-and-object-references"> <h3><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">object numbering and object references</a><a class="self-link" title="link to this section" href="#object-numbering-and-object-references"></a></h3> For equations, tables & figures. These would be the equivalent of DocBook's "formal" elements. In LaTeX, automatic counters are implemented for sections, equations and floats (figures, tables) (configurable via stylesheets or in the latex-preamble). Objects can be given <a class="reference external" href="../ref/rst/restructuredtext.html#reference-names">reference names</a> with the \label{<refname} command, \ref{<refname>} inserts the corresponding number. No such mechanism exists in HTML. <ul> <li>We need persistent sequences, similar to chapter and footnote numbers. See <a class="reference external" href="http://xml.openoffice.org/">OpenOffice.org XML</a> "fields". <ul class="simple"> <li>Should the sequences be automatic or manual (user-specifyable)?</li> </ul> </li> <li>It is already possible to give <a class="reference external" href="../ref/rst/restructuredtext.html#reference-names">reference names</a> to objects via internal hyperlink targets or the "name" directive option: <pre class="literal-block">.. _figure name: .. figure:: image.png</pre> or <pre class="literal-block">.. figure:: image.png :name: figure name</pre> Improve the mapping of "phrase references" to IDs/labels with Literal transcription (i.e. ü -> ue, ß -> ss, å -> aa) instead of just stripping the accents and other non-ASCII chars. See also the feature request <a class="reference external" href="https://sourceforge.net/p/docutils/feature-requests/66/">allow more characters when transforming "names" to "ids"</a>. A "table" directive has been implemented, supporting table titles. Perhaps the name could derive from the title/caption? </li> <li>We need syntax for object references. Cf. <a class="reference external" href="http://xml.openoffice.org/">OpenOffice.org XML</a> "reference fields": <ul> <li>Parameterized substitutions are too complicated (cf. <cite>or not to do</cite>: <a class="reference external" href="rst/alternatives.html#object-references">object references</a>)</li> <li>An interpreted text approach is simpler and better: <pre class="literal-block">See Figure :ref:`figure name` and Equation :ref:`eq:identity`.</pre> </li> <li>"equation", "figure", and "page" roles could generate appropriate boilerplate text: <pre class="literal-block">See :figure:`figure name` on :page:`figure name`.</pre> See <a class="reference internal" href="#interpreted-text">Interpreted Text</a> below. Reference boilerplate could be specified in the document (defaulting to nothing): <pre class="literal-block">.. fignum:: :prefix-ref: "Figure " :prefix-caption: "Fig. " :suffix-caption: :</pre> The position of the role (prefix or suffix) could also be utilized </li> </ul> </li> </ul> </section> </section> <section id="documentation"> <h2><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">Documentation</a><a class="self-link" title="link to this section" href="#documentation"></a></h2> <section id="user-docs"> <h3><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">User Docs</a><a class="self-link" title="link to this section" href="#user-docs"></a></h3> <ul class="simple"> <li>Add a FAQ entry about using Docutils (with reStructuredText) on a server and that it's terribly slow. See the first paragraphs in <<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1584">http://article.gmane.org/gmane.text.docutils.user/1584</a>>.</li> <li>Add document about what Docutils has previously been used for (web/use-cases.rst?).</li> <li>Improve index in docs/user/config.rst.</li> </ul> </section> <section id="developer-docs"> <h3><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">Developer Docs</a><a class="self-link" title="link to this section" href="#developer-docs"></a></h3> <ul class="simple"> <li>Improve the internal module documentation (docstrings in the code). Specific deficiencies listed below. <ul> <li>docutils.parsers.rst.states.State.build_table: data structure required (including StringList).</li> <li>docutils.parsers.rst.states: more complete documentation of parser internals.</li> </ul> </li> <li>docs/ref/doctree.rst: DTD element structural relationships, semantics, and attributes. In progress; element descriptions to be completed.</li> <li>Document the pending elements, how they're generated and what they do.</li> <li>Document the <a class="reference external" href="../api/transforms.html">transforms</a> (perhaps in docstrings?): how they're used, what they do, dependencies & order considerations.</li> <li>Document the HTML classes used by html4css1.py.</li> <li>Write an overview of the Docutils architecture, as an introduction for developers. What connects to what, why, and how. Either update PEP 258 (see <a class="reference internal" href="#peps">PEPs</a> below) or as a separate doc.</li> <li>Give information about unit tests. Maybe as a howto?</li> <li>Document the docutils.nodes APIs.</li> <li>Complete the docs/api/publisher.rst docs.</li> </ul> </section> <section id="how-tos"> <h3><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">How-Tos</a><a class="self-link" title="link to this section" href="#how-tos"></a></h3> <ul class="simple"> <li>Creating Docutils Writers</li> <li>Creating Docutils Readers</li> <li>Creating Docutils <a class="reference external" href="../api/transforms.html">Transforms</a></li> <li>Creating Docutils Parsers</li> <li>Using Docutils as a Library</li> </ul> </section> <section id="peps"> <h3><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">PEPs</a><a class="self-link" title="link to this section" href="#peps"></a></h3> <ul> <li>Complete PEP 258 Docutils Design Specification. <ul> <li>Fill in the blanks in API details.</li> <li>Specify the nodes.py internal data structure implementation? <blockquote> [Tibs:] Eventually we need to have direct documentation in there on how it all hangs together - the DTD is not enough (indeed, is it still meant to be correct? [Yes, it is. --DG]). </blockquote> </li> </ul> </li> <li>Rework PEP 257, separating style from spec from tools, wrt Docutils? See Doc-SIG from 2001-06-19/20.</li> </ul> </section> </section> <section id="python-source-reader"> <h2><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">Python Source Reader</a><a class="self-link" title="link to this section" href="#python-source-reader"></a></h2> General: <ul class="simple"> <li>Analyze Tony Ibbs' PySource code.</li> <li>Analyze Doug Hellmann's HappyDoc project.</li> <li>Investigate how POD handles literate programming.</li> <li>Take the best ideas and integrate them into Docutils.</li> </ul> Miscellaneous ideas: <ul> <li>Ask Python-dev for opinions (GvR for a pronouncement) on special variables (__author__, __version__, etc.): convenience vs. namespace pollution. Ask opinions on whether or not Docutils should recognize & use them.</li> <li>If we can detect that a comment block begins with ##, a la JavaDoc, it might be useful to indicate interspersed section headers & explanatory text in a module. For example: <pre class="literal-block">"""Module docstring.""" ## # Constants # ========= a = 1 b = 2 ## # Exception Classes # ================= class MyException(Exception): pass # etc.</pre> </li> <li>Should standalone strings also become (module/class) docstrings? Under what conditions? We want to prevent arbitrary strings from becoming docstrings of prior attribute assignments etc. Assume that there must be no blank lines between attributes and attribute docstrings? (Use lineno of NEWLINE token.) Triple-quotes are sometimes used for multi-line comments (such as commenting out blocks of code). How to reconcile? </li> <li>HappyDoc's idea of using comment blocks when there's no docstring may be useful to get around the conflict between <a class="reference external" href="../peps/pep-0258.html#additional-docstrings">additional docstrings</a> and from __future__ import for module docstrings. A module could begin like this: <pre class="literal-block">#!/usr/bin/env python # :Author: Me # :Copyright: whatever """This is the public module docstring (``__doc__``).""" # More docs, in comments. # All comments at the beginning of a module could be # accumulated as docstrings. # We can't have another docstring here, because of the # ``__future__`` statement. from __future__ import division</pre> Using the JavaDoc convention of a doc-comment block beginning with ## is useful though. It allows doc-comments and implementation comments. </li> <li>HappyDoc uses an initial comment block to set "parser configuration values". Do the same thing for Docutils, to set runtime settings on a per-module basis? I.e.: <pre class="literal-block"># Docutils:setting=value</pre> Could be used to turn on/off function parameter comment recognition & other marginal features. Could be used as a general mechanism to augment config files and command-line options (but which takes precedence?). </li> <li>Multi-file output should be divisible at arbitrary level.</li> <li>Support all forms of import statements: <ul class="simple"> <li>import module: listed as "module"</li> <li>import module as alias: "alias (module)"</li> <li>from module import identifier: "identifier (from module)"</li> <li>from module import identifier as alias: "alias (identifier from module)"</li> <li>from module import *: "all identifiers (*) from module"</li> </ul> </li> <li>Have links to colorized Python source files from API docs? And vice-versa: backlinks from the colorized source files to the API docs!</li> <li>In summaries, use the first sentence of a docstring if the first line is not followed by a blank line.</li> </ul> </section> <section id="restructuredtext-parser"> <h2><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">reStructuredText Parser</a><a class="self-link" title="link to this section" href="#restructuredtext-parser"></a></h2> Also see the <a class="reference external" href="rst/alternatives.html#or-not-to-do">... Or Not To Do?</a> list. <section id="bugs-1"> <h3><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">Bugs</a><a class="self-link" title="link to this section" href="#bugs-1"></a></h3> <ul class="simple"> <li>A container directive with :class: option gets the spurious class value "class".</li> </ul> </section> <section id="misc"> <h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink">Misc</a><a class="self-link" title="link to this section" href="#misc"></a></h3> <ul> <li>Another list problem: <pre class="literal-block">* foo * bar * baz</pre> This ends up as a definition list. This is more of a usability issue. </li> <li>This case is probably meant to be a nested list, but it ends up as a list inside a block-quote without an error message: <pre class="literal-block">- foo - bar</pre> It should probably just be an error. The problem with this is that you don't notice easily in HTML that it's not a nested list but a block-quote -- there's not much of a visual difference. </li> <li>Treat enumerated lists that are not arabic and consist of only one item in a single line as ordinary paragraphs. See <<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2635">http://article.gmane.org/gmane.text.docutils.user/2635</a>>.</li> <li>The citation syntax could use some improvements. See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499">http://thread.gmane.org/gmane.text.docutils.user/2499</a>> (and the sub-thread at <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028">http://thread.gmane.org/gmane.text.docutils.user/2499/focus=3028</a>>, and the follow-ups at <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3087">http://thread.gmane.org/gmane.text.docutils.user/3087</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3110">http://thread.gmane.org/gmane.text.docutils.user/3110</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3114">http://thread.gmane.org/gmane.text.docutils.user/3114</a>>), <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2443">http://thread.gmane.org/gmane.text.docutils.user/2443</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2715">http://thread.gmane.org/gmane.text.docutils.user/2715</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3027">http://thread.gmane.org/gmane.text.docutils.user/3027</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3120">http://thread.gmane.org/gmane.text.docutils.user/3120</a>>, <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3253">http://thread.gmane.org/gmane.text.docutils.user/3253</a>>.</li> <li>The current list-recognition logic has too many false positives, as in <pre class="literal-block">* Aorta * V. cava superior * V. cava inferior</pre> Here V. is recognized as an enumerator, which leads to confusion. We need to find a solution that resolves such problems without complicating the spec to much. See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2524">http://thread.gmane.org/gmane.text.docutils.user/2524</a>>. </li> <li>Add indirect links via citation references & footnote references. Example: <pre class="literal-block">`Goodger (2005)`_ is helpful. .. _Goodger (2005): [goodger2005]_ .. [goodger2005] citation text</pre> See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/2499">http://thread.gmane.org/gmane.text.docutils.user/2499</a>>. </li> <li>Complain about bad URI characters (<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2046">http://article.gmane.org/gmane.text.docutils.user/2046</a>) and disallow internal whitespace (<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/2214">http://article.gmane.org/gmane.text.docutils.user/2214</a>).</li> <li>Create info-level system messages for unnecessarily backslash-escaped characters (as in "\something", rendered as "something") to allow checking for errors which silently slipped through.</li> <li>Add (functional) tests for untested roles.</li> <li>Add test for ":figwidth: image" option of "figure" directive. (Test code needs to check if PIL is available on the system.)</li> <li>Add support for CJK double-width whitespace (indentation) & punctuation characters (markup; e.g. double-width "*", "-", "+")?</li> <li>Add motivation sections for constructs in spec.</li> <li>Support generic hyperlink references to targets in other documents? Not in an HTML-centric way, though (it's trivial to say https://www.example.org/doc#name, and useless in non-HTML contexts). XLink/XPointer? .. baseref::? See Doc-SIG 2001-08-10.</li> <li>Implement the header row separator modification to table.el. (Wrote to Takaaki Ota & the table.el mailing list on 2001-08-12, suggesting support for "=====" header rows. On 2001-08-17 he replied, saying he'd put it on his to-do list, but "don't hold your breath".)</li> <li>Fix the parser's indentation handling to conform with the stricter definition in the spec. (Explicit markup blocks should be strict or forgiving?)  </li> <li>Make the parser modular. Allow syntax constructs to be added or disabled at run-time. Subclassing is probably not enough because it makes it difficult to apply multiple extensions.</li> <li>Generalize the "doctest block" construct (which is overly Python-centric) to other interactive sessions? "Doctest block" could be renamed to "I/O block" or "interactive block", and each of these could also be recognized as such by the parser: <ul> <li>Shell sessions: <pre class="literal-block">$ cat example1.rst A block beginning with a "$ " prompt is interpreted as a shell session interactive block. As with Doctest blocks, the interactive block ends with the first blank line, and wouldn't have to be indented.</pre> </li> <li>Root shell sessions: <pre class="literal-block"># cat example2.rst A block beginning with a "# " prompt is interpreted as a root shell session (the user is or has to be logged in as root) interactive block. Again, the block ends with a blank line.</pre> </li> </ul> Other standard (and unambiguous) interactive session prompts could easily be added (such as "> " for WinDOS). Tony Ibbs spoke out against this idea (2002-06-14 Doc-SIG thread "docutils feedback"). </li> <li>Add support for pragma (syntax-altering) directives. Some pragma directives could be local-scope unless explicitly specified as global/pragma using ":global:" options. </li> <li>Support whitespace in angle-bracketed standalone URLs according to Appendix E ("Recommendations for Delimiting URI in Context") of <a class="reference external" href="https://tools.ietf.org/html/rfc2396.html">RFC 2396</a>.</li> <li>Use the vertical spacing of the source text to determine the corresponding vertical spacing of the output?</li> <li>[From Mark Nodine] For cells in simple tables that comprise a single line, the justification can be inferred according to the following rules: <ol class="arabic simple"> <li>If the text begins at the leftmost column of the cell, then left justification, ELSE</li> <li>If the text begins at the rightmost column of the cell, then right justification, ELSE</li> <li>Center justification.</li> </ol> The onus is on the author to make the text unambiguous by adding blank columns as necessary. There should be a parser setting to turn off justification-recognition (normally on would be fine). Decimal justification? All this shouldn't be done automatically. Only when it's requested by the user, e.g. with something like this: <pre class="literal-block">.. table:: :auto-indent: (Table goes here.)</pre> Otherwise it will break existing documents. </li> <li>Generate a warning or info message for paragraphs which should have been lists, like this one: <pre class="literal-block">1. line one 3. line two</pre> </li> <li>Generalize the "target-notes" directive into a command-line option somehow? See docutils-develop 2003-02-13.</li> <li>Allow a "::"-only paragraph (first line, actually) to introduce a literal block without a blank line? (Idea from Paul Moore.) <pre class="literal-block">:: This is a literal block</pre> Is indentation enough to make the separation between a paragraph which contains just a :: and the literal text unambiguous? (There's one problem with this concession: If one wants a definition list item which defines the term "::", we'd have to escape it.) It would only be reasonable to apply it to "::"-only paragraphs though. I think the blank line is visually necessary if there's text before the "::": <pre class="literal-block">The text in this paragraph needs separation from the literal block following:: This doesn't look right.</pre> </li> <li>Add new syntax for nested inline markup? Or extend the parser to parse nested inline markup somehow? See the <a class="reference external" href="rst/alternatives.html#nested-inline-markup">collected notes</a>.</li> <li>Drop the backticks from embedded URIs with omitted reference text? Should the angle brackets be kept in the output or not? <pre class="literal-block"><file_name>_</pre> Probably not worth the trouble. </li> <li>How about a syntax for alternative hyperlink behavior, such as "open in a new window" (as in HTML's <a target="_blank">)? The MoinMoin wiki uses a caret ("^") at the beginning of the URL ("^" is not a legal URI character). That could work for both inline and explicit targets: <pre class="literal-block">The `reference docs <^url>`__ may be handy. .. _name: ^url</pre> This may be too specific to HTML. It hasn't been requested very often either. </li> <li>Add an option to add URI schemes at runtime.</li> <li>Segmented lists: <pre class="literal-block">: segment : segment : segment : segment : segment : very long segment : segment : segment : segment</pre> The initial colon (":") can be thought of as a type of bullet We could even have segment titles: <pre class="literal-block">:: title : title : title : segment : segment : segment : segment : segment : segment</pre> This would correspond well to DocBook's SegmentedList. Output could be tabular or "name: value" pairs, as described in DocBook's docs. </li> <li>Enable grid tables inside XML comments, where "--" ends comments. Implementation possibilities: <ol class="arabic simple"> <li>Make the table syntax characters into "table" directive options. This is the most flexible but most difficult, and we probably don't need that much flexibility.</li> <li>Substitute "~" for "-" with a specialized directive option (e.g. ":tildes:").</li> <li>Make the standard table syntax recognize "~" as well as "-", even without a directive option. Individual tables would have to be internally consistent.</li> <li>Allow Unicode box characters for table markup (<a class="reference external" href="https://sourceforge.net/p/docutils/feature-requests/6">feature request [6]</a>)</li> </ol> Directive options are preferable to configuration settings, because tables are document-specific. A pragma directive would be another approach, to set the syntax once for a whole document. Unicode box character markup would kill two birds with one stone. In the meantime, the <a class="reference external" href="../ref/rst/directives.html#list-table">list-table</a> directive is a good replacement for grid tables inside XML comments. </li> <li>Generalize docinfo contents (bibliographic fields): remove specific fields, and have only a single generic "field"?</li> <li>Line numbers and "source" in system messages: <ul> <li>Add "source" and "line" keyword arguments to all Reporter calls? This would require passing source/line arguments along all intermediate functions (where currently only <cite>line</cite> is used). Or rather specify "line" only if actually needed? Currently, <cite>document.reporter</cite> uses a state machine instance to determine the "source" and "line" info from <cite>statemachine.input_lines</cite> if not given explicitly. Except for special cases, the "line" argument is not needed because, <cite>document.statemachine</cite> keeps record of the current line number. </li> <li>For system messages generated after the parsing is completed (i.e. by transforms or the writer) "line" info must be present in the doctree elements. Elements' .line assignments should be checked. (Assign to .source too? Add a set_info method? To what?) The "source" (and line number in the source) can either be added explicitly to the elements or determined from the “raw” line number by <cite>document.statemachine.get_source_and_line</cite>. </li> <li>Some line numbers in elements are not being set properly (explicitly), just implicitly/automatically. See rev. 1.74 of docutils/parsers/rst/states.py for an example of how to set.</li> <li>The line numbers of definition list items are wrong: <pre class="literal-block">$ rst2pseudoxml --expose-internal-attribute line 1 2 3 5 6 7 <document source="<stdin>"> <definition_list> <definition_list_item internal:line="3"> <term> 1 <definition> <paragraph internal:line="2"> 2 3 <definition_list_item internal:line="6"> <term> 5 <definition> <paragraph internal:line="6"> 6 7</pre> </li> </ul> </li> <li>Quite a few nodes are getting a "None" source attribute as well. In particular, see the bodies of definition lists. </li> </ul> </section> <section id="adaptable-file-extensions"> <h3><a class="toc-backref" href="#toc-entry-15" role="doc-backlink">Adaptable file extensions</a><a class="self-link" title="link to this section" href="#adaptable-file-extensions"></a></h3> <section id="questions"> <h4><a class="toc-backref" href="#toc-entry-16" role="doc-backlink">Questions</a><a class="self-link" title="link to this section" href="#questions"></a></h4> Should Docutils support adaptable file extensions in hyperlinks? <blockquote> In the rST source, sister documents are ".rst" files. If we're generating HTML, then ".html" is appropriate; if PDF, then ".pdf"; etc. </blockquote> Handle documents only, or objects (images, etc.) also? <blockquote> Different output formats support different sets of image formats (HTML supports ".svg" but not ".pdf", pdfLaTeX supports ".pdf" but not ".svg", LaTeX supports only ".eps"). This is less urgent 2020 than 2004, as <cite>pdflatex</cite> and <cite>lualatex</cite> are now standard and support most image formats. Also, a wrapper like <a class="reference external" href="https://pypi.org/project/rubber/">rubber</a> that provides on-the-fly image conversion depends on the "wrong" extension in the LaTeX source. </blockquote> At what point should the extensions be substituted? <blockquote> <dl> <dt><a class="reference external" href="../api/transforms.html">Transforms</a>:</dt> <dd>Fits well in the <a class="reference external" href="../peps/pep-0258.html#id24">Reader → Transformer → Writer</a> processing framework. <ul class="simple"> <li>Filename/URL extension replacement can be done walking over the Document tree transforming the document tree from a valid state to another valid state.</li> <li>Writer-specific configuration is still possible in the respective sections of the <a class="reference external" href="../user/config.html">configuration</a> file.</li> </ul> </dd> <dt>Pre- or post-processing:</dt> <dd>Can be implemented independent of Docutils -- keeps Docutils simple. <blockquote> ... those who need more sophisticated filename extension tweaking can simply use regular expressions, which isn't too difficult due to the determinability of the writers. So there is no need to add a complex filename-extension-handling feature to Docutils. —<a class="reference external" href="https://sourceforge.net/p/docutils/mailman/message/6918089/">Lea Wiemann in docutils-users 2004-06-04</a> </blockquote> </dd> </dl> </blockquote> </section> <section id="proposals"> <h4><a class="toc-backref" href="#toc-entry-17" role="doc-backlink">Proposals</a><a class="self-link" title="link to this section" href="#proposals"></a></h4> How about using ".*" to indicate "choose the most appropriate filename extension"? For example: <pre class="literal-block">.. _Another Document: another.*</pre> <ul> <li>My point about using .* is that any other mechanism inside reST leads to too many ambiguities in reading reST documents; at least with .* it's clear that some kind of substitution is going on. --- Aahz </li> <li>What is to be done for output formats that don't have hyperlinks? For example, LaTeX targeted at print. Hyperlinks may be "called out", as footnotes with explicit URLs. (Don't convert the links.) But then there's also LaTeX targeted at PDFs, which can have links. Perhaps a runtime setting for "*" could explicitly provide the extension, defaulting to the output file's extension. </li> <li>If this handles images also, how to differentiate between document and image links? Element context (within "image")? Which image extension to use for which document format? For HTML output, there is no reliable way of determining which extension to use (svg, png, jpg, jpeg, gif, ...). Should the system check for existing files? No, not practical (the image files may be not available when the document is processed to HTML). Mailing list threads: <a class="reference external" href="https://sourceforge.net/p/docutils/mailman/docutils-users/thread/40BAA4B7.5020801%40python.org/#msg6918066">Images in both HTML and LaTeX</a> (especially <a class="reference external" href="https://sourceforge.net/p/docutils/mailman/message/6918089/">this summary of Lea's objections</a>). </li> </ul> Chris Liechti suggests a new :link: role in <a class="reference external" href="https://sourceforge.net/p/docutils/mailman/message/6919484/">more-universal links?</a>: <pre class="literal-block"> .. role:: link(rewrite) :transform: .rst|.html and then to use it:: for more information see :link:`README.rst` it would be useful if it supported an additional option ``:format: html`` so that separate rules for each format can be defined. (like the "raw" role)</pre> Idea from Jim Fulton: an external lookup table of targets: <blockquote> I would like to specify the extension (e.g. .rst) [in the source, rather than filename.*], but tell the converter to change references to the files anticipating that the files will be converted too. For example: <pre class="literal-block">.. _Another Document: another.rst rst2html --convert-links "another.rst bar.rst" foo.rst</pre> That is, name the files for which extensions should be converted. Note that I want to refer to original files in the original text (another.rst rather than another.*) because I want the unconverted text to stand on its own. Note that in most cases, people will be able to use globs: <pre class="literal-block">rst2html --convert-link-extensions-for "`echo *.rst`" foo.rst</pre> It might be nice to be able to use multiple arguments, as in: <pre class="literal-block">rst2html --convert-link-extensions-for *.rst -- foo.rst</pre> > Handle documents only, or objects (images, etc.) also? No, documents only, but there really is no need for guesswork. Just get the file names as command-line arguments. EIBTI [explicit is better than implicit]. </blockquote> In <a class="reference external" href="https://sourceforge.net/p/docutils/patches/169/">Patch #169</a> <cite>Hyperlink extension rewriting</cite>, John L. Clark suggests command line options that map to-be-changed file extensions, e.g.: <pre class="literal-block">rst2html --map-extension rst html --map-extension jpg png \ input-filename.rst</pre> <blockquote> Specifying the mapping as regular expressions would make this approach more generic and easier to implement (use re.replace and refer to the "re" module's documentation instead of coding and documenting a home-grown extraction and mapping procedure). </blockquote> </section> </section> <section id="math-markup"> <h3><a class="toc-backref" href="#toc-entry-18" role="doc-backlink">Math Markup</a><a class="self-link" title="link to this section" href="#math-markup"></a></h3> Since Docutils 0.8, a "math" role and directive using LaTeX math syntax as input format is part of reStructuredText. Open issues: <ul class="simple"> <li>Use a "Transform" for math format conversions as extensively discussed in the "math directive issues" thread in May 2008 (<a class="reference external" href="http://osdir.com/ml/text.docutils.devel/2008-05/threads.html">http://osdir.com/ml/text.docutils.devel/2008-05/threads.html</a>)?</li> <li>Generic <a class="reference external" href="../user/config.html#math-output">math-output setting</a> (currently specific to HTML). (List of math-output preferences?)</li> <li>Try to be compatible with <a class="reference external" href="http://sphinx.pocoo.org/ext/math.html">Math support in Sphinx</a>? <ul> <li>The :label: option selects a label for the equation, by which it can be cross-referenced, and causes an equation number to be issued. In Docutils, the option :name: sets the label. Equation numbering is not implemented yet.</li> <li>Option :nowrap: prevents wrapping of the given math in a math environment (you have to specify the math environment in the content).</li> </ul> </li> <li>Equation numbering and references. (see the section on <cite>object numbering and object references</cite> for equations, formal tables, and images.)</li> </ul> <section id="alternative-input-formats"> <h4><a class="toc-backref" href="#toc-entry-19" role="doc-backlink">alternative input formats</a><a class="self-link" title="link to this section" href="#alternative-input-formats"></a></h4> Use a directive option to specify an alternative input format, e.g. (but not limited to): <dl> <dt><a class="reference external" href="https://www.w3.org/TR/MathML2/">MathML</a></dt> <dd>Not for hand-written code but maybe useful when pasted in (or included from a file) For an overview of MathML implementations and tests, see, e.g., the <a class="reference external" href="http://www.mathweb.org/wiki/MathML">mathweb wiki</a> or the <a class="reference external" href="http://wiki.contextgarden.net/MathML">ConTeXT MathML page</a>. A MathML to LaTeX XSLT sheet: <a class="reference external" href="https://github.com/davidcarlisle/web-xslt/tree/master/pmml2tex">https://github.com/davidcarlisle/web-xslt/tree/master/pmml2tex</a> </dd> <dt><a class="reference external" href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMath</a></dt> <dd>Simple, ASCII based math input language (see also <a class="reference external" href="http://www.wjagray.co.uk/maths/ASCIIMathTutorial.html">ASCIIMath tutorial</a>). <ul> <li>The Python module <a class="reference external" href="http://pypi.python.org/pypi/asciimathml/">ASCIIMathML</a> translates a string with ASCIIMath into a MathML tree. Used, e.g., by <a class="reference external" href="http://fletcherpenney.net/multimarkdown/">MultiMarkdown</a>. A more comprehensive implementation is <a class="reference external" href="https://github.com/paulhtremblay/asciimathml">ASCIIMathPython</a> by Paul Trembley (also used in his sandbox projects). </li> <li>For conversion to LaTeX, there is <ul class="simple"> <li>a JavaScript script at <a class="reference external" href="http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js">http://dlippman.imathas.com/asciimathtex/ASCIIMath2TeX.js</a></li> <li>The javascript <cite>asciimath-to-latex</cite> AsciiMath to LaTex converter at the node package manager <a class="reference external" href="https://www.npmjs.com/package/asciimath-to-latex">https://www.npmjs.com/package/asciimath-to-latex</a> and at GitHub <a class="reference external" href="https://github.com/tylerlong/asciimath-to-latex">https://github.com/tylerlong/asciimath-to-latex</a></li> <li>a javascript and a PHP converter script at GitHub <a class="reference external" href="https://github.com/asciimath/asciimathml/tree/master/asciimath-based">https://github.com/asciimath/asciimathml/tree/master/asciimath-based</a></li> </ul> </li> </ul> </dd> <dt><a class="reference external" href="https://www.unicode.org/notes/tn28/">Unicode Nearly Plain Text Encoding of Mathematics</a></dt> <dd>format for lightly marked-up representation of mathematical expressions in Unicode. (Unicode Technical Note. Sole responsibility for its contents rests with the author(s). Publication does not imply any endorsement by the Unicode Consortium.) </dd> <dt>itex</dt> <dd>See <a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/118">the culmination of a relevant discussion in 2003</a>. </dd> </dl> </section> <section id="latex-output"> <h4><a class="toc-backref" href="#toc-entry-20" role="doc-backlink">LaTeX output</a><a class="self-link" title="link to this section" href="#latex-output"></a></h4> Which equation environments should be supported by the math directive? <ul> <li>one line: <ul class="simple"> <li>numbered: <cite>equation</cite></li> <li>unnumbered: <cite>equation*</cite></li> </ul> </li> <li>multiline (test for \\ outside of a nested environment (e.g. <cite>array</cite> or <cite>cases</cite>) <ul> <li>numbered: <cite>align</cite> (number every line) (To give one common number to all lines, put them in a <cite>split</cite> environment. Docutils then places it in an <cite>equation</cite> environment.) </li> <li>unnumbered: <cite>align*</cite></li> <li>Sphinx math also supports <cite>gather</cite> (checking for blank lines in the content). Docutils puts content blocks separated by blank lines in separate math-block doctree nodes. (The only difference of <cite>gather</cite> to two consecutive "normal" environments seems to be that page-breaks between the two are prevented.)</li> </ul> </li> </ul> See <a class="reference external" href="http://www.math.uiuc.edu/~hildebr/tex/displays.html">http://www.math.uiuc.edu/~hildebr/tex/displays.html</a>. </section> <section id="html-output"> <h4><a class="toc-backref" href="#toc-entry-21" role="doc-backlink">HTML output</a><a class="self-link" title="link to this section" href="#html-output"></a></h4> There is no native math support in HTML4. HTML5 has built-in support for MathML. MathML is supported by all major browsers since 2023. For supported math output variants see the <a class="reference external" href="../user/config.html#math-output">math-output setting</a>. <dl> <dt><a class="reference external" href="https://www.w3.org/TR/MathML2/">MathML</a></dt> <dd>Additional converters from LaTeX to MathML <ul class="simple"> <li><a class="reference external" href="http://www.tug.org/applications/tex4ht/mn.html">TeX4ht</a> (TeX based)</li> <li><a class="reference external" href="https://github.com/mathjax/MathJax-node">MathJax for Node</a></li> </ul> </dd> <dt>HTML/CSS</dt> <dd>format math in standard HTML enhanced by CSS rules (<a class="reference external" href="http://www.zipcon.net/~swhite/docs/math/math.html">Examples and experiments</a>). The math-output=html option uses the converter from <a class="reference external" href="http://elyxer.nongnu.org/">eLyXer</a> (included with Docutils). Alternatives: LaTeX-math to HTML/CSS converters include <ul class="simple"> <li><a class="reference external" href="http://para.inria.fr/~maranget/hevea/">Hevea</a> (Objective Caml)</li> <li><a class="reference external" href="https://github.com/mathjax/MathJax-node">MathJax for Node</a></li> <li><a class="reference external" href="https://katex.org">KaTeX</a></li> </ul> </dd> <dt>client side JavaScript conversion</dt> <dd>Use TeX notation in the web page and JavaScript in the displaying browser. (implemented as <a class="reference external" href="../user/config.html#math-output">math-output setting</a> "mathjax"). <ul class="simple"> <li><a class="reference external" href="http://mathscribe.com/author/jqmath.html">jqMath</a> (faster and lighter than <a class="reference external" href="http://www.mathjax.org/">MathJax</a>)</li> </ul> </dd> </dl> </section> <section id="openoffice-output"> <h4><a class="toc-backref" href="#toc-entry-22" role="doc-backlink">OpenOffice output</a><a class="self-link" title="link to this section" href="#openoffice-output"></a></h4> <ul> <li>The <a class="reference external" href="http://www.oasis-open.org/standards#opendocumentv1.1">OpenDocument standard</a> version 1.1 says: <blockquote> Mathematical content is represented by MathML 2.0 </blockquote> However, putting MathML into an ODP file seems tricky as these (maybe outdated) links suppose: <a class="reference external" href="http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx">http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx</a> <a class="reference external" href="http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx">http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx</a> </li> <li><a class="reference external" href="http://ooolatex.sourceforge.net/">OOoLaTeX</a>: "a set of macros designed to bring the power of LaTeX into OpenOffice." </li> </ul> </section> </section> <section id="directives"> <h3><a class="toc-backref" href="#toc-entry-23" role="doc-backlink">Directives</a><a class="self-link" title="link to this section" href="#directives"></a></h3> Directives below are often referred to as "module.directive", the directive function. The "module." is not part of the directive name when used in a document. <ul> <li>Allow for field lists in list tables. See <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.devel/3392">http://thread.gmane.org/gmane.text.docutils.devel/3392</a>>.</li> <li>Unify table implementations and unify options of table directives (<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.user/1857">http://article.gmane.org/gmane.text.docutils.user/1857</a>). </li> <li>Allow directives to be added at run-time?</li> <li>Use the language module for directive option names?</li> <li>Add "substitution_only" and "substitution_ok" function attributes, and automate context checking?</li> <li>Implement options or features on existing directives: <ul> <li>All directives that produce titled elements should grow implicit reference names based on the titles.</li> <li>Allow the :trim: option for all directives when they occur in a substitution definition, not only the <a class="reference external" href="../ref/rst/directives.html#unicode-character-codes">unicode</a> directive. </li> <li>Add the "class" option to the <a class="reference external" href="../ref/rst/directives.html#unicode-character-codes">unicode</a> directive. For example, you might want to get characters or strings with borders around them.</li> <li>images.figure: "title" and "number", to indicate a formal figure?</li> <li>parts.sectnum: "local"?, "refnum" A "local" option could enable numbering for sections from a certain point down, and sections in the rest of the document are not numbered. For example, a reference section of a manual might be numbered, but not the rest. OTOH, an all-or-nothing approach would probably be enough. The "sectnum" directive should be usable multiple times in a single document. For example, in a long document with "chapter" and "appendix" sections, there could be a second "sectnum" before the first appendix, changing the sequence used (from 1,2,3... to A,B,C...). This is where the "local" concept comes in. This part of the implementation can be left for later. A "refnum" option (better name?) would insert reference names (targets) consisting of the reference number. Then a URL could be of the form http://host/document.html#2.5 (or "2-5"?). Allow internal references by number? Allow name-based and number-based ids at the same time, or only one or the other (which would the table of contents use)? Usage issue: altering the section structure of a document could render hyperlinks invalid. </li> <li>parts.contents: Add a "suppress" or "prune" option? It would suppress contents display for sections in a branch from that point down. Or a new directive, like "prune-contents"? Add an option to include topics in the TOC? Another for sidebars? The "topic" directive could have a "contents" option, or the "contents" directive" could have an "include-topics" option. See docutils-develop 2003-01-29. </li> <li>parts.header & parts.footer: Support multiple, named headers & footers? For example, separate headers & footers for odd, even, and the first page of a document. This may be too specific to output formats which have a notion of "pages". </li> <li>misc.class: <ul class="simple"> <li>Add a :parent: option for setting the parent's class (<a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3165">http://article.gmane.org/gmane.text.docutils.devel/3165</a>).</li> </ul> </li> <li>misc.include: <ul> <li>Option to label lines?</li> <li>How about an environment variable, say RSTINCLUDEPATH or RSTPATH, for standard includes (as in .. include:: <name>)? This could be combined with a setting/option to allow user-defined include directories.</li> <li>Add support for inclusion by URL? <pre class="literal-block">.. include:: :url: https://www.example.org/inclusion.rst</pre> </li> <li>Strip blank lines from begin and end of a literal included file or file section. This would correspond to the way a literal block is handled. As nodes.literal_block expects (and we have) the text as a string (rather than a list of lines), using a regexp seems the way. </li> </ul> </li> <li>misc.raw: add a "destination" option to the "raw" directive? <pre class="literal-block">.. raw:: html :destination: head <link ...></pre> It needs thought & discussion though, to come up with a consistent set of destination labels and consistent behavior. And placing HTML code inside the <head> element of an HTML document is rather the job of a templating system. </li> <li>body.sidebar: Allow internal section structure? Adornment styles would be independent of the main document. That is really complicated, however, and the document model greatly benefits from its simplicity. </li> </ul> </li> <li>Implement directives. Each of the list items below begins with an identifier of the form, "module_name.directive_function_name". The directive name itself could be the same as the directive_function_name, or it could differ. <ul> <li>html.imagemap It has the disadvantage that it's only easily implementable for HTML, so it's specific to one output format. (For non-HTML writers, the imagemap would have to be replaced with the image only.) </li> <li>parts.endnotes (or "footnotes"): See <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>.</li> <li>parts.citations: See <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>.</li> <li>misc.language: Specify (= change) the language of a document at parse time? <ul class="simple"> <li>The <a class="reference internal" href="#misc-settings">misc.settings</a> directive suggested below offers a more generic approach.</li> <li>The language of document parts can be indicated by the "special class value" "language-" + <a class="reference external" href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a> language code. Class arguments to the title are attached to the document's base node - hence titled documents can be given a different language at parse time. However, "language by class attribute" does not change parsing (localized directives etc.), only supporting writers.</li> </ul> </li> <li>misc.settings: Set any(?) Docutils runtime setting from within a document? Needs much thought and discussion. Security concerns need to be taken into account (it shouldn't be possible to enable file_insertion_enabled from within a document), and settings that only would have taken effect before the directive (like tab-width) shouldn't be accessible either. See this sub-thread: <<a class="reference external" href="http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649">http://thread.gmane.org/gmane.text.docutils.user/3620/focus=3649</a>> </li> <li>misc.gather: Gather (move, or copy) all instances of a specific element. A generalization of the <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a> ideas.</li> <li>Add a custom "directive" directive, equivalent to "role"? For example: <pre class="literal-block">.. directive:: incr .. class:: incremental .. incr:: "``.. incr::``" above is equivalent to "``.. class:: incremental``".</pre> Another example: <pre class="literal-block">.. directive:: printed-links .. topic:: Links :class: print-block .. target-notes:: :class: print-inline</pre> This acts like macros. The directive contents will have to be evaluated when referenced, not when defined. <ul class="simple"> <li>Needs a better name? "Macro", "substitution"?</li> <li>What to do with directive arguments & options when the macro/directive is referenced?</li> </ul> </li> <li>Make the meaning of block quotes overridable? Only a 1-shot though; doesn't solve the general problem.</li> <li>conditional directives: <aside class="admonition note"> Note See also the implementation in <a class="reference external" href="http://www.sphinx-doc.org/">Sphinx</a>. </aside> Docutils already has the ability to say "use this content for Writer X" via the "raw" directive. It also does have the ability to say "use this content for any Writer other than X" via the "strip-elements with class" config value. However, using "raw" input just to select a special writer is inconvenient in many cases. It wouldn't be difficult to get more straightforward support, though. My first idea would be to add a set of conditional directives. Let's call them "writer-is" and "writer-is-not" for discussion purposes (don't worry about implementation details). We might have: <pre class="literal-block">.. writer-is:: text-only :: +----------+ | SNMP | +----------+ | UDP | +----------+ | IP | +----------+ | Ethernet | +----------+ .. writer-is:: pdf .. figure:: protocol_stack.eps .. writer-is-not:: text-only pdf .. figure:: protocol_stack.png</pre> This could be an interface to the Filter transform (docutils.transforms.components.Filter). The ideas in the <a class="reference internal" href="#adaptable-file-extensions">adaptable file extensions</a> section above may also be applicable here. SVG's "switch" statement may provide inspiration. Here's an example of a directive that could produce multiple outputs (both raw troff pass-through and a GIF, for example) and allow the Writer to select. <pre class="literal-block">.. eqn:: .EQ delim %% .EN %sum from i=o to inf c sup i~=~lim from {m -> inf} sum from i=0 to m sup i% .EQ delim off .EN</pre> </li> <li>body.example: Examples; suggested by Simon Hefti. Semantics as per Docbook's "example"; admonition-style, numbered, reference, with a caption/title.</li> <li>body.index: Index targets. See <a class="reference external" href="./rst/alternatives.html#index-entries-indexes">Index Entries & Indexes</a>. </li> <li>body.literal: Literal block, possibly "formal" (see <a class="reference internal" href="#object-numbering-and-object-references">object numbering and object references</a> above). Possible options: <ul> <li>"highlight" a range of lines</li> <li>include only a specified range of lines</li> <li>"number" or "line-numbers"? (since 0.9 available with "code" directive)</li> <li>"styled" could indicate that the directive should check for style comments at the end of lines to indicate styling or markup. Specific derivatives (i.e., a "python-interactive" directive) could interpret style based on cues, like the ">>> " prompt and "input()"/"raw_input()" calls. </li> </ul> See docutils-users 2003-03-03. </li> <li>body.listing: Code listing with title (to be numbered eventually), equivalent of "figure" and "table" directives.</li> <li>pysource.usage: Extract a usage message from the program, either by running it at the command line with a --help option or through an exposed API. [Suggestion for Optik.]</li> <li>body.float: Generic float that can be used for figures, tables, code listings, flowcharts, ... There is a Sphinx extension by Ignacio Fernández Galván <<a class="reference external" href="mailto:jellby@gmail.com">jellby@gmail.com</a>> <blockquote> <blockquote> I implemented something for generic floats in sphinx, and submitted a pull request that is still waiting: <pre class="literal-block">.. float:: :type: figure :caption: My caption</pre> </blockquote> <a class="reference external" href="https://github.com/sphinx-doc/sphinx/pull/1858">https://github.com/sphinx-doc/sphinx/pull/1858</a> </blockquote> </li> </ul> </li> </ul> </section> <section id="interpreted-text"> <h3><a class="toc-backref" href="#toc-entry-24" role="doc-backlink">Interpreted Text</a><a class="self-link" title="link to this section" href="#interpreted-text"></a></h3> Interpreted text is entirely a reStructuredText markup construct, a way to get around built-in limitations of the medium. Some roles are intended to introduce new doctree elements, such as "title-reference". Others are merely convenience features, like "RFC". All supported interpreted text roles must already be known to the Parser when they are encountered in a document. Whether pre-defined in core/client code, or in the document, doesn't matter; the roles just need to have already been declared. Adding a new role may involve adding a new element to the DTD and may require extensive support, therefore such additions should be well thought-out. There should be a limited number of roles. The only place where no limit is placed on variation is at the start, at the Reader/Parser interface. Transforms are inserted by the Reader into the Transformer's queue, where non-standard elements are converted. Once past the Transformer, no variation from the standard Docutils doctree is possible. An example is the Python Source Reader, which will use interpreted text extensively. The default role will be "Python identifier", which will be further interpreted by namespace context into <class>, <method>, <module>, <attribute>, etc. elements (see pysource.dtd), which will be transformed into standard hyperlink references, which will be processed by the various Writers. No Writer will need to have any knowledge of the Python-Reader origin of these elements. <ul> <li>Add explicit interpreted text roles for the rest of the implicit inline markup constructs: named-reference, anonymous-reference, footnote-reference, citation-reference, substitution-reference, target, uri-reference (& synonyms).</li> <li>Add directives for each role as well? This would allow indirect nested markup: <pre class="literal-block">This text contains |nested inline markup|. .. |nested inline markup| emphasis:: nested ``inline`` markup</pre> </li> <li>Implement roles: <ul> <li>"raw-wrapped" (or "raw-wrap"): Base role to wrap raw text around role contents. For example, the following reStructuredText source ... <pre class="literal-block">.. role:: red(raw-formatting) :prefix: :html: :latex: {\color{red} :suffix: :html: :latex: } colored :red:`text`</pre> ... will yield the following document fragment: <pre class="literal-block"><paragraph> colored <inline classes="red"> <raw format="html"> <raw format="latex"> {\color{red} <inline classes="red"> text <raw format="html"> <raw format="latex"> }</pre> Possibly without the intermediate "inline" node. </li> <li>"acronym" and "abbreviation": Associate the full text with a short form. Jason Diamond's description: <blockquote> I want to translate `reST`:acronym: into <acronym title='reStructuredText'>reST</acronym>. The value of the title attribute has to be defined out-of-band since you can't parameterize interpreted text. Right now I have them in a separate file but I'm experimenting with creating a directive that will use some form of reST syntax to let you define them. </blockquote> Should Docutils complain about undefined acronyms or abbreviations? What to do if there are multiple definitions? How to differentiate between CSS (Content Scrambling System) and CSS (Cascading Style Sheets) in a single document? David Priest responds, <blockquote> The short answer is: you don't. Anyone who did such a thing would be writing very poor documentation indeed. (Though I note that <a class="reference external" href="rst/alternatives.html#parameterized-interpreted-text">somewhere else in the docs</a>, there's mention of allowing replacement text to be associated with the abbreviation. That takes care of the duplicate acronyms/abbreviations problem, though a writer would be foolish to ever need it.) </blockquote> How to define the full text? Possibilities: <ol class="arabic"> <li>With a directive and a definition list? <pre class="literal-block">.. acronyms:: reST reStructuredText DPS Docstring Processing System</pre> Would this list remain in the document as a glossary, or would it simply build an internal lookup table? A "glossary" directive could be used to make the intention clear. Acronyms/abbreviations and glossaries could work together. Then again, a glossary could be formed by gathering individual definitions from around the document. </li> <li>Some kind of <a class="reference external" href="rst/alternatives.html#parameterized-interpreted-text">inline parameter syntax</a>? <pre class="literal-block">`reST <reStructuredText>`:acronym: is `WYSIWYG <what you see is what you get>`:acronym: plaintext markup.</pre> </li> <li>A combination of 1 & 2? The multiple definitions issue could be handled by establishing rules of priority. For example, directive-based lookup tables have highest priority, followed by the first inline definition. Multiple definitions in directive-based lookup tables would trigger warnings, similar to the rules of <a class="reference external" href="../ref/rst/restructuredtext.html#implicit-hyperlink-targets">implicit hyperlink targets</a>. </li> <li>Using substitutions? <pre class="literal-block">.. |reST| acronym:: reST :text: reStructuredText</pre> </li> </ol> What do we do for other formats than HTML which do not support tool tips? Put the full text in parentheses? </li> <li>"figure", "table", "listing", "chapter", "page", etc: See <a class="reference internal" href="#object-numbering-and-object-references">object numbering and object references</a> above.</li> <li>"glossary-term": This would establish a link to a glossary. It would require an associated "glossary-entry" directive, whose contents could be a definition list: <pre class="literal-block">.. glossary-entry:: term1 definition1 term2 definition2</pre> This would allow entries to be defined anywhere in the document, and collected (via a "glossary" directive perhaps) at one point. </li> </ul> </li> </ul> </section> <section id="doctree-pruning"> <h3><a class="toc-backref" href="#toc-entry-25" role="doc-backlink">Doctree pruning</a><a class="self-link" title="link to this section" href="#doctree-pruning"></a></h3> [DG 2017-01-02: These are not definitive to-dos, just one developer's opinion. Added 2009-10-13 by Günter Milde, in r6178.] [Updated by GM 2017-02-04] The number of doctree nodes can be reduced by "normalizing" some related nodes. This makes the document model and the writers somewhat simpler. <ul> <li>The "doctest" element can be replaced by literal blocks with a class attribute (similar to the "code" directive output). The syntax shall be left in reST. [DG 2017-01-02:] +0. <dl> <dt>Discussion</dt> <dd>The syntax could be left in reST (for a set period of time?). [DG 2017-01-02:] The syntax must be left in reST, practically forever. Removing it would introduce a huge backwards incompatibility. Any syntax removal must be preceded by a thorough review and planning, including a deprecation warning process. My opinion: it's not worth it. </dd> </dl> </li> <li>"Normalize" special admonitions (note, hint, warning, ...) during parsing (similar to transforms.writer_aux.Admonitions). There is no need to keep them as distinct elements in the doctree specification. [DG 2017-01-02:] -1: <note>{body}</> is much more concise and expressive than <admonition><title>Note</>{body}</>, and the title translation can be put off until much later in the process. [GM 2017-02-04]: <dl class="simple"> <dt>-0 for <admonition class=note><title>Note</>... instead of <note>:</dt> <dd>a document is rarely printed/used as doctree or XML. </dd> <dt>+1 reduce the complexity of the doctree</dt> <dd>(there is no 1:1 rST syntax element <-> doctree node mapping anyway). </dd> <dt>+2 every writer needs 9 visit_*/depart_* method pairs to handle the 9</dt> <dd>subtypes of an admonition, i.e. we could but also remove 36 redundant methods (HTML, LaTeX, Manpage, ODF). </dd> </dl> -1 the most unfortunately named of these directives will survive. <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref">[1]</a> <blockquote> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="footnote-1" role="doc-footnote"> [<a role="doc-backlink" href="#footnote-reference-1">1</a>] with "biblical touch" and hard to translate: <dl class="field-list"> <dt>admonition:</dt> <dd><div class="line-block"> <div class="line">Ermahnung; Verweis; Warnung; Rüge</div> <div class="line">(exhortation; censure; warning; reprimand, rebuke)</div> </div> </dd> </dl> </aside> </aside> </blockquote> Keep the special admonition directives in reStructuredText syntax. [DG 2017-01-02:] We must definitely keep the syntax. Removing it would introduce a huge backwards incompatibility. </li> </ul> </section> </section> <section id="unimplemented-transforms"> <h2><a class="toc-backref" href="#toc-entry-26" role="doc-backlink">Unimplemented Transforms</a><a class="self-link" title="link to this section" href="#unimplemented-transforms"></a></h2> <ul> <li>Footnote & Citation Gathering Collect and move footnotes & citations to the end of a document or the place of a "footnotes" or "citations" directive (see <cite><./ref/rst/directives.html>_</cite>) <dl> <dt>Footnotes:</dt> <dd>Collect all footnotes that are referenced in the document before the directive (and after an eventually preceding .. footnotes:: directive) and insert at this place. Allows "endnotes" at a configurable place. </dd> <dt>Citations:</dt> <dd>Collect citations that are referenced ... Citations can be: <ol class="loweralpha simple"> <li>defined in the document as citation elements</li> <li>auto-generated from entries in a bibliographic database. <ul class="simple"> <li>based on <a class="reference external" href="http://code.google.com/p/bibstuff/">bibstuff</a>?</li> <li>also have a look at <ul> <li><a class="reference external" href="http://www.cs.cornell.edu/people/egs/crosstex/">CrossTeX</a>, a backwards-compatible, improved bibtex re-implementation in Python (including HTML export). (development stalled since 2 years)</li> <li><a class="reference external" href="http://pybtex.sourceforge.net/">Pybtex</a>,a drop-in replacement for BibTeX written in Python. <ul> <li>BibTeX styles & (experimental) pythonic style API.</li> <li>Database in BibTeX, BibTeXML and YAML formats.</li> <li>full Unicode support.</li> <li>Write to TeX, HTML and plain text.</li> </ul> </li> <li><a class="reference external" href="http://e6h.org/%7Eegh/hg/zotero-plain/">Zotero plain</a> supports Zotero databases and <a class="reference external" href="http://www.citationstyles.org/">CSL</a> styles with Docutils with an xcite role.</li> <li><a class="reference external" href="http://sphinxcontrib-bibtex.readthedocs.org/">sphinxcontrib-bibtex</a> Sphinx extension with "bibliography" directive and "cite" role supporting BibTeX databases.</li> <li><a class="reference external" href="http://www.loria.fr/~rougier/coding/article/rst2html.py">Modified rst2html</a> by Nicolas Rougier.</li> </ul> </li> </ul> </li> </ol> <ul class="simple"> <li>Automatically insert a "References" heading?</li> </ul> </dd> </dl> </li> </ul> <ul> <li>Reference Merging When merging two or more subdocuments (such as docstrings), conflicting references may need to be resolved. There may be: <ul class="simple"> <li>duplicate reference and/or substitution names that need to be made unique; and/or</li> <li>duplicate footnote numbers that need to be renumbered.</li> </ul> Should this be done before or after reference-resolving transforms are applied? What about references from within one subdocument to inside another? </li> <li>Document Splitting If the processed document is written to multiple files (possibly in a directory tree), it will need to be split up. Internal references will have to be adjusted. (HTML only? Initially, yes. Eventually, anything should be splittable.) Ideas: <ul> <li>Insert a "destination" attribute into the root element of each split-out document, containing the path/filename. The Output object or Writer will recognize this attribute and split out the files accordingly. Must allow for common headers & footers, prev/next, breadcrumbs, etc.</li> <li>Transform a single-root document into a document containing multiple subdocuments, recursively. The content model of the "document" element would have to change to: <pre class="literal-block"><!ELEMENT document ( (title, subtitle?)?, decoration?, (docinfo, transition?)?, %structure.model;, document* )></pre> (I.e., add the last line -- 0 or more document elements.) Let's look at the case of hierarchical (directories and files) HTML output. Each document element containing further document elements would correspond to a directory (with an index.html file for the content preceding the subdocuments). Each document element containing no subdocuments (i.e., structure model elements only) corresponds to a concrete file with no directory. The natural transform would be to map sections to subdocuments, but possibly only a given number of levels deep. </li> </ul> </li> <li>Navigation If a document is split up, each segment will need navigation links: parent, children (small TOC), previous (preorder), next (preorder). Part of <a class="reference internal" href="#document-splitting">Document Splitting</a>? </li> <li>List of System Messages The system_message elements are inserted into the document tree, adjacent to the problems themselves where possible. Some (those generated post-parse) are kept until later, in document.messages, and added as a special final section, "Docutils System Messages". Docutils could be made to generate hyperlinks to all known system_messages and add them to the document, perhaps to the end of the "Docutils System Messages" section. Fred L. Drake, Jr. wrote: <blockquote> I'd like to propose that both parse- and transformation-time messages are included in the "Docutils System Messages" section. If there are no objections, I can make the change. </blockquote> The advantage of the current way of doing things is that parse-time system messages don't require a transform; they're already in the document. This is valuable for testing (unit tests, tools/dev/quicktest.py). So if we do decide to make a change, I think the insertion of parse-time system messages ought to remain as-is and the Messages transform ought to move all parse-time system messages (remove from their originally inserted positions, insert in System Messages section). </li> <li>Index Generation</li> </ul> </section> <section id="html-writer"> <h2><a class="toc-backref" href="#toc-entry-27" role="doc-backlink">HTML Writer</a><a class="self-link" title="link to this section" href="#html-writer"></a></h2> <ul> <li>Make the list compacting logic more generic: For example, allow for literal blocks or line blocks inside of compact list items. This is not implementable as long as list compacting is done by omitting tags. List compacting would need to be done by adjusting CSS margins instead. <dl class="field-list"> <dt>2015-04-02:</dt> <dd>The new html writer no longer strips tags but adds the class value simple to the list. Formatting is done by CSS --- configurable by a custom style sheet. Auto-compactization can be overridden by the open vs. compact class arguments. </dd> </dl> </li> <li>Idea for field-list rendering: hanging indent: <pre class="literal-block">Field name (bold): First paragraph of field body begins with the field name inline. If the first item of a field body is not a paragraph, it would begin on the following line.</pre> <dl class="field-list simple"> <dt>2015-04-02:</dt> <dd>The new html writer writes field-lists as definition lists with class field-list. Formatting is done by CSS --- configurable by a custom style sheet. The default style sheet has some examples, including a run-in field-list style. </dd> </dl> </li> <li>Add more support for <link> elements, especially for navigation bars. The framework does not have a notion of document relationships, so probably <a class="reference internal" href="#misc-raw">raw.destination</a> should be used. We'll have framework support for document relationships when support for <a class="reference internal" href="#multiple-output-files">multiple output files</a> is added. The HTML writer could automatically generate <link> elements then. </li> <li>Base list compaction on the spacing of source list? Would require parser support. (Idea: fantasai, 16 Dec 2002, doc-sig.)</li> <li>Add a tool tip ("title" attribute?) to footnote back-links identifying them as such. Text in Docutils language module.</li> <li>Set HTML "width" and "height" attributes with the original size (read from the image) to prevent layout shifts: <blockquote> Layout shifts are very disrupting to the user, especially if you have already started reading the article and suddenly you are thrown off by a jolt of movement, and you have to find your place again. —<a class="reference external" href="https://www.smashingmagazine.com/2020/03/setting-height-width-images-important-again/.">Setting Height And Width On Images Is Important Again</a> </blockquote> <ul class="simple"> <li>If there are no size options (:widht:, :height:, :scale:) in the "image" directive and the image is local and can be read and interpreted by PIM. (if not, silently skip).</li> <li>Alternatively, if the only size option is :scale: 100% and the image can be read with urllib (opt-in for the "costly" variant).</li> </ul> </li> </ul> </section> <section id="pep-html-writer"> <h2><a class="toc-backref" href="#toc-entry-28" role="doc-backlink">PEP/HTML Writer</a><a class="self-link" title="link to this section" href="#pep-html-writer"></a></h2> <ul> <li>Remove the generic style information (duplicated from html4css1.css) from pep.css to avoid redundancy. Set stylesheet-path to "html4css.css,pep.css" and the stylesheet-dirs accordingly instead. (See the xhtml11 writer for an example.) </li> </ul> </section> <section id="s5-html-writer"> <h2><a class="toc-backref" href="#toc-entry-29" role="doc-backlink">S5/HTML Writer</a><a class="self-link" title="link to this section" href="#s5-html-writer"></a></h2> <ul> <li>Add a way to begin an untitled slide.</li> <li>Add a way to begin a new slide, continuation, using the same title as the previous slide? (Unnecessary?) You need that if you have a lot of items in one section which don't fit on one slide. Maybe either this item or the previous one can be realized using transitions. </li> <li>Have a timeout on incremental items, so the colour goes away after 1 second.</li> <li>Add an empty, black last slide (optionally). Currently the handling of the last slide is not very nice, it re-cycles through the incremental items on the last slide if you hit space-bar after the last item.</li> <li>Add a command-line option to disable advance-on-click.</li> <li>Add a speaker's master document, which would contain a small version of the slide text with speaker's notes interspersed. The master document could use target="whatever" to direct links to a separate window on a second monitor (e.g., a projector). <aside class="admonition note"> Note This item and the following items are partially accomplished by the S5 1.2 code (currently in alpha), which has not yet been integrated into Docutils. </aside> </li> <li>Speaker's notes -- how to intersperse? Could use reST comments (".."), but make them visible in the speaker's master document. If structure is necessary, we could use a "comment" directive (to avoid nonsensical DTD changes, the "comment" directive could produce an untitled topic element). The speaker's notes could (should?) be separate from S5's handout content. </li> <li>The speaker's master document could use frames for easy navigation: TOC on the left, content on the right. <ul class="simple"> <li>It would be nice if clicking in the TOC frame simultaneously linked to both the speaker's notes frame and to the slide window, synchronizing both. Needs JavaScript?</li> <li>TOC would have to be tightly formatted -- minimal indentation.</li> <li>TOC auto-generated, as in the PEP Reader. (What if there already is a "contents" directive in the document?)</li> <li>There could be another frame on the left (top-left or bottom-left) containing a single "Next" link, always pointing to the next slide (synchronized, of course). Also "Previous" link? FF/Rew go to the beginning of the next/current parent section? First/Last also? Tape-player-style buttons like |<< << < > >> >>|?</li> </ul> </li> </ul> </section> <section id="epub-html-writer"> <h2><a class="toc-backref" href="#toc-entry-30" role="doc-backlink">Epub/HTML Writer</a><a class="self-link" title="link to this section" href="#epub-html-writer"></a></h2> Add epub as an output format. <blockquote> epub is an open file format for ebooks based on HTML, specified by the <a class="reference external" href="http://www.idpf.org/">International Digital Publishing Forum</a>. Thus, documents in epub format are suited to be read with <a class="reference external" href="https://en.wikipedia.org/wiki/List_of_e-book_readers">electronic reading devices</a>. </blockquote> Pack the output of a HTML writer and supporting files (e.g. images) into one single epub document. There are <a class="reference external" href="../user/links.html#ePub">links to two 3rd party ePub writers</a> in the Docutils link list. Test and consider moving the better one into the docutils core. </section> <section id="latex-writer"> <h2><a class="toc-backref" href="#toc-entry-31" role="doc-backlink">LaTeX writer</a><a class="self-link" title="link to this section" href="#latex-writer"></a></h2> Also see the <a class="reference external" href="../user/latex.html#problems">Problems</a> section in the <a class="reference external" href="../user/latex.html">latex writer documentation</a>. <section id="bug-fixes"> <h3><a class="toc-backref" href="#toc-entry-32" role="doc-backlink">Bug fixes</a><a class="self-link" title="link to this section" href="#bug-fixes"></a></h3> <ul> <li>Too deeply nested lists fail: generate a warning and provide a workaround. 2017-02-09 this is fixed for enumeration in 0.13.1 for others, cf. sandbox/latex-variants/tests/rst-levels.txt </li> <li>File names of included graphics (see also <cite>grffile</cite> package).</li> <li>Paragraph following field-list or table in compound is indented. This is a problem with the current DUfieldlist definition and with the use of "longtable" for tables. See <a class="reference internal" href="#other-latex-constructs-and-packages-instead-of-re-implementations">other LaTeX constructs and packages instead of re-implementations</a> for alternatives. </li> </ul> </section> <section id="generate-clean-and-configurable-latex-source"> <h3><a class="toc-backref" href="#toc-entry-33" role="doc-backlink">Generate clean and configurable LaTeX source</a><a class="self-link" title="link to this section" href="#generate-clean-and-configurable-latex-source"></a></h3> Which packages do we want to use? <ul> <li>base and "recommended" packages (packages that should be in a "reasonably sized and reasonably modern LaTeX installation like the <cite>texlive-latex-recommended</cite> Debian package, say): </li> <li>No "fancy" or "exotic" requirements.</li> <li>pointers to advanced packages and their use in the <a class="reference external" href="../user/latex.html">latex writer documentation</a>.</li> </ul> <section id="configurable-placement-of-figure-and-table-floats"> <h4><a class="toc-backref" href="#toc-entry-34" role="doc-backlink">Configurable placement of figure and table floats</a><a class="self-link" title="link to this section" href="#configurable-placement-of-figure-and-table-floats"></a></h4> <ul> <li>Special class argument to individually place figures? Example: <pre class="literal-block">.. figure:: foo.pdf :class: place-here-if-possible place-top place-bottom</pre> would be written as \figure[htb]{...} with the optional args: <dl class="field-list simple"> <dt>H:</dt> <dd>place-here </dd> <dt>h:</dt> <dd>place-here-if-possible </dd> <dt>t:</dt> <dd>place-top </dd> <dt>b:</dt> <dd>place-bottom </dd> <dt>p:</dt> <dd>place-on-extra-page </dd> </dl> Alternative: class value = "place-" + optional arg, e.g. :class: place-htb. </li> </ul> </section> <section id="footnotes"> <h4><a class="toc-backref" href="#toc-entry-35" role="doc-backlink">Footnotes</a><a class="self-link" title="link to this section" href="#footnotes"></a></h4> <ul> <li>True footnotes with LaTeX auto-numbering (as option --latex-footnotes) (also for target-footnotes): Write \footnote{<footnote content>} at the place of the <footnote_reference> node.</li> <li>Open questions: <ul> <li>Load <a class="reference external" href="https://www.ctan.org/pkg/hyperref">hyperref</a> with option "hyperfootnotes" and/or package <a class="reference external" href="https://www.ctan.org/pkg/footnotebackref">footnotebackref</a> or leave this to the user?</li> <li>Consider cases where LaTeX does not support footnotes (inside <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=footintab">tables</a>, <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=ftnsect">headings</a>, caption, ...). Use <a class="reference external" href="https://www.ctan.org/pkg/ftnxtra">ftnxtra</a>, <a class="reference external" href="https://www.ctan.org/pkg/tabularx">tabularx</a>, <a class="reference external" href="https://www.ctan.org/pkg/tabulary">tabulary</a>, <a class="reference external" href="https://www.ctan.org/pkg/longtable">longtable</a>? </li> <li>Consider <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=multfoot">multiple footnote refs to common footnote text</a>. KOMA-script classes and the KOMA <a class="reference external" href="https://www.ctan.org/pkg/longtable">scrextend</a> package provide \footref that can be used for additional references to a \label-ed footnote. Since 2021-05-01, \footref is provided by the LaTeX core, too. </li> <li>Consider numbered vs. symbolic footnotes.</li> </ul> </li> <li>document customization (links to how-to and packages)</li> </ul>   </section> <section id="other-latex-constructs-and-packages-instead-of-re-implementations"> <h4><a class="toc-backref" href="#toc-entry-36" role="doc-backlink">Other LaTeX constructs and packages instead of re-implementations</a><a class="self-link" title="link to this section" href="#other-latex-constructs-and-packages-instead-of-re-implementations"></a></h4> <ul class="simple"> <li>Check the generated source with package <cite>nag</cite>.</li> <li><a class="reference external" href="https://www.ctan.org/pkg/enumitem">enumitem</a> (texlive-latex-extra) for field-lists?</li> </ul> </section> </section> <section id="default-layout"> <h3><a class="toc-backref" href="#toc-entry-37" role="doc-backlink">Default layout</a><a class="self-link" title="link to this section" href="#default-layout"></a></h3> <ul> <li>Use italic instead of slanted for titlereference?</li> <li>Start a new paragraph after lists (as currently) or continue (no blank line in source, no parindent in output)? Overriding: <ul class="simple"> <li>continue if the <a class="reference external" href="../ref/rst/directives.html#compound-paragraph">compound paragraph</a> directive is used (as currently), or</li> <li>force a new paragraph with an empty comment.</li> </ul> </li> <li>Sidebar handling (environment with <cite>framed</cite>, <cite>marginnote</cite>, <cite>wrapfig</cite>, ...)?</li> <li>Use optionlist for docinfo?</li> <li>Keep literal-blocks together on a page, avoid pagebreaks. Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before the block. Should be possible with --literal-block-env==lstlistings and some configuration... </li> <li>More space between title and subtitle? <pre class="literal-block">- \\ % subtitle% + \\[0.5em] % subtitle%</pre> </li> </ul> <section id="tables"> <h4><a class="toc-backref" href="#toc-entry-38" role="doc-backlink">Tables</a><a class="self-link" title="link to this section" href="#tables"></a></h4> <ul> <li>Improve/simplify logic to set the column width in the output. <ul class="simple"> <li>Assumed reST line length for table width setting configurable, or</li> <li>use <cite>ltxtable</cite> (a combination of <cite>tabularx</cite> (auto-width) and <cite>longtable</cite> (page breaks)), or</li> <li>use tabularx column type X and let LaTeX decide width, or</li> <li>use <a class="reference external" href="https://www.ctan.org/pkg/tabulary">tabulary</a>?</li> </ul> </li> <li>From comp.text.tex (13. 4. 2011): <blockquote> When using fixed width columns, you should ensure that the total width does not exceed linewidth: if the first column is p{6cm} the second one should be p{dimexprlinewidth-6cm-4tabcolsep} because the glue tabcolsep is added twice at every column edge. You may also consider to set tabcolsep to a different value... </blockquote> </li> <li>csv-tables do not have a colwidth.</li> <li>Add more classes or options, e.g. for <ul class="simple"> <li>horizontal alignment and rules.</li> <li>long table vs. tabular (see next item).</li> </ul> </li> <li>Use tabular instead of longtable for tables in legends or generally inside a float? Alternatively, default to tabular and use longtable only if specified by config setting or class argument (analogue to booktable)? </li> <li>Table heads and footer for longtable (firstpage lastpage ..)?</li> <li>In tools.rst the option tables right column, there should be some more spacing between the description and the next paragraph "Default:".</li> <li>Paragraph separation in tables is hairy. see <a class="reference external" href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab</a> <ul class="simple"> <li>The strut solution did not work.</li> <li>setting extrarowheight added ad top of row not between paragraphs in a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.</li> <li>baselineskip/stretch does not help.</li> </ul> </li> <li>Should there be two hlines after table head and on table end?</li> <li>Place titled tables in a float ('table' environment)? The 'table', 'csv-table', and 'list-table' directives support an (optional) table title. In analogy to the 'figure' directive this should map to a table float. </li> </ul> </section> <section id="image-and-figure-directives"> <h4><a class="toc-backref" href="#toc-entry-39" role="doc-backlink">Image and figure directives</a><a class="self-link" title="link to this section" href="#image-and-figure-directives"></a></h4> <ul> <li>compare the test case in: <ul class="simple"> <li><a class="reference external" href="../../test/functional/input/data/standard.rst">../../test/functional/input/data/standard.rst</a></li> <li><a class="reference external" href="../../test/functional/expected/standalone_rst_html4css1.html">../../test/functional/expected/standalone_rst_html4css1.html</a></li> <li><a class="reference external" href="../../test/functional/expected/standalone_rst_latex.tex">../../test/functional/expected/standalone_rst_latex.tex</a></li> </ul> </li> <li>The default CSS styling for HTML output (plain.css, default.css) lets text following a right- or left-aligned image float to the side of the image/figure. <ul class="simple"> <li>Use this default also for LaTeX?</li> <li>Wrap text around figures/images with class argument "wrap" (like the odt writer)?</li> </ul> Use <cite>wrapfig</cite> (or other recommended) package. </li> <li>support more graphic formats (especially SVG, the only standard vector format for HTML)</li> </ul> </section> </section> <section id="missing-features"> <h3><a class="toc-backref" href="#toc-entry-40" role="doc-backlink">Missing features</a><a class="self-link" title="link to this section" href="#missing-features"></a></h3> <ul> <li>support "figwidth" argument for figures. As the 'figwidth' argument is still ignored and the "natural width" of a figure in LaTeX is 100 % of the text width, setting the 'align' argument has currently no effect on the LaTeX output. </li> <li>Multiple author entries in docinfo (same thing as in html).</li> <li>Consider supporting the "compact" option and class argument (from rst2html) as some lists look better compact and others need the space.</li> <li>Better citation support (see <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>).</li> <li>If use-latex-citations is used, a bibliography is inserted right at the end of the document. Put in place of the to-be-implemented "citations" directive (see <a class="reference internal" href="#footnote-citation-gathering">Footnote & Citation Gathering</a>). </li> </ul> <section id="unicode-to-latex"> <h4><a class="toc-backref" href="#toc-entry-41" role="doc-backlink">Unicode to LaTeX</a><a class="self-link" title="link to this section" href="#unicode-to-latex"></a></h4> The <a class="reference external" href="http://www.lyx.org">LyX</a> document processor has a comprehensive Unicode to LaTeX conversion feature with a file called unicodesymbols that lists LaTeX counterparts for a wide range of Unicode characters. <ul class="simple"> <li>Use this in the LaTeXTranslator? Think of copyright issues!</li> <li>The "ucs" package has many translations in ...doc/latex/ucs/config/</li> <li>The <a class="reference external" href="http://code.google.com/p/bibstuff/">bibstuff</a> tool ships a <cite>latex_codec</cite> Python module!</li> </ul> </section> <section id="xetex-writer"> <h4><a class="toc-backref" href="#toc-entry-42" role="doc-backlink">XeTeX writer</a><a class="self-link" title="link to this section" href="#xetex-writer"></a></h4> <ul class="simple"> <li>Glyphs missing in the font are left out in the PDF without warning (e.g. ⇔ left-right double arrow in the functional test output).</li> <li>Disable word-wrap (hyphenation) in literal text locally with providecommand{\nohyphenation}{\addfontfeatures{HyphenChar=None}}?</li> </ul> </section> <section id="problematic-urls"> <h4><a class="toc-backref" href="#toc-entry-43" role="doc-backlink">problematic URLs</a><a class="self-link" title="link to this section" href="#problematic-urls"></a></h4> <ul> <li>^^ LaTeX's special syntax for characters results in "strange" replacements (both with href and url). <a class="reference external" href="../strange^^name">file with ^^</a>: <a class="reference external" href="../strange^^name">../strange^^name</a> </li> <li>Unbalanced braces, { or }, will fail (both with href and url): <pre class="literal-block">`file with { <../strange{name>`__ `<../strange{name>`__</pre> </li> </ul> Currently, a warning is written to the error output stream. For correct printing, we can <ul> <li>use the href command with "normal" escaped name argument, or</li> <li>define a url-command in the preamble <pre class="literal-block">\urldef{\fragileURLi}\nolinkurl{myself%node@gateway.net}</pre> </li> </ul> but need to find a way to insert it as href argument. The following fails: <pre class="literal-block">\href{https://www.w3.org/XML/Schema^^dev}{\fragileURLi}</pre> Use %-replacement like <a class="reference external" href="http://nowhere/url_with%28parens%29">http://nowhere/url_with%28parens%29</a> ? -> does not work for file paths (with pdflatex and xpdf). </section> <section id="add-stylesheet-option"> <h4><a class="toc-backref" href="#toc-entry-44" role="doc-backlink">add-stylesheet option</a><a class="self-link" title="link to this section" href="#add-stylesheet-option"></a></h4> From <a class="reference external" href="http://article.gmane.org/gmane.text.docutils.devel/3429/">http://article.gmane.org/gmane.text.docutils.devel/3429/</a> The problem is that since we have a default value, we have to differentiate between adding another stylesheet and replacing the default. I suggest that the existing --stylesheet & --stylesheet-path options keep their semantics to replace the existing settings. We could introduce new --add-stylesheet & --add-stylesheet-path options, which accumulate; further --stylesheet/--stylesheet-path options would clear these lists. The stylesheet or stylesheet_path setting (only one may be set), plus the added_stylesheets and added_stylesheet_paths settings, describe the combined styles. For example, this run will have only one custom stylesheet: <blockquote> rstpep2html.py --stylesheet-path custom.css ... </blockquote> This run will use the default stylesheet, and the custom one: <blockquote> rstpep2html.py --add-stylesheet-path custom.css ... </blockquote> This run will use the default stylesheet, a custom local stylesheet, and an external stylesheet: <blockquote> <dl class="simple"> <dt>rstpep2html.py --add-stylesheet-path custom.css </dt> <dd>--add-stylesheet <a class="reference external" href="https://www.example.org/external.css">https://www.example.org/external.css</a> ... </dd> </dl> </blockquote> This run will use only the second custom stylesheet: <blockquote> <dl class="simple"> <dt>rstpep2html.py --add-stylesheet-path custom.css </dt> <dd>--stylesheet-path second.css ... </dd> </dl> </blockquote> </section> </section> </section> <section id="front-end-tools"> <h2><a class="toc-backref" href="#toc-entry-45" role="doc-backlink">Front-End Tools</a><a class="self-link" title="link to this section" href="#front-end-tools"></a></h2> <ul> <li>Parameterize help text & defaults somehow? Perhaps a callback? Or initialize settings_spec in __init__ or init_options?</li> <li>Disable common options that don't apply? (This should now be easier with frontend.filter_settings_spec.)</li> <li>Add --section-numbering command line option. The "sectnum" directive should override the --no-section-numbering command line option then.</li> <li>Implement the following suggestions from clig.dev? <blockquote> Display output on success, but keep it brief. provide a --quiet option to suppress all non-essential output. Consider chaining several args as input and use --output (or redirection) for output. —<a class="reference external" href="https://clig.dev/#help">https://clig.dev/#help</a> </blockquote> </li> </ul>  </section> </main> <footer> <a class="reference external" href="todo.rst">View document source</a>. Generated on: 2024-08-15 08:45 UTC. Generated by <a class="reference external" href="https://docutils.sourceforge.io/">Docutils</a> from <a class="reference external" href="https://docutils.sourceforge.io/rst.html">reStructuredText</a> source. </footer> </body> </html>