# reStructuredText Standard Definition Files

Author:

  David Goodger

Contact:
  docutils-develop@lists.sourceforge.net
Revision:
  10285
Date:
  2026-01-07
Copyright:
  This document has been placed in the public domain.

This document describes standard definition files, such as sets of substitution definitions and interpreted text roles, that can be included in reStructuredText documents. The "include" directive has a special syntax for these standard definition files, angle brackets around the file name:

    .. include:: <filename.txt>

The individual data files are stored with the Docutils source code in the "docutils" package, in the docutils/parsers/rst/include directory.

## Substitution Definitions

Many of the standard definition files contain sets of substitution definitions, which can be used in documents via substitution references. For example, the copyright symbol is defined in isonum.txt as "copy":

    .. include:: <isonum.txt>

    Copyright |copy| 2003 by John Q. Public, all rights reserved.

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:

    .. include:: <isonum.txt>

    Copyright |copy| 2003, BogusMegaCorp\ |trade|.

Custom substitution definitions may use the "unicode" directive. Whitespace is ignored and removed, effectively sqeezing together the text:

    .. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
       .. with trademark sign

    Copyright |copy| 2003, |BogusMegaCorp (TM)|.

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:

    .. |---| unicode:: U+02014 .. em dash
       :trim:

### Character Entity Sets

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 unicode.xml, which is maintained as part of the MathML 2 Recommentation XML source.

Entity Set File | Description
--- | ---
isoamsa.txt | Added Mathematical Symbols: Arrows
isoamsb.txt | Added Mathematical Symbols: Binary Operators
isoamsc.txt | Added Mathematical Symbols: Delimiters
isoamsn.txt | Added Mathematical Symbols: Negated Relations
isoamso.txt | Added Mathematical Symbols: Ordinary
isoamsr.txt | Added Mathematical Symbols: Relations
isobox.txt | Box and Line Drawing
isocyr1.txt | Russian Cyrillic
isocyr2.txt | Non-Russian Cyrillic
isodia.txt | Diacritical Marks
isogrk1.txt | Greek Letters
isogrk2.txt | Monotoniko Greek
isogrk3.txt | Greek Symbols
isogrk4.txt [1] | Alternative Greek Symbols
isolat1.txt | Added Latin 1
isolat2.txt | Added Latin 2
isomfrk.txt [1] | Mathematical Fraktur
isomopf.txt [1] | Mathematical Openface (Double-struck)
isomscr.txt [1] | Mathematical Script
isonum.txt | Numeric and Special Graphic
isopub.txt | Publishing
isotech.txt | General Technical
mmlalias.txt | MathML aliases for entities from other sets
mmlextra.txt [1] | Extra names added by MathML
xhtml1-lat1.txt | XHTML Latin 1
xhtml1-special.txt | XHTML Special Characters
xhtml1-symbol.txt | XHTML Mathematical, Greek and Symbolic Characters

[1] (1,2,3,4,5)

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.

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|.

## Role Definitions

Role definitions use the "role" directive to provide additional reStructuredText interpreted text roles.

### Semantic Inline Markup Roles

The "html-roles.txt" standard definitions file provides role definitions for semantic HTML inline markup elements and tags for representation of edits to the document that do not have a corresponding standard rST role (except for elements requiring an additional attribute).

The additional roles work out of the box with the "html5" writer (selects the corresponding HTML element) and the LaTeX writers.

b:

  highlight key words without marking them up as important

bdi:

  text directionality isolation [2]

del:

  represents removed content [2]

dfn:

  dfn represents the defining instance of a term [2]

i:

  voix alternative

ins:

  editional additions [2]

kbd:

  user input like `Ctrl X`

mark:

  highlight a run of text

q:

  represents phrasing content quoted from another source [2]

s:

  text that is no longer accurate, or no longer relevant

samp:

  computer output like `hello world!`

small:

  side comments like this

u:

  unarticulated annotations of, e.g, mispellings

var:

  variables (or constants like c)

[2] (1,2,3,4,5)

Would gain from support for attributes/arguments to inline roles (see TODO).

New in Docutils 0.22.

### S5/HTML Definitions

The "s5defs.txt" standard definition file contains interpreted text roles (classes) and other definitions for documents destined to become S5/HTML slide shows.