# docutils.sty

Helper commands and element definitions for Docutils LaTeX output.

Copyright

  © 2020 Günter Milde

Licence

  Released under the terms of the 2-Clause BSD license

## Changelog

2020-08-28 first public version for Docutils >= 0.17

## Requirements

None.

## Installation

If possible, get this package from your distribution using its installation manager. Alternatively, copy/move/link docutils.sty to a place where LaTeX can find it.

## Usage

The package is intended for use with LaTeX documents generated from reStructuredText sources with Docutils.

When generating LaTeX documents, specify this package with the “stylesheet” configuration option, e.g.

    rst2latex --stylesheet=docutils exampledocument.txt

The the Docutils LaTeX writer will then reference this package istead of inserting required definitions into the preamble of generated documents (see the Docutils LaTeX Writer documentation for details).

## Documentation Generation

The bidirectional text <-> code converter PyLit and Docutils were used to generate the HTML documentation:

    #> pylit docutils.sty
    #> rst2html5 docutils.sty.txt docutils.sty.html

## Implementation

### Identification

    \NeedsTeXFormat{LaTeX2e}
    \ProvidesPackage{docutils}
      [2020/08/28 macros for Docutils LaTeX output]

### Helpers

duclass:

    % class handling for environments (block-level elements)
    % \begin{DUclass}{spam} tries \DUCLASSspam and
    % \end{DUclass}{spam} tries \endDUCLASSspam
    \ifx\DUclass\undefined % poor man's "provideenvironment"
     \newenvironment{DUclass}[1]%
      {% "#1" does not work in end-part of environment.
       \def\DocutilsClassFunctionName{DUCLASS#1}
         \csname \DocutilsClassFunctionName \endcsname}%
      {\csname end\DocutilsClassFunctionName \endcsname}%
    \fi

providelength:

    % Provide a length variable and set default, if it is new
    \providecommand*{\DUprovidelength}[2]{
      \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
    }

### Configuration defaults

See the Docutils LaTeX Writer documentation for details.

abstract:

    \providecommand*{\DUCLASSabstract}{
      \renewcommand{\DUtitle}[1]{\centerline{\textbf{##1}}}
    }

dedication:

    % special topic for dedications
    \providecommand*{\DUCLASSdedication}{%
      \renewenvironment{quote}{\begin{center}}{\end{center}}%
    }

TODO: add em to set dedication text in italics?

docinfo:

    % width of docinfo table
    \DUprovidelength{\DUdocinfowidth}{0.9\linewidth}

error:

    \providecommand*{\DUCLASSerror}{\color{red}}

highlight_rules:

    % basic code highlight:
    \providecommand*\DUrolecomment[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}}
    \providecommand*\DUroledeleted[1]{\textcolor[rgb]{0.40,0.40,0.40}{#1}}
    \providecommand*\DUrolekeyword[1]{\textbf{#1}}
    \providecommand*\DUrolestring[1]{\textit{#1}}

### Elements

Definitions for unknown or to-be-configured Docutils elements.

admonition:

    % admonition environment (specially marked topic)
    \ifx\DUadmonition\undefined % poor man's "provideenvironment"
     \newbox{\DUadmonitionbox}
     \newenvironment{DUadmonition}%
      {\begin{center}
         \begin{lrbox}{\DUadmonitionbox}
           \begin{minipage}{0.9\linewidth}
      }%
      {    \end{minipage}
         \end{lrbox}
         \fbox{\usebox{\DUadmonitionbox}}
       \end{center}
      }
    \fi

fieldlist:

    % field list environment (for separate configuration of `field lists`)
    \ifthenelse{\isundefined{\DUfieldlist}}{
      \newenvironment{DUfieldlist}%
        {\quote\description}
        {\enddescription\endquote}
    }{}

footnotes:

    % numerical or symbol footnotes with hyperlinks and backlinks
    \providecommand*{\DUfootnotemark}[3]{%
      \raisebox{1em}{\hypertarget{#1}{}}%
      \hyperlink{#2}{\textsuperscript{#3}}%
    }
    \providecommand{\DUfootnotetext}[4]{%
      \begingroup%
      \renewcommand{\thefootnote}{%
        \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
        \protect\hyperlink{#2}{#3}}%
      \footnotetext{#4}%
      \endgroup%
    }

inline:

    % custom inline roles: \DUrole{#1}{#2} tries \DUrole#1{#2}
    \providecommand*{\DUrole}[2]{%
      \ifcsname DUrole#1\endcsname%
        \csname DUrole#1\endcsname{#2}%
      \else%
        #2%
      \fi%
    }

legend:

    % legend environment (in figures and formal tables)
    \ifthenelse{\isundefined{\DUlegend}}{
      \newenvironment{DUlegend}{\small}{}
    }{}

lineblock:

    % line block environment
    \DUprovidelength{\DUlineblockindent}{2.5em}
    \ifthenelse{\isundefined{\DUlineblock}}{
      \newenvironment{DUlineblock}[1]{%
        \list{}{\setlength{\partopsep}{\parskip}
                \addtolength{\partopsep}{\baselineskip}
                \setlength{\topsep}{0pt}
                \setlength{\itemsep}{0.15\baselineskip}
                \setlength{\parsep}{0pt}
                \setlength{\leftmargin}{#1}}
        \raggedright
      }
      {\endlist}
    }{}

optionlist:

    % list of command line options
    \providecommand*{\DUoptionlistlabel}[1]{\bfseries #1 \hfill}
    \DUprovidelength{\DUoptionlistindent}{3cm}
    \ifthenelse{\isundefined{\DUoptionlist}}{
      \newenvironment{DUoptionlist}{%
        \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
                \setlength{\rightmargin}{1cm}
                \setlength{\leftmargin}{\rightmargin}
                \addtolength{\leftmargin}{\labelwidth}
                \addtolength{\leftmargin}{\labelsep}
                \renewcommand{\makelabel}{\DUoptionlistlabel}}
      }
      {\endlist}
    }{}

rubric:

    % informal heading
    \providecommand*{\DUrubric}[1]{\subsubsection*{\emph{#1}}}

sidebar:

    % text outside the main text flow
    \providecommand{\DUsidebar}[1]{%
      \begin{center}
        \colorbox[gray]{0.80}{\parbox{0.9\linewidth}{#1}}
      \end{center}
    }

title:

    % title for topics, admonitions, unsupported section levels, and sidebar
    \providecommand*{\DUtitle}[1]{\subsubsection*{#1}}

subtitle:

    % subtitle (for sidebar)
    \providecommand*{\DUsubtitle}[1]{\par\emph{#1}\smallskip}

documentsubtitle:

    % subtitle (in document title)
    \providecommand*{\DUdocumentsubtitle}[1]{{\large #1}}

titlereference:

    % titlereference standard role
    \providecommand*{\DUroletitlereference}[1]{\textsl{#1}}

transition:

    % transition (break / fancybreak / anonymous section)
    \providecommand*{\DUtransition}{%
      \hspace*{\fill}\hrulefill\hspace*{\fill}
      \vskip 0.5\baselineskip
    }