rst2xetex(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

✨ rst2xetex ✨

okay bestie, so this page is the manpage for rst2xetex, and it lives in the text processing section, i.e. section 1. buckle uppp, it's a long one — worth it tho 💖

🌸 NAME 🌸

rst2xetex — convert reST documents to XeLaTeX 🦋

🎀 SYNOPSIS 🎀

rst2xetex [options] [<source> [<destination>]]

💅 DESCRIPTION 💅

So what this does: it generates LaTeX (XeLaTeX/LuaLaTeX) documents from standalone reStructuredText sources. The deets are here in the docs: https://docutils.sourceforge.io/docs/user/latex.html.

It reads from <source> — and if you don't hand it a source, it just reads from stdin — and it writes to <destination> — and if you don't hand it a destination, it writes to stdout.

There's a whole detailed settings reference at https://docutils.sourceforge.io/docs/user/config.html if you wanna go feral with config. 🫶

✨ OPTIONS ✨

General Docutils Options

  • --output-path=<destination>, --output=<destination> — the name of the output destination. lowkey this obsoletes the <destination> positional argument. Default: None (stdout). 👀
  • --title=<title> — set the document title as metadata.
  • --generator, -g — include a "Generated by Docutils" credit and link. gotta give credit where credit is due 💖
  • --no-generator — do NOT include a generator credit.
  • --date, -d — include the date at the end of the document (UTC).
  • --time, -t — include the time & date (UTC). full timestamp energy ⏰
  • --no-datestamp — include no datestamp of any kind. none. zero. nada.
  • --root-prefix=<path> — base directory for absolute paths when reading from the local filesystem. Default "".
  • --source-link, -s — include a "View document source" link.
  • --source-url=<URL> — use <URL> for a source link; this implies --source-link.
  • --no-source-link — do NOT include a "View document source" link.
  • --toc-entry-backlinks — link from section headers to TOC entries. (default)
  • --toc-top-backlinks — link from section headers to the top of the TOC.
  • --no-toc-backlinks — disable backlinks to the table of contents.
  • --footnote-backlinks — link from footnotes/citations to references. (default)
  • --no-footnote-backlinks — disable backlinks from footnotes and citations.
  • --section-numbering — enable section numbering by Docutils. (default)
  • --no-section-numbering — disable section numbering by Docutils.
  • --strip-comments — remove comment elements from the document tree.
  • --leave-comments — leave comment elements in the document tree. (default)
  • --strip-elements-with-class=<class> — remove all elements with classes="<class>" from the document tree. > ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option.)
  • --strip-class=<class> — remove all classes="<class>" attributes from elements in the document tree. > ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option.)
  • --report=<level>, -r <level> — report system messages at or higher than <level>, where <level> is one of "info" or "1", "warning"/"2" (the default), "error"/"3", "severe"/"4", "none"/"5".
  • --verbose, -v — report ALL system messages. (Same as "--report=1".)
  • --quiet, -q — report no system messages. (Same as "--report=5".) 🤫
  • --halt=<level> — halt execution at system messages at or above <level>. Levels work like in --report. Default: 4 (severe).
  • --strict — halt at the slightest problem. Same as "--halt=info". she does not play 💀
  • --exit-status=<level> — enable a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (disabled).
  • --debug — enable debug-level system messages and diagnostics.
  • --no-debug — disable debug output. (default)
  • --warnings=<file> — send the output of system messages to <file>.
  • --traceback — enable Python tracebacks when Docutils is halted.
  • --no-traceback — disable Python tracebacks. (default)
  • --input-encoding=<name[:handler]> — specify the encoding, and optionally the error handler, of input text. Default: utf-8.
  • --output-encoding=<name[:handler]> — specify the text encoding, and optionally the error handler, for output. Default: utf-8.
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — specify text encoding, and optionally the error handler, for error output. Default: system encoding.
  • --language=<tag>, -l <tag> — specify the language as a BCP 47 language tag. Default: en.
  • --record-dependencies=<file> — write output file dependencies to <file>.
  • --config=<file> — read configuration settings from <file>, if it exists.
  • --version, -V — show this program's version number and exit.
  • --help, -h — show this help message and exit. 🫶

Generic Parser Options

  • --no-file-insertion — disable directives that insert the contents of an external file; they get replaced with a "warning" system message instead.
  • --file-insertion-enabled — enable directives that insert the contents of an external file. (default)
  • --no-raw — disable the "raw" directive; it gets replaced with a "warning" system message.
  • --raw-enabled — enable the "raw" directive. (default)
  • --line-length-limit=<length> — the maximal number of characters in an input line. Default 10 000.
  • --legacy-ids — keep identifiers backwards compatible. Default.
  • --matching-ids — explicit targets use identifiers matching the reference name.
  • --validate — validate the document tree after parsing.
  • --no-validation — do NOT validate the document tree. (default)

reStructuredText Parser Options

  • --pep-references — recognize and link to standalone PEP references (like "PEP 258").
  • --pep-base-url=<URL> — base URL for PEP references (default "https://peps.python.org/").
  • --pep-file-url-template=<URL> — template for the PEP file part of the URL. (default "pep-%04d")
  • --rfc-references — recognize and link to standalone RFC references (like "RFC 822").
  • --rfc-base-url=<URL> — base URL for RFC references (default "https://tools.ietf.org/html/").
  • --tab-width=<width> — set the number of spaces for tab expansion (default 8).
  • --trim-footnote-reference-space — remove spaces before footnote references.
  • --leave-footnote-reference-space — leave spaces before footnote references.
  • --syntax-highlight=<format> — the token name set for parsing code with Pygments, one of "long", "short", or "none" (which means no parsing). Default is "long".
  • --smart-quotes=<yes/no/alt> — change straight quotation marks to typographic form, one of "yes", "no", "alt[ernative]" (default "no").
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — the characters to use as "smart quotes" for <language>.
  • --word-level-inline-markup — inline markup is recognized at word boundaries only, i.e. adjacent to punctuation or whitespace. Force character-level inline markup recognition with "\" (backslash + space). Default.
  • --character-level-inline-markup — inline markup is recognized anywhere, regardless of surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental.

Standalone Reader Options

  • --no-doc-title — disable the promotion of a lone top-level section title to document title (and the subsequent promotion of a section title to document subtitle; this promotion is enabled by default).
  • --no-doc-info — disable the bibliographic field list transform (enabled by default).
  • --section-subtitles — activate the promotion of lone subsection titles to section subtitles (disabled by default).
  • --no-section-subtitles — deactivate the promotion of lone subsection titles.

LaTeX-Specific Options

  • --documentclass=<documentclass> — specify the LaTeX documentclass. Default: "article".
  • --documentoptions=<options> — specify document options. Multiple options can be given, separated by commas. Default: "a4paper".
  • --footnote-references=<format> — format for footnote references, one of "superscript" or "brackets". Default: "superscript".
  • --use-latex-citations — use cite command for citations. (future default)
  • --figure-citations — use figure floats for citations (might get mixed with real figures, just so you know). (provisional default)
  • --attribution=<format> — format for block quote attributions, one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". Default: "dash".
  • --stylesheet=<file[,file,...]> — specify LaTeX packages/stylesheets. A style gets referenced with "usepackage" if the extension is .sty or omitted, and with "input" otherwise. This overrides previous --stylesheet and --stylesheet-path settings.
  • --stylesheet-path=<file[,file,...]> — a comma separated list of LaTeX packages/stylesheets. Relative paths are expanded if a matching file is found in the --stylesheet-dirs. With --link-stylesheet, the path is rewritten relative to the output .tex file.
heads up bestie — the original page literally has a broken markup artifact right here, it got hiccuped mid-write ✋😭: System Message: WARNING/2 (debian/tmp/man/rst2xetex.txt:, line 186) Inline emphasis start-string without end-string.
  • --link-stylesheet — link to the stylesheet(s) in the output file. (default)
  • --embed-stylesheet — embed the stylesheet(s) in the output file. Stylesheets must be accessible during processing.
  • --stylesheet-dirs=<dir[,dir,...]> — a comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. Default: ".".
  • --latex-preamble=<preamble> — customization by LaTeX code in the preamble. Default: select "Linux Libertine" fonts.
  • --template=<file> — template file. Default: "xelatex.tex".
  • --use-latex-toc — table of contents by LaTeX. (default)
  • --use-docutils-toc — table of contents by Docutils (without page numbers).
  • --use-part-section — add parts on top of the section hierarchy.
  • --use-docutils-docinfo — attach author and date to the document info table. (default)
  • --use-latex-docinfo — attach author and date to the document title.
  • --topic-abstract — typeset abstract as topic. (default)
  • --use-latex-abstract — use LaTeX abstract environment for the document's abstract.
  • --hyperlink-color=<color> — color of any hyperlinks embedded in text. Default: "blue" (use "false" to disable).
  • --hyperref-options=<options> — additional options to the "hyperref" package.
  • --compound-enumerators — enable compound enumerators for nested enumerated lists (e.g. "1.2.a.ii").

more coming in part 2, stay tuned bestie 💖

  • --no-compound-enumerators — turns OFF compound enumerators for nested enumerated lists. this is the default, bestie, so this is just what you already get. 💅
  • --section-prefix-for-enumerators — turns ON section prefixes ("." then subsection and so on) for compound enumerators. so like 2.3.1 energy instead of just vibes. 🦋 but — and this is important — it does literally nothing unless you also have --compound-enumerators turned on. no cap. zero effect otherwise. 🙈
  • --no-section-prefix-for-enumerators — turns OFF those section prefixes for compound enumerators. also the default. we're all just out here defaulting. ✨
  • --section-enumerator-separator=<char> — sets the separator that sits between the section number and the enumerator in compound enumerated lists. default: "-". so you get that cute little hyphen moment by default. 🎀
  • --literal-block-env=<environment> — when it can, it uses the environment you name for literal-blocks. default: "" — which means it falls back to "alltt". she has a backup plan, always. 💜
  • --table-style=<format> — your table aesthetic, pick your fighter: 🌈
    • "standard" — horizontal AND vertical lines, the classic
    • "booktabs" — LaTeX booktabs style, so only horizontal lines above and below the table, plus one below the header. very clean, very editorial.
    • "borderless" — no lines, just vibes
    • default: "standard"
  • --graphicx-option=<option> — sets the LaTeX graphicx package option. default: "". that's it, that's the whole thing 🫶
  • --reference-label=<commandname> — by default, the latex-writer puts the reference title into hyperreferences. if you want the section number or the page number instead, specify "ref" or "pageref" here. pick your lore. 📖
  • --use-bibtex=<style,bibfile[,bibfile,...]> — names the style and the database(s) for bibtex, like "--use-bibtex=unsrt,mydb1,mydb2". ⚠️ Provisional! — do not build your whole personality on this one yet, it's still cooking. 💀
  • --legacy-class-functions — uses the legacy functions with the class value list for DUtitle and DUadmonition. the old way, the throwback. 🙈
  • --new-class-functions — uses DUrole and "DUclass" wrappers for class values, and puts admonition content in an environment. this is the default. main character behaviour, genuinely. 👑
  • --legacy-column-widths — uses the legacy algorithm to figure out table column widths. this is the provisional default right now, so heads up, it's the one you're getting unless you say otherwise. 😭
  • --new-column-widths — uses the new algorithm for table column widths. it's marked as the future default, so enjoy it now before it becomes the norm. 🌟
  • --docutils-footnotes — footnotes with numbers/symbols courtesy of Docutils. default. 💖
  • --latex-footnotes — footnotes with numbers, brought to you by LaTeX. 🎀

and that's the whole page, bestie!! 🫶 you made it all the way to the bottom, which honestly is iconic of you. this was rst2xetex(1) — yes, the man page itself is literally named that, she's self-titled, she's the moment. ✨ 💅🌸

go forth and xetex responsibly. periodt. 💖

📦 where this page comes from