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" /> <meta name="dcterms.date" content="2024-08-15" /> <meta name="dcterms.rights" content="This document has been placed in the public domain." /> <title>Docutils Front-End Tools</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-front-end-tools"> <h1 class="title">Docutils Front-End Tools</h1> <dl class="docinfo"> <dt class="author">Author:</dt> <dd class="author">David Goodger</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="revision">Revision:</dt> <dd class="revision">9906</dd> <dt class="date">Date:</dt> <dd class="date">2024-08-15</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="#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> <ul> <li><a class="reference internal" href="#docutils" id="toc-entry-5">docutils</a></li> </ul> </li> <li><a class="reference internal" href="#html-generating-tools" id="toc-entry-6">HTML-Generating Tools</a> <ul> <li><a class="reference internal" href="#rst2html" id="toc-entry-7">rst2html</a></li> <li><a class="reference internal" href="#rst2html4" id="toc-entry-8">rst2html4</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" id="toc-entry-10">rst2html5</a></li> <li><a class="reference internal" href="#rst2s5" id="toc-entry-11">rst2s5</a> <ul> <li><a class="reference internal" href="#themes" id="toc-entry-12">Themes</a></li> </ul> </li> <li><a class="reference internal" href="#buildhtml-py" id="toc-entry-13">buildhtml.py</a></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" id="toc-entry-15">rst2latex</a></li> <li><a class="reference internal" href="#rst2xetex" id="toc-entry-16">rst2xetex</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" id="toc-entry-18">rst2man</a></li> </ul> </li> <li><a class="reference internal" href="#opendocument-generating-tools" id="toc-entry-19">OpenDocument-Generating Tools</a> <ul> <li><a class="reference internal" href="#rst2odt" id="toc-entry-20">rst2odt</a></li> </ul> </li> <li><a class="reference internal" href="#restructuredtext-generating-tools" id="toc-entry-21">reStructuredText-Generating Tools</a></li> <li><a class="reference internal" href="#xml-generating-tools" id="toc-entry-22">XML-Generating Tools</a> <ul> <li><a class="reference internal" href="#rst2xml" id="toc-entry-23">rst2xml</a></li> </ul> </li> <li><a class="reference internal" href="#testing-debugging-tools" id="toc-entry-24">Testing/Debugging Tools</a> <ul> <li><a class="reference internal" href="#rst2pseudoxml" id="toc-entry-25">rst2pseudoxml</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#customization" id="toc-entry-26">Customization</a> <ul> <li><a class="reference internal" href="#command-line-options" id="toc-entry-27">Command-Line Options</a></li> <li><a class="reference internal" href="#configuration-files" id="toc-entry-28">Configuration Files</a></li> </ul> </li> </ul> </nav> <section id="introduction"> <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Introduction</a><a class="self-link" title="link to this section" href="#introduction"></a></h2> In addition to the generic "<a class="reference internal" href="#docutils">docutils</a>" application, Docutils installs a set of small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), "Parser" (which understands the syntax of the text), and "Writer" (which knows how to generate a specific data format). <aside class="admonition note"> Note Docutils front-end tool names, install details and the set of auto-installed tools changed in Docutils聽0.21 (see the <a class="reference external" href="../../RELEASE-NOTES.html">RELEASE-NOTES</a>). </aside> Most <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref">[1]</a> front-end tools have common options and the same command-line usage pattern: <pre class="literal-block"><toolname> [options] [<source> [<destination>]]</pre> See <a class="reference internal" href="#the-tools">the tools</a> below for concrete examples. Each tool has a "--help" 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>. 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. <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>] The exception is <a class="reference internal" href="#buildhtml-py">buildhtml.py</a>. </aside> </aside> <aside class="admonition note"> Note The command line usage pattern will change over the next releases. See <a class="reference external" href="../../RELEASE-NOTES.html#future-changes">Future changes</a> in the RELEASE-NOTES. </aside> <section id="getting-help"> <h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Getting Help</a><a class="self-link" title="link to this section" href="#getting-help"></a></h3> First, try the "--help" option each front-end tool has. Command line options and their corresponding configuration file entries are detailed in <a class="reference external" href="config.html">Docutils Configuration</a>. 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. </section> </section> <section id="the-tools"> <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">The Tools</a><a class="self-link" title="link to this section" href="#the-tools"></a></h2> <section id="generic-command-line-front-end"> <h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink">Generic Command Line Front End</a><a class="self-link" title="link to this section" href="#generic-command-line-front-end"></a></h3> <section id="docutils"> <h4><a class="toc-backref" href="#toc-entry-5" role="doc-backlink">docutils</a><a class="self-link" title="link to this section" href="#docutils"></a></h4> <dl class="field-list simple"> <dt>CLI name:</dt> <dd>docutils </dd> <dt>Readers:</dt> <dd>Standalone (default), PEP </dd> <dt>Parsers:</dt> <dd>reStructuredText (default), Markdown (requires 3rd party packages) </dd> <dt>Writers:</dt> <dd><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> (default), <a class="reference external" href="latex.html">latex2e</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>, </dd> <dt><a class="reference external" href="config.html#configuration-file-sections-entries">Config</a>:</dt> <dd><a class="reference external" href="config.html#docutils-application">[docutils application]</a> </dd> </dl> Since Docutils 0.19, you can start the generic front end like: <pre class="literal-block">docutils test.rst > test.html</pre> Alternatively, use Python's -m option, or the docutils-cli.py script in the tools/ directory. The generic front end allows combining "reader", "parser", and "writer" components from the Docutils package or 3rd party plug-ins. For example, to process a <a class="reference external" href="https://www.markdownguide.org/">Markdown</a> file "test.md" into <a class="reference internal" href="#pseudo-xml">Pseudo-XML</a>: <pre class="literal-block">docutils --parser=markdown --writer=pseudoxml test.md > test.rst</pre> Another example is converting a reStructuredText <a class="reference external" href="https://peps.python.org">PEP</a> source into a HTML preview <a class="brackets" href="#footnote-2" id="footnote-reference-2" role="doc-noteref">[2]</a>: <pre class="literal-block">docutils --reader=pep --writer=pep_html pep-0287.rst > pep-0287.html</pre> The <a class="reference external" href="html.html#pep-html">pep_html</a> writer makes use of a "pep-html-template" file and the "pep.css" stylesheet (both in the docutils/writers/pep_html/ directory), but these can be overridden by command-line options or configuration files. Use the "--help" option together with the component-selection options to get the correct list of supported command-line options. Example: <pre class="literal-block">docutils --parser=markdown --writer=xml --help</pre> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="footnote-2" role="doc-footnote"> [<a role="doc-backlink" href="#footnote-reference-2">2</a>] The rendering of published PEPs is done by a Sphinx-based build system (see <a class="reference external" href="https://peps.python.org/pep-0676">PEP 676</a>). </aside> </aside> </section> </section> <section id="html-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink">HTML-Generating Tools</a><a class="self-link" title="link to this section" href="#html-generating-tools"></a></h3> <section id="rst2html"> <h4><a class="toc-backref" href="#toc-entry-7" role="doc-backlink">rst2html</a><a class="self-link" title="link to this section" href="#rst2html"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="html.html#html">html</a> </dd> </dl> rst2html 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. <aside class="admonition caution"> Caution! Use a specific front end like <a class="reference internal" href="#rst2html4">rst2html4</a> or <a class="reference internal" href="#rst2html5">rst2html5</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). </aside> </section> <section id="rst2html4"> <h4><a class="toc-backref" href="#toc-entry-8" role="doc-backlink">rst2html4</a><a class="self-link" title="link to this section" href="#rst2html4"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="html.html#html4css1">html4css1</a> </dd> </dl> The rst2html4 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). For example, to process a reStructuredText file "test.rst" into HTML: <pre class="literal-block">rst2html test.rst > test.html</pre> Now open the "test.html" file in your favourite 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: <pre class="literal-block">rst2html --source-link --time --generator test.rst > test.html</pre> <section id="stylesheets"> <h5><a class="toc-backref" href="#toc-entry-9" role="doc-backlink">Stylesheets</a><a class="self-link" title="link to this section" href="#stylesheets"></a></h5> rst2html inserts into the generated HTML a cascading stylesheet (or a link to a stylesheet, when passing the "--link-stylesheet" option). A stylesheet is required for proper rendering. The default stylesheet (docutils/writers/html4css1/html4css1.css, located in the installation directory) is provided for basic use. 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>. </section> </section> <section id="rst2html5"> <h4><a class="toc-backref" href="#toc-entry-10" role="doc-backlink">rst2html5</a><a class="self-link" title="link to this section" href="#rst2html5"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="html.html#html5">html5</a> </dd> </dl> The rst2html5 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 minimal.css and plain.css define required and optional styling rules respectively. </section> <section id="rst2s5"> <h4><a class="toc-backref" href="#toc-entry-11" role="doc-backlink">rst2s5</a><a class="self-link" title="link to this section" href="#rst2s5"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="html.html#s5-html">s5_html</a> </dd> </dl> The rst2s5 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. For example, to process a reStructuredText file "slides.rst" into S5/HTML: <pre class="literal-block">rst2s5 slides.rst --output=slides.html</pre> Now open the "slides.html" file in your favourite browser, switch to full-screen mode, and enjoy the results. <section id="themes"> <h5><a class="toc-backref" href="#toc-entry-12" role="doc-backlink">Themes</a><a class="self-link" title="link to this section" href="#themes"></a></h5> Each S5 theme consists of a directory containing several files: stylesheets, JavaScript, and graphics. These are copied into a ui/<theme> directory beside the generated HTML. <a class="brackets" href="#copy-theme" id="footnote-reference-3" role="doc-noteref">[3]</a> A theme is chosen using the "--theme" option (for themes that come with Docutils) or the "--theme-url" option (for themes anywhere). For example, the "medium-black" theme can be specified as follows: <pre class="literal-block">rst2s5 --theme medium-black slides.rst --output=slides.html</pre> The theme will be copied <a class="brackets" href="#copy-theme" id="footnote-reference-4" role="doc-noteref">[3]</a> to the ui/medium-black directory. Several themes are included with Docutils: <dl class="simple"> <dt>default</dt> <dd>This is a simplified version of S5's default theme. <dl class="field-list simple"> <dt>Main content:</dt> <dd>black serif text on a white background </dd> <dt>Text capacity:</dt> <dd>about 13 lines </dd> <dt>Headers:</dt> <dd>light blue, bold sans-serif text on a dark blue background; titles are limited to one line </dd> <dt>Footers:</dt> <dd>small, gray, bold sans-serif text on a dark blue background </dd> </dl> </dd> <dt>small-white</dt> <dd>(Small text on a white background.) <dl class="field-list simple"> <dt>Main content:</dt> <dd>black serif text on a white background </dd> <dt>Text capacity:</dt> <dd>about 15 lines </dd> <dt>Headers:</dt> <dd>black, bold sans-serif text on a white background; titles wrap </dd> <dt>Footers:</dt> <dd>small, dark gray, bold sans-serif text on a white background </dd> </dl> </dd> <dt>small-black</dt> <dd><dl class="field-list simple"> <dt>Main content:</dt> <dd>white serif text on a black background </dd> <dt>Text capacity:</dt> <dd>about 15 lines </dd> <dt>Headers:</dt> <dd>white, bold sans-serif text on a black background; titles wrap </dd> <dt>Footers:</dt> <dd>small, light gray, bold sans-serif text on a black background </dd> </dl> </dd> <dt>medium-white</dt> <dd><dl class="field-list simple"> <dt>Main content:</dt> <dd>black serif text on a white background </dd> <dt>Text capacity:</dt> <dd>about 9 lines </dd> <dt>Headers:</dt> <dd>black, bold sans-serif text on a white background; titles wrap </dd> <dt>Footers:</dt> <dd>small, dark gray, bold sans-serif text on a white background </dd> </dl> </dd> <dt>medium-black</dt> <dd><dl class="field-list simple"> <dt>Main content:</dt> <dd>white serif text on a black background </dd> <dt>Text capacity:</dt> <dd>about 9 lines </dd> <dt>Headers:</dt> <dd>white, bold sans-serif text on a black background; titles wrap </dd> <dt>Footers:</dt> <dd>small, light gray, bold sans-serif text on a black background </dd> </dl> </dd> <dt>big-white</dt> <dd><dl class="field-list simple"> <dt>Main content:</dt> <dd>black, bold sans-serif text on a white background </dd> <dt>Text capacity:</dt> <dd>about 5 lines </dd> <dt>Headers:</dt> <dd>black, bold sans-serif text on a white background; titles wrap </dd> <dt>Footers:</dt> <dd>not displayed </dd> </dl> </dd> <dt>big-black</dt> <dd><dl class="field-list simple"> <dt>Main content:</dt> <dd>white, bold sans-serif text on a black background </dd> <dt>Text capacity:</dt> <dd>about 5 lines </dd> <dt>Headers:</dt> <dd>white, bold sans-serif text on a black background; titles wrap </dd> <dt>Footers:</dt> <dd>not displayed </dd> </dl> </dd> </dl> If a theme directory contains a file named __base__, 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). For details, please see <a class="reference external" href="slide-shows.html">Easy Slide Shows With reStructuredText & S5</a>. <aside class="footnote-list brackets"> <aside class="footnote brackets" id="copy-theme" role="doc-footnote"> [3] (<a role="doc-backlink" href="#footnote-reference-3">1</a>,<a role="doc-backlink" href="#footnote-reference-4">2</a>) Theme files can only be copied by Docutils, if the <a class="reference external" href="config.html#output">output</a> destination path is specified. </aside> </aside> </section> </section> <section id="buildhtml-py"> <h4><a class="toc-backref" href="#toc-entry-13" role="doc-backlink">buildhtml.py</a><a class="self-link" title="link to this section" href="#buildhtml-py"></a></h4> <dl class="field-list simple"> <dt>Readers:</dt> <dd>Standalone, PEP </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writers:</dt> <dd><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> </dd> <dt><a class="reference external" href="config.html#configuration-file-sections-entries">Config</a>:</dt> <dd><a class="reference external" href="config.html#buildhtml-application">[buildhtml application]</a> </dd> </dl> The buildhtml.py script can be found in the /tools directory of the "docutils" source. It is not included in binary packages. <a class="brackets" href="#footnote-3" id="footnote-reference-5" role="doc-noteref">[4]</a> Usage: <pre class="literal-block">buildhtml.py [options] [<directory> ...]</pre> Use buildhtml.py to generate *.html from reStructuredText source files in each <directory> given, and their subdirectories too. The current directory is chosen by default if no directory is specified. Use the --local option to skip all subdirectories. See <a class="reference external" href="config.html#buildhtml-application">[buildhtml application]</a> in <a class="reference external" href="config.html">Docutils Configuration</a> for more specific selection options. After unpacking the Docutils source package, you can cd into its root directory (docutils-X.Y/ where "X.Y" is the release version, for official releases) and generate HTML pages for all included documentation files with: <pre class="literal-block">tools/buildhtml.py</pre> Some files may generate system messages (docs/user/rst/demo.rst contains intentional errors); use the --quiet option to suppress all warnings. <aside class="footnote-list brackets"> <aside class="footnote brackets" id="footnote-3" role="doc-footnote"> [<a role="doc-backlink" href="#footnote-reference-5">4</a>] The Debian package "python3-docutils" includes the script under the name rst-buildhtml. </aside> </aside> </section> </section> <section id="latex-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink">LaTeX-Generating Tools</a><a class="self-link" title="link to this section" href="#latex-generating-tools"></a></h3> <section id="rst2latex"> <h4><a class="toc-backref" href="#toc-entry-15" role="doc-backlink">rst2latex</a><a class="self-link" title="link to this section" href="#rst2latex"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="latex.html">latex2e</a> </dd> </dl> The rst2latex 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 "test.rst" into LaTeX: <pre class="literal-block">rst2latex test.rst > test.tex</pre> The output file "test.tex" should then be processed with latex or pdflatex to get a document in DVI, PostScript or PDF format for printing or on-screen viewing. For details see <a class="reference external" href="latex.html">Generating LaTeX with Docutils</a>. </section> <section id="rst2xetex"> <h4><a class="toc-backref" href="#toc-entry-16" role="doc-backlink">rst2xetex</a><a class="self-link" title="link to this section" href="#rst2xetex"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd>xelatex </dd> </dl> The rst2xetex 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 "test.rst" into LaTeX: <pre class="literal-block">rst2xetex test.rst > test.tex</pre> The output file "test.tex" should then be processed with xelatex or lualatex to get a document in PDF format for printing or on-screen viewing. For details see <a class="reference external" href="latex.html">Generating LaTeX with Docutils</a>. </section> </section> <section id="man-page-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-17" role="doc-backlink">Man-Page-Generating Tools</a><a class="self-link" title="link to this section" href="#man-page-generating-tools"></a></h3> <section id="rst2man"> <h4><a class="toc-backref" href="#toc-entry-18" role="doc-backlink">rst2man</a><a class="self-link" title="link to this section" href="#rst2man"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="manpage.html">manpage</a> </dd> </dl> The rst2man front end reads standalone reStructuredText source files and produces <a class="reference external" href="https://troff.org/">troff</a> sources for Unix man pages. </section> </section> <section id="opendocument-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink">OpenDocument-Generating Tools</a><a class="self-link" title="link to this section" href="#opendocument-generating-tools"></a></h3> <section id="rst2odt"> <h4><a class="toc-backref" href="#toc-entry-20" role="doc-backlink">rst2odt</a><a class="self-link" title="link to this section" href="#rst2odt"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd><a class="reference external" href="odt.html">odt</a> </dd> </dl> The rst2odt 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> oowriter or <a class="reference external" href="https://www.libreoffice.org/">LibreOffice</a> lowriter. A stylesheet file is required. A stylesheet file is an OpenOffice .odt file containing definitions of the styles required for rst2odt. For details, see <a class="reference external" href="odt.html">Odt Writer for Docutils</a>. </section> </section> <section id="restructuredtext-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-21" role="doc-backlink">reStructuredText-Generating Tools</a><a class="self-link" title="link to this section" href="#restructuredtext-generating-tools"></a></h3> Currently, there is no reStructuredText writer in Docutils and therefore an rst2rst tool is still missing. To generate reStructuredText documents with Docutils, you can use the XML (Docutils native) writer and the <a class="reference external" href="http://www.merten-home.de/FreeSoftware/xml2rst/index.html">xml2rst</a> processor. </section> <section id="xml-generating-tools"> <h3><a class="toc-backref" href="#toc-entry-22" role="doc-backlink">XML-Generating Tools</a><a class="self-link" title="link to this section" href="#xml-generating-tools"></a></h3> <section id="rst2xml"> <h4><a class="toc-backref" href="#toc-entry-23" role="doc-backlink">rst2xml</a><a class="self-link" title="link to this section" href="#rst2xml"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd>XML (Docutils native) </dd> </dl> The rst2xml 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="http://www.merten-home.de/FreeSoftware/xml2rst/index.html">xml2rst</a> processor by Stefan Merten. </section> </section> <section id="testing-debugging-tools"> <h3><a class="toc-backref" href="#toc-entry-24" role="doc-backlink">Testing/Debugging Tools</a><a class="self-link" title="link to this section" href="#testing-debugging-tools"></a></h3> <section id="rst2pseudoxml"> <h4><a class="toc-backref" href="#toc-entry-25" role="doc-backlink">rst2pseudoxml</a><a class="self-link" title="link to this section" href="#rst2pseudoxml"></a></h4> <dl class="field-list simple"> <dt>Reader:</dt> <dd>Standalone </dd> <dt>Parser:</dt> <dd>reStructuredText </dd> <dt>Writer:</dt> <dd>Pseudo-XML </dd> </dl> rst2pseudoxml 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. </section> </section> </section> <section id="customization"> <h2><a class="toc-backref" href="#toc-entry-26" role="doc-backlink">Customization</a><a class="self-link" title="link to this section" href="#customization"></a></h2> All 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). Some front-end tools also add application-specific settings. <section id="command-line-options"> <h3><a class="toc-backref" href="#toc-entry-27" role="doc-backlink">Command-Line Options</a><a class="self-link" title="link to this section" href="#command-line-options"></a></h3> Command-line options are intended for one-off customization. They take priority over configuration file settings. Use the --help option on each of the front ends to list the command-line options it supports. </section> <section id="configuration-files"> <h3><a class="toc-backref" href="#toc-entry-28" role="doc-backlink">Configuration Files</a><a class="self-link" title="link to this section" href="#configuration-files"></a></h3> Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool. 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.  </section> </section> </main> <footer> <a class="reference external" href="tools.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>