| Server IP : 82.148.16.210 / Your IP : 216.73.216.19 Web Server : nginx/1.29.5 System : Linux mail.sarafai.ru 6.1.0-43-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.162-1 (2026-02-08) x86_64 User : root ( 0) PHP Version : 7.4.33 Disable Function : pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wifcontinued,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_get_handler,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,pcntl_async_signals,pcntl_unshare, MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : OFF Directory : /proc/746/root/usr/share/doc/python3-docutils/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> <title>Docutils Front-End Tools</title> <meta name="author" content="David Goodger" /> <meta name="date" content="2022-06-20" /> <meta name="copyright" content="This document has been placed in the public domain." /> <link rel="stylesheet" href="../../css/html4css1.css" type="text/css" /> </head> <body> <div class="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> <hr class="header"/> </div> <div class="document" id="docutils-front-end-tools"> <h1 class="title">Docutils Front-End Tools</h1> <table class="docinfo" frame="void" rules="none"> <col class="docinfo-name" /> <col class="docinfo-content" /> <tbody valign="top"> <tr><th class="docinfo-name">Author:</th> <td>David Goodger</td></tr> <tr><th class="docinfo-name">Contact:</th> <td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr> <tr><th class="docinfo-name">Revision:</th> <td>9082</td></tr> <tr><th class="docinfo-name">Date:</th> <td>2022-06-20</td></tr> <tr><th class="docinfo-name">Copyright:</th> <td>This document has been placed in the public domain.</td></tr> </tbody> </table> <!-- Minimal menu bar for inclusion in documentation sources in ``docutils/docs/*/`` sub-diretories. Attention: this is not a standalone document. --> <div class="contents topic" id="contents"> <p class="topic-title">Contents</p> <ul class="simple"> <li><a class="reference internal" href="#introduction" id="toc-entry-1">Introduction</a><ul> <li><a class="reference internal" href="#getting-help" id="toc-entry-2">Getting Help</a></li> </ul> </li> <li><a class="reference internal" href="#the-tools" id="toc-entry-3">The Tools</a><ul> <li><a class="reference internal" href="#generic-command-line-front-end" id="toc-entry-4">Generic Command Line Front End</a></li> <li><a class="reference internal" href="#html-generating-tools" id="toc-entry-5">HTML-Generating Tools</a><ul> <li><a class="reference internal" href="#buildhtml-py" id="toc-entry-6">buildhtml.py</a></li> <li><a class="reference internal" href="#rst2html-py" id="toc-entry-7">rst2html.py</a></li> <li><a class="reference internal" href="#rst2html4-py" id="toc-entry-8">rst2html4.py</a><ul> <li><a class="reference internal" href="#stylesheets" id="toc-entry-9">Stylesheets</a></li> </ul> </li> <li><a class="reference internal" href="#rst2html5-py" id="toc-entry-10">rst2html5.py</a></li> <li><a class="reference internal" href="#rstpep2html-py" id="toc-entry-11">rstpep2html.py</a></li> <li><a class="reference internal" href="#rst2s5-py" id="toc-entry-12">rst2s5.py</a><ul> <li><a class="reference internal" href="#themes" id="toc-entry-13">Themes</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#latex-generating-tools" id="toc-entry-14">LaTeX-Generating Tools</a><ul> <li><a class="reference internal" href="#rst2latex-py" id="toc-entry-15">rst2latex.py</a></li> <li><a class="reference internal" href="#rst2xetex-py" id="toc-entry-16">rst2xetex.py</a></li> </ul> </li> <li><a class="reference internal" href="#man-page-generating-tools" id="toc-entry-17">Man-Page-Generating Tools</a><ul> <li><a class="reference internal" href="#rst2man-py" id="toc-entry-18">rst2man.py</a></li> </ul> </li> <li><a class="reference internal" href="#odf-openoffice-generating-tools" id="toc-entry-19">ODF/OpenOffice-Generating Tools</a><ul> <li><a class="reference internal" href="#rst2odt-py" id="toc-entry-20">rst2odt.py</a><ul> <li><a class="reference internal" href="#rst2odt-prepstyles-py" id="toc-entry-21">rst2odt_prepstyles.py</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#restructuredtext-generating-tools" id="toc-entry-22">reStructuredText-Generating Tools</a></li> <li><a class="reference internal" href="#xml-generating-tools" id="toc-entry-23">XML-Generating Tools</a><ul> <li><a class="reference internal" href="#rst2xml-py" id="toc-entry-24">rst2xml.py</a></li> </ul> </li> <li><a class="reference internal" href="#testing-debugging-tools" id="toc-entry-25">Testing/Debugging Tools</a><ul> <li><a class="reference internal" href="#rst2pseudoxml-py" id="toc-entry-26">rst2pseudoxml.py</a></li> <li><a class="reference internal" href="#quicktest-py" id="toc-entry-27">quicktest.py</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#customization" id="toc-entry-28">Customization</a><ul> <li><a class="reference internal" href="#command-line-options" id="toc-entry-29">Command-Line Options</a></li> <li><a class="reference internal" href="#configuration-files" id="toc-entry-30">Configuration Files</a></li> </ul> </li> </ul> </div> <div class="section" id="introduction"> <h1><a class="toc-backref" href="#toc-entry-1">Introduction</a></h1> <p>Once the Docutils package is unpacked, you will discover a <tt class="docutils literal">tools/</tt> directory containing several front ends for common Docutils processing. In addition to the <a class="reference internal" href="#generic-command-line-front-end">generic command line front end</a>, Docutils has many small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), a "Parser" (which understands the syntax of the text), and a "Writer" (which knows how to generate a specific data format).</p> <p>Most <a class="footnote-reference" href="#footnote-1" id="footnote-reference-1">[1]</a> front ends have common options and the same command-line usage pattern (see <a class="reference internal" href="#the-tools">the tools</a> below for concrete examples):</p> <pre class="literal-block"> toolname [options] [<source> [<destination>]] </pre> <p>Each tool has a "<tt class="docutils literal"><span class="pre">--help</span></tt>" option which lists the <a class="reference internal" href="#command-line-options">command-line options</a> and arguments it supports. Processing can also be customized with <a class="reference internal" href="#configuration-files">configuration files</a>.</p> <p>The two arguments, "source" and "destination", are optional. If only one argument (source) is specified, the standard output (stdout) is used for the destination. If no arguments are specified, the standard input (stdin) is used for the source.</p> <p>In Debian these tools are installed in the normal system path, without the <tt class="docutils literal">.py</tt> extension, according to Debian policy. <a class="reference internal" href="#buildhtml-py">buildhtml.py</a> is installed as rst-buildhtml.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Docutils front-end tool support is currently under discussion. Tool names, install details and the set of auto-installed tools may change in future Docutils versions.</p> </div> <table class="docutils footnote" frame="void" id="footnote-1" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-1">[1]</a></td><td>The exceptions are <a class="reference internal" href="#buildhtml-py">buildhtml.py</a>, <a class="reference internal" href="#quicktest-py">quicktest.py</a> and <a class="reference internal" href="#rst2odt-prepstyles-py">rst2odt_prepstyles.py</a>.</td></tr> </tbody> </table> <div class="section" id="getting-help"> <h2><a class="toc-backref" href="#toc-entry-2">Getting Help</a></h2> <p>First, try the "<tt class="docutils literal"><span class="pre">--help</span></tt>" option each front-end tool has.</p> <p>Command line options and their corresponding configuration file entries are detailed in <a class="reference external" href="config.html">Docutils Configuration</a>.</p> <p>Users who have questions or need assistance with Docutils or reStructuredText should post a message to the <a class="reference external" href="mailing-lists.html#docutils-users">Docutils-users</a> mailing list.</p> </div> </div> <div class="section" id="the-tools"> <h1><a class="toc-backref" href="#toc-entry-3">The Tools</a></h1> <div class="section" id="generic-command-line-front-end"> <h2><a class="toc-backref" href="#toc-entry-4">Generic Command Line Front End</a></h2> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Readers:</th><td class="field-body">Standalone, PEP</td> </tr> <tr class="field"><th class="field-name">Parsers:</th><td class="field-body">reStructuredText, Markdown (requires 3rd party packages)</td> </tr> <tr class="field"><th class="field-name">Writers:</th><td class="field-body"><a class="reference external" href="html.html#html">html</a>, <a class="reference external" href="html.html#html4css1">html4css1</a>, <a class="reference external" href="html.html#html5">html5</a>, <a class="reference external" href="latex.html">latex</a>, <a class="reference external" href="manpage.html">manpage</a>, <a class="reference external" href="odt.html">odt</a>, <a class="reference external" href="html.html#pep-html">pep_html</a>, <a class="reference internal" href="#pseudo-xml">pseudo-xml</a>, <a class="reference external" href="html.html#s5-html">s5_html</a>, <a class="reference internal" href="#xelatex">xelatex</a>, <a class="reference internal" href="#xml">xml</a>,</td> </tr> <tr class="field"><th class="field-name"><a class="reference external" href="config.html#configuration-file-sections-entries">Config</a>:</th><td class="field-body">See <a class="reference external" href="config.html#docutils-application">[docutils application]</a></td> </tr> </tbody> </table> <p>The generic front end allows combining "reader", "parser", and "writer" components from the Docutils package or 3rd party plug-ins.</p> <p>Since Docutils 0.19, it can be called by Python's <tt class="docutils literal"><span class="pre">-m</span></tt> option, the <tt class="docutils literal">docutils</tt> script installed in the binary PATH, or the <tt class="docutils literal"><span class="pre">docutils-cli.py</span></tt> script in the <tt class="docutils literal">tools/</tt> directory.</p> <p>For example, to process a <a class="reference external" href="https://www.markdownguide.org/">Markdown</a> file "<tt class="docutils literal">test.md</tt>" into <a class="reference internal" href="#pseudo-xml">Pseudo-XML</a></p> <pre class="literal-block"> python3 -m docutils --parser=markdown --writer=pseudoxml\ test.md test.txt </pre> <p>Use the "--help" option together with the component-selection options to get the correct list of supported command-line options. Example:</p> <pre class="literal-block"> docutils --parser=markdown --writer=xml --help </pre> </div> <div class="section" id="html-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-5">HTML-Generating Tools</a></h2> <div class="section" id="buildhtml-py"> <h3><a class="toc-backref" href="#toc-entry-6">buildhtml.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Readers:</th><td class="field-body">Standalone, PEP</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writers:</th><td class="field-body"><a class="reference external" href="html.html#html">html</a>, <a class="reference external" href="html.html#html5">html5</a>, <a class="reference external" href="html.html#pep-html">pep_html</a></td> </tr> <tr class="field"><th class="field-name"><a class="reference external" href="config.html#configuration-file-sections-entries">Config</a>:</th><td class="field-body"><a class="reference external" href="config.html#buildhtml-application">[buildhtml application]</a></td> </tr> </tbody> </table> <p>In Debian this tool is installed under the name rst-buildhtml.</p> <p>Use <tt class="docutils literal">buildhtml.py</tt> to generate <tt class="docutils literal">*.html</tt> from all the <tt class="docutils literal">*.txt</tt> files (including PEPs) in each <directory> given, and their subdirectories too. (Use the <tt class="docutils literal"><span class="pre">--local</span></tt> option to skip subdirectories.)</p> <p>Usage:</p> <pre class="literal-block"> rst-buildhtml [options] [<directory> ...] </pre> <p>After unpacking the Docutils package, the following shell commands will generate HTML for all included documentation:</p> <pre class="literal-block"> cd docutils/tools buildhtml.py .. </pre> <p>For official releases, the directory may be called "docutils-X.Y", where "X.Y" is the release version. Alternatively:</p> <pre class="literal-block"> cd docutils tools/buildhtml.py --config=tools/docutils.conf </pre> <p>The current directory (and all subdirectories) is chosen by default if no directory is named. Some files may generate system messages (docs/user/rst/demo.txt contains intentional errors); use the <tt class="docutils literal"><span class="pre">--quiet</span></tt> option to suppress all warnings. The <tt class="docutils literal"><span class="pre">--config</span></tt> option ensures that the correct settings are in place (a <tt class="docutils literal">docutils.conf</tt> <a class="reference internal" href="#configuration-files">configuration file</a> in the current directory is picked up automatically). Command-line options may be used to override config file settings or replace them altogether.</p> </div> <div class="section" id="rst2html-py"> <h3><a class="toc-backref" href="#toc-entry-7">rst2html.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="html.html#html">html</a></td> </tr> </tbody> </table> <p>In Debian this front end is installed as rst2html.</p> <p><cite>rst2html.py</cite> is the front-end for the default Docutils HTML writer. The default writer may change with the development of HTML, browsers, Docutils, and the web. The current default is <a class="reference external" href="html.html#html4css1">html4css1</a>, it will change to <a class="reference external" href="html.html#html5">html5</a> in Docutils 2.0.</p> <div class="admonition caution"> <p class="first admonition-title">Caution!</p> <p class="last">Use a specific front end like <a class="reference internal" href="#rst2html4-py">rst2html4.py</a> or <a class="reference internal" href="#rst2html5-py">rst2html5.py</a>, if you depend on stability of the generated HTML code (e.g., because you use a custom style sheet or post-processing that may break otherwise).</p> </div> </div> <div class="section" id="rst2html4-py"> <h3><a class="toc-backref" href="#toc-entry-8">rst2html4.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="html.html#html4css1">html4css1</a></td> </tr> </tbody> </table> <p>In Debian this front end is installed as rst2html4.</p> <p>The <tt class="docutils literal">rst2html4.py</tt> front end reads standalone reStructuredText source files and produces <a class="reference external" href="https://www.w3.org/TR/xhtml1/">XHTML 1.0 Transitional</a> output. A CSS stylesheet is required for proper rendering; a simple but complete stylesheet is installed and used by default (see <a class="reference internal" href="#stylesheets">Stylesheets</a> below).</p> <p>For example, to process a reStructuredText file "<tt class="docutils literal">test.txt</tt>" into HTML:</p> <pre class="literal-block"> rst2html test.txt test.html </pre> <p>Now open the "<tt class="docutils literal">test.html</tt>" file in your favorite browser to see the results. To get a footer with a link to the source file, date & time of processing, and links to the Docutils project, add some options:</p> <pre class="literal-block"> rst2html -stg test.txt test.html </pre> <div class="section" id="stylesheets"> <h4><a class="toc-backref" href="#toc-entry-9">Stylesheets</a></h4> <p><tt class="docutils literal">rst2html.py</tt> inserts into the generated HTML a cascading stylesheet (or a link to a stylesheet, when passing the "<tt class="docutils literal"><span class="pre">--link-stylesheet</span></tt>" option). A stylesheet is required for proper rendering. The default stylesheet (<tt class="docutils literal">docutils/writers/html4css1/html4css1.css</tt>, located in the installation directory) is provided for basic use.</p> <p>To use different stylesheet(s), specify the stylesheets' location(s) as comma-separated list with the "<a class="reference external" href="config.html#stylesheet">--stylesheet</a>" or "<a class="reference external" href="config.html#stylesheet-path">--stylesheet-path</a>" options. To experiment with styles, please see the <a class="reference external" href="../howto/html-stylesheets.html">guide to writing HTML (CSS) stylesheets for Docutils</a>.</p> </div> </div> <div class="section" id="rst2html5-py"> <h3><a class="toc-backref" href="#toc-entry-10">rst2html5.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="html.html#html5">html5</a></td> </tr> </tbody> </table> <p>In Debian this front end is installed as rst2html5.</p> <p>The <tt class="docutils literal">rst2html5.py</tt> front end reads standalone reStructuredText source files and produces <a class="reference external" href="https://www.w3.org/TR/html5/">HTML 5</a> output. Correct rendering of elements not directly supported by HTML depends on a CSS style sheet. The provided style sheets <tt class="docutils literal">minimal.css</tt> and <tt class="docutils literal">plain.css</tt> define required and optional styling rules respectively.</p> </div> <div class="section" id="rstpep2html-py"> <h3><a class="toc-backref" href="#toc-entry-11">rstpep2html.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">PEP</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="html.html#pep-html">pep_html</a></td> </tr> </tbody> </table> <p>In Debian this front end is installed as rstpep2html.</p> <p><tt class="docutils literal">rstpep2html.py</tt> reads a new-style PEP (marked up with reStructuredText) and produces <a class="reference external" href="https://www.w3.org/TR/xhtml1/">XHTML 1.0 Transitional</a>. It requires a template file and a stylesheet. By default, it makes use of a "<tt class="docutils literal"><span class="pre">pep-html-template</span></tt>" file and the "<tt class="docutils literal">pep.css</tt>" stylesheet (both in the <tt class="docutils literal">docutils/writers/pep_html/</tt> directory), but these can be overridden by command-line options or configuration files.</p> <p>For example, to process a PEP into HTML:</p> <pre class="literal-block"> cd <path-to-docutils>/docs/peps rstpep2html pep-0287.txt pep-0287.html </pre> </div> <div class="section" id="rst2s5-py"> <h3><a class="toc-backref" href="#toc-entry-12">rst2s5.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="html.html#s5-html">s5_html</a></td> </tr> </tbody> </table> <p>In Debian this is installed as rst2s5.</p> <p>The <tt class="docutils literal">rst2s5.py</tt> front end reads standalone reStructuredText source files and produces (X)HTML output compatible with <a class="reference external" href="http://meyerweb.com/eric/tools/s5/">S5</a>, the "Simple Standards-based Slide Show System" by Eric Meyer. A theme is required for proper rendering; several are distributed with Docutils and others are available; see <a class="reference internal" href="#themes">Themes</a> below.</p> <p>For example, to process a reStructuredText file "<tt class="docutils literal">slides.txt</tt>" into S5/HTML:</p> <pre class="literal-block"> rst2s5 slides.txt slides.html </pre> <p>Now open the "<tt class="docutils literal">slides.html</tt>" file in your favorite browser, switch to full-screen mode, and enjoy the results.</p> <div class="section" id="themes"> <h4><a class="toc-backref" href="#toc-entry-13">Themes</a></h4> <p>Each S5 theme consists of a directory containing several files: stylesheets, JavaScript, and graphics. These are copied into a <tt class="docutils literal"><span class="pre">ui/<theme></span></tt> directory beside the generated HTML. A theme is chosen using the "<tt class="docutils literal"><span class="pre">--theme</span></tt>" option (for themes that come with Docutils) or the "<tt class="docutils literal"><span class="pre">--theme-url</span></tt>" option (for themes anywhere). For example, the "medium-black" theme can be specified as follows:</p> <pre class="literal-block"> rst2s5 --theme medium-black slides.txt slides.html </pre> <p>The theme will be copied to the <tt class="docutils literal"><span class="pre">ui/medium-black</span></tt> directory.</p> <p>Several themes are included with Docutils:</p> <dl class="docutils"> <dt><tt class="docutils literal">default</tt></dt> <dd><p class="first">This is a simplified version of S5's default theme.</p> <table class="last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">black serif text on a white background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 13 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">light blue, bold sans-serif text on a dark blue background; titles are limited to one line</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">small, gray, bold sans-serif text on a dark blue background</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">small-white</span></tt></dt> <dd><p class="first">(Small text on a white background.)</p> <table class="last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">black serif text on a white background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 15 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">black, bold sans-serif text on a white background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">small, dark gray, bold sans-serif text on a white background</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">small-black</span></tt></dt> <dd><table class="first last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">white serif text on a black background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 15 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">white, bold sans-serif text on a black background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">small, light gray, bold sans-serif text on a black background</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">medium-white</span></tt></dt> <dd><table class="first last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">black serif text on a white background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 9 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">black, bold sans-serif text on a white background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">small, dark gray, bold sans-serif text on a white background</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">medium-black</span></tt></dt> <dd><table class="first last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">white serif text on a black background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 9 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">white, bold sans-serif text on a black background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">small, light gray, bold sans-serif text on a black background</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">big-white</span></tt></dt> <dd><table class="first last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">black, bold sans-serif text on a white background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 5 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">black, bold sans-serif text on a white background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">not displayed</td> </tr> </tbody> </table> </dd> <dt><tt class="docutils literal"><span class="pre">big-black</span></tt></dt> <dd><table class="first last docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Main content:</th><td class="field-body">white, bold sans-serif text on a black background</td> </tr> <tr class="field"><th class="field-name">Text capacity:</th><td class="field-body">about 5 lines</td> </tr> <tr class="field"><th class="field-name">Headers:</th><td class="field-body">white, bold sans-serif text on a black background; titles wrap</td> </tr> <tr class="field"><th class="field-name">Footers:</th><td class="field-body">not displayed</td> </tr> </tbody> </table> </dd> </dl> <p>If a theme directory contains a file named <tt class="docutils literal">__base__</tt>, the name of the theme's base theme will be read from it. Files are accumulated from the named theme, any base themes, and the "default" theme (which is the implicit base of all themes).</p> <p>For details, please see <a class="reference external" href="slide-shows.html">Easy Slide Shows With reStructuredText & S5</a>.</p> </div> </div> </div> <div class="section" id="latex-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-14">LaTeX-Generating Tools</a></h2> <div class="section" id="rst2latex-py"> <h3><a class="toc-backref" href="#toc-entry-15">rst2latex.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="latex.html">latex2e</a></td> </tr> </tbody> </table> <p>In Debian this is installed as rst2latex.</p> <p>The <tt class="docutils literal">rst2latex.py</tt> front end reads standalone reStructuredText source files and produces <a class="reference external" href="https://en.wikipedia.org/wiki/LaTeX">LaTeX</a> output. For example, to process a reStructuredText file "<tt class="docutils literal">test.txt</tt>" into LaTeX:</p> <pre class="literal-block"> rst2latex test.txt test.tex </pre> <p>The output file "<tt class="docutils literal">test.tex</tt>" should then be processed with <tt class="docutils literal">latex</tt> or <tt class="docutils literal">pdflatex</tt> to get a document in DVI, PostScript or PDF format for printing or on-screen viewing.</p> <p>For details see <a class="reference external" href="latex.html">Generating LaTeX with Docutils</a>.</p> </div> <div class="section" id="rst2xetex-py"> <h3><a class="toc-backref" href="#toc-entry-16">rst2xetex.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><span class="target" id="xelatex">xelatex</span></td> </tr> </tbody> </table> <p>On Debian this front end is installed as rst2xetex.</p> <p>The <tt class="docutils literal">rst2xetex.py</tt> front end reads standalone reStructuredText source files and produces <cite>LaTeX</cite> output for processing with Unicode-aware TeX engines (<a class="reference external" href="https://en.wikipedia.org/wiki/LuaTeX">LuaTeX</a> or <a class="reference external" href="https://en.wikipedia.org/wiki/XeTeX">XeTeX</a>). For example, to process a reStructuredText file "<tt class="docutils literal">test.txt</tt>" into LaTeX:</p> <pre class="literal-block"> rst2xetex.py test.txt test.tex </pre> <p>The output file "<tt class="docutils literal">test.tex</tt>" should then be processed with <tt class="docutils literal">xelatex</tt> or <tt class="docutils literal">lualatex</tt> to get a document in PDF format for printing or on-screen viewing.</p> <p>For details see <a class="reference external" href="latex.html">Generating LaTeX with Docutils</a>.</p> </div> </div> <div class="section" id="man-page-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-17">Man-Page-Generating Tools</a></h2> <div class="section" id="rst2man-py"> <h3><a class="toc-backref" href="#toc-entry-18">rst2man.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="manpage.html">manpage</a></td> </tr> </tbody> </table> <p>The <tt class="docutils literal">rst2man.py</tt> front end reads standalone reStructuredText source files and produces <a class="reference external" href="https://troff.org/">troff</a> sources for Unix man pages.</p> </div> </div> <div class="section" id="odf-openoffice-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-19">ODF/OpenOffice-Generating Tools</a></h2> <div class="section" id="rst2odt-py"> <h3><a class="toc-backref" href="#toc-entry-20">rst2odt.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><a class="reference external" href="odt.html">odt</a></td> </tr> </tbody> </table> <p>In Debian this front end is installed as rst2odt.</p> <p>The <tt class="docutils literal">rst2odt.py</tt> front end reads standalone reStructuredText source files and produces ODF/.odt files that can be read, edited, printed, etc with <a class="reference external" href="https://www.openoffice.org/">OpenOffice</a> <tt class="docutils literal">oowriter</tt> or <a class="reference external" href="https://www.libreoffice.org/">LibreOffice</a> <tt class="docutils literal">lowriter</tt>. A stylesheet file is required. A stylesheet file is an OpenOffice .odt file containing definitions of the styles required for <tt class="docutils literal">rst2odt.py</tt>. For details, see <a class="reference external" href="odt.html">Odt Writer for Docutils</a>.</p> <div class="section" id="rst2odt-prepstyles-py"> <h4><a class="toc-backref" href="#toc-entry-21">rst2odt_prepstyles.py</a></h4> <p>A helper tool to fix a word-processor-generated STYLE_FILE.odt for odtwriter use:</p> <pre class="literal-block"> rst2odt_prepstyles STYLE_FILE.odt </pre> <p>See <a class="reference external" href="odt.html#page-size">Odt Writer for Docutils</a> for details.</p> </div> </div> </div> <div class="section" id="restructuredtext-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-22">reStructuredText-Generating Tools</a></h2> <p>Currently, there is no reStructuredText writer in Docutils and therefore an <tt class="docutils literal">rst2rst.py</tt> tool is still missing.</p> <p>To generate reStructuredText documents with Docutils, you can use the XML (Docutils native) writer and the <a class="reference external" href="../../../sandbox/xml2rst">xml2rst</a> processor.</p> </div> <div class="section" id="xml-generating-tools"> <h2><a class="toc-backref" href="#toc-entry-23">XML-Generating Tools</a></h2> <div class="section" id="rst2xml-py"> <h3><a class="toc-backref" href="#toc-entry-24">rst2xml.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><span class="target" id="xml">XML</span> (Docutils native)</td> </tr> </tbody> </table> <p>In Debian this is installed as rst2xml.</p> <p>The <tt class="docutils literal">rst2xml.py</tt> front end produces Docutils-native XML output. This can be transformed with standard XML tools such as XSLT processors into arbitrary final forms. An example is the <a class="reference external" href="../../../sandbox/xml2rst">xml2rst</a> processor in the Docutils sandbox.</p> </div> </div> <div class="section" id="testing-debugging-tools"> <h2><a class="toc-backref" href="#toc-entry-25">Testing/Debugging Tools</a></h2> <div class="section" id="rst2pseudoxml-py"> <h3><a class="toc-backref" href="#toc-entry-26">rst2pseudoxml.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">Standalone</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body"><span class="target" id="pseudo-xml">Pseudo-XML</span></td> </tr> </tbody> </table> <p>In Debian this is installed as rst2pseudoxml.</p> <p><tt class="docutils literal">rst2pseudoxml.py</tt> is used for debugging the Docutils "Reader to Transform to Writer" pipeline. It produces a compact pretty-printed "pseudo-XML", where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given.</p> </div> <div class="section" id="quicktest-py"> <h3><a class="toc-backref" href="#toc-entry-27">quicktest.py</a></h3> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field"><th class="field-name">Reader:</th><td class="field-body">N/A</td> </tr> <tr class="field"><th class="field-name">Parser:</th><td class="field-body">reStructuredText</td> </tr> <tr class="field"><th class="field-name">Writer:</th><td class="field-body">N/A</td> </tr> </tbody> </table> <p>This tool is not currently installed by the Debian package; <tt class="docutils literal"><span class="pre">apt-get</span> source <span class="pre">python-docutils</span></tt> if you need it.</p> <p>The <tt class="docutils literal">quicktest.py</tt> tool is used for testing the reStructuredText parser. It does not use a Docutils Reader or Writer or the standard Docutils command-line options. Rather, it does its own I/O and calls the parser directly. No transforms are applied to the parsed document. Possible output forms output include:</p> <table class="docutils option-list" frame="void" rules="none"> <col class="option" /> <col class="description" /> <tbody valign="top"> <tr><td class="option-group"> <kbd><span class="option">--pretty</span></kbd></td> <td>Pretty-printed pseudo-XML (default)</td></tr> <tr><td class="option-group"> <kbd><span class="option">--test</span></kbd></td> <td>Test data (Python list of input and pseudo-XML output strings; useful for creating new test cases)</td></tr> <tr><td class="option-group"> <kbd><span class="option">--xml</span></kbd></td> <td>Pretty-printed native XML</td></tr> <tr><td class="option-group"> <kbd><span class="option">--rawxml</span></kbd></td> <td>Raw native XML (with or without a stylesheet reference)</td></tr> <tr><td class="option-group"> <kbd><span class="option">--help</span></kbd></td> <td>Usage hint and complete list of supported options.</td></tr> </tbody> </table> <div class="admonition caution"> <p class="first admonition-title">Caution!</p> <p class="last"><tt class="docutils literal">quicktest.py</tt> uses Python's default encoding. Input and output encoding depend on UTF-8 mode, Python version, locale setting, and operating system (cf. <a class="reference external" href="https://peps.python.org/pep-0540">PEP 540</a>, <a class="reference external" href="https://peps.python.org/pep-0538">PEP 538</a>, <a class="reference external" href="https://peps.python.org/pep-0597">PEP 597</a>, and <a class="reference external" href="https://peps.python.org/pep-0686">PEP 686</a>).</p> </div> </div> </div> </div> <div class="section" id="customization"> <h1><a class="toc-backref" href="#toc-entry-28">Customization</a></h1> <p>Most front-end tools support the options/settings from the generic <a class="reference external" href="config.html#configuration-file-sections-entries">configuration file sections</a> plus the sections of their components (reader, writer, parser). <a class="footnote-reference" href="#footnote-2" id="footnote-reference-2">[2]</a> Some front-end tools also add application-specific settings.</p> <table class="docutils footnote" frame="void" id="footnote-2" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#footnote-reference-2">[2]</a></td><td>The exceptions are <a class="reference internal" href="#quicktest-py">quicktest.py</a> and <a class="reference internal" href="#rst2odt-prepstyles-py">rst2odt_prepstyles.py</a>.</td></tr> </tbody> </table> <div class="section" id="command-line-options"> <h2><a class="toc-backref" href="#toc-entry-29">Command-Line Options</a></h2> <p>Command-line options are intended for one-off customization. They take priority over configuration file settings.</p> <p>Use the "--help" option on each of the front ends to list the command-line options it supports.</p> </div> <div class="section" id="configuration-files"> <h2><a class="toc-backref" href="#toc-entry-30">Configuration Files</a></h2> <p>Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool.</p> <p>Command-line options and their corresponding configuration file entry names are listed in the <a class="reference external" href="config.html">Docutils Configuration</a> document.</p> <!-- Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End: --> </div> </div> </div> </body> </html>