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>reStructuredText Standard Definition Files</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="restructuredtext-standard-definition-files"> <h1 class="title">reStructuredText Standard Definition Files</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="#substitution-definitions" id="toc-entry-1">Substitution Definitions</a> <ul> <li><a class="reference internal" href="#character-entity-sets" id="toc-entry-2">Character Entity Sets</a></li> </ul> </li> <li><a class="reference internal" href="#s5-html-definitions" id="toc-entry-3">S5/HTML Definitions</a></li> </ul> </nav> This document describes standard definition files, such as sets of substitution definitions and interpreted text roles, that can be included in reStructuredText documents. The <a class="reference external" href="directives.html#include">"include" directive</a> has a special syntax for these standard definition files, angle brackets around the file name: <pre class="literal-block">.. include:: <filename.txt></pre> The individual data files are stored with the Docutils source code in the "docutils" package, in the docutils/parsers/rst/include directory. <section id="substitution-definitions"> <h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink">Substitution Definitions</a><a class="self-link" title="link to this section" href="#substitution-definitions"></a></h2> Many of the standard definition files contain sets of <a class="reference external" href="restructuredtext.html#substitution-definitions">substitution definitions</a>, which can be used in documents via <a class="reference external" href="restructuredtext.html#substitution-references">substitution references</a>. For example, the copyright symbol is defined in isonum.txt as "copy": <pre class="literal-block">.. include:: <isonum.txt> Copyright |copy| 2003 by John Q. Public, all rights reserved.</pre> Individual substitution definitions can also be copied from definition files and pasted into documents. This has two advantages: it removes dependencies, and it saves processing of unused definitions. However, multiple substitution definitions add clutter to the document. Substitution references require separation from the surrounding text with whitespace or punctuation. To use a substitution without intervening whitespace, you can use the disappearing-whitespace escape sequence, backslash-space: <pre class="literal-block">.. include:: <isonum.txt> Copyright |copy| 2003, BogusMegaCorp\ |trade|.</pre> Custom substitution definitions may use the <a class="reference external" href="directives.html#unicode">"unicode" directive</a>. Whitespace is ignored and removed, effectively sqeezing together the text: <pre class="literal-block">.. |copy| unicode:: U+000A9 .. COPYRIGHT SIGN .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122 .. with trademark sign Copyright |copy| 2003, |BogusMegaCorp (TM)|.</pre> In addition, the "ltrim", "rtrim", and "trim" options may be used with the "unicode" directive to automatically trim spaces from the left, right, or both sides (respectively) of substitution references: <pre class="literal-block">.. |---| unicode:: U+02014 .. em dash :trim:</pre> <section id="character-entity-sets"> <h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink">Character Entity Sets</a><a class="self-link" title="link to this section" href="#character-entity-sets"></a></h3> The following files contain substitution definitions corresponding to XML character entity sets, from the following standards: ISO 8879 & ISO 9573-13 (combined), MathML, and XHTML1. They were generated by the tools/dev/unicode2rstsubs.py program from the input file <a class="reference external" href="https://www.w3.org/2003/entities/xml/">unicode.xml</a>, which is maintained as part of the MathML 2 Recommentation XML source. <table> <colgroup> <col style="width: 27.9%" /> <col style="width: 72.1%" /> </colgroup> <thead> <tr><th class="head">Entity Set File</th> <th class="head">Description</th> </tr> </thead> <tbody> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamsa.txt">isoamsa.txt</a></td> <td>Added Mathematical Symbols: Arrows</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamsb.txt">isoamsb.txt</a></td> <td>Added Mathematical Symbols: Binary Operators</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamsc.txt">isoamsc.txt</a></td> <td>Added Mathematical Symbols: Delimiters</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamsn.txt">isoamsn.txt</a></td> <td>Added Mathematical Symbols: Negated Relations</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamso.txt">isoamso.txt</a></td> <td>Added Mathematical Symbols: Ordinary</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isoamsr.txt">isoamsr.txt</a></td> <td>Added Mathematical Symbols: Relations</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isobox.txt">isobox.txt</a></td> <td>Box and Line Drawing</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isocyr1.txt">isocyr1.txt</a></td> <td>Russian Cyrillic</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isocyr2.txt">isocyr2.txt</a></td> <td>Non-Russian Cyrillic</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isodia.txt">isodia.txt</a></td> <td>Diacritical Marks</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isogrk1.txt">isogrk1.txt</a></td> <td>Greek Letters</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isogrk2.txt">isogrk2.txt</a></td> <td>Monotoniko Greek</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isogrk3.txt">isogrk3.txt</a></td> <td>Greek Symbols</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isogrk4.txt">isogrk4.txt</a> <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref">[1]</a></td> <td>Alternative Greek Symbols</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isolat1.txt">isolat1.txt</a></td> <td>Added Latin 1</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isolat2.txt">isolat2.txt</a></td> <td>Added Latin 2</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isomfrk.txt">isomfrk.txt</a> <a class="brackets" href="#footnote-1" id="footnote-reference-2" role="doc-noteref">[1]</a></td> <td>Mathematical Fraktur</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isomopf.txt">isomopf.txt</a> <a class="brackets" href="#footnote-1" id="footnote-reference-3" role="doc-noteref">[1]</a></td> <td>Mathematical Openface (Double-struck)</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isomscr.txt">isomscr.txt</a> <a class="brackets" href="#footnote-1" id="footnote-reference-4" role="doc-noteref">[1]</a></td> <td>Mathematical Script</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isonum.txt">isonum.txt</a></td> <td>Numeric and Special Graphic</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isopub.txt">isopub.txt</a></td> <td>Publishing</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/isotech.txt">isotech.txt</a></td> <td>General Technical</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/mmlalias.txt">mmlalias.txt</a></td> <td>MathML aliases for entities from other sets</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/mmlextra.txt">mmlextra.txt</a> <a class="brackets" href="#footnote-1" id="footnote-reference-5" role="doc-noteref">[1]</a></td> <td>Extra names added by MathML</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/xhtml1-lat1.txt">xhtml1-lat1.txt</a></td> <td>XHTML Latin 1</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/xhtml1-special.txt">xhtml1-special.txt</a></td> <td>XHTML Special Characters</td> </tr> <tr><td><a class="reference external" href="../../../docutils/parsers/rst/include/xhtml1-symbol.txt">xhtml1-symbol.txt</a></td> <td>XHTML Mathematical, Greek and Symbolic Characters</td> </tr> </tbody> </table> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="footnote-1" role="doc-footnote"> [1] (<a role="doc-backlink" href="#footnote-reference-1">1</a>,<a role="doc-backlink" href="#footnote-reference-2">2</a>,<a role="doc-backlink" href="#footnote-reference-3">3</a>,<a role="doc-backlink" href="#footnote-reference-4">4</a>,<a role="doc-backlink" href="#footnote-reference-5">5</a>) There are *-wide.txt variants for each of these character entity set files, containing characters outside of the Unicode basic multilingual plane or BMP (wide-Unicode; code points greater than U+FFFF). Before Python 3.3, some distributions were "narrow" and did not support wide-Unicode characters. This should not be an issue nowadays. </aside> </aside> For example, the copyright symbol is defined as the XML character entity &copy;. The equivalent reStructuredText substitution reference (defined in both isonum.txt and xhtml1-lat1.txt) is |copy|. </section> </section> <section id="s5-html-definitions"> <h2><a class="toc-backref" href="#toc-entry-3" role="doc-backlink">S5/HTML Definitions</a><a class="self-link" title="link to this section" href="#s5-html-definitions"></a></h2> The "<a class="reference external" href="../../../docutils/parsers/rst/include/s5defs.txt">s5defs.txt</a>" standard definition file contains interpreted text roles (classes) and other definitions for documents destined to become <a class="reference external" href="../../user/slide-shows.html">S5/HTML slide shows</a>.  </section> </main> <footer> <a class="reference external" href="definitions.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>