rst2pseudoxml(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

🌸 NAME 🌸

rst2pseudoxml — bestie, this is the little glow-up machine that turns reST documents into pseudo-XML ✨ (it's rst2pseudoxml(1), if you're keeping track of the manual number, and honestly iconic of it)

🦋 SYNOPSIS 🦋

rst2pseudoxml [options] [<source> [<destination>]]

💖 DESCRIPTION 💖

Okay so picture this: you've got a standalone reStructuredText source, and you want a pseudo-XML (test) document out the other side. That's the whole gig, no cap. It's giving "doctree, but visible" 🎀

Here's the link if you wanna see what that doctree thing actually is: https://docutils.sourceforge.io/docs/ref/doctree.html 🔥

It reads from <source> — and if you don't hand it one, it just reads from stdin, like sure, whatever, it's flexible 💅 — and it writes to <destination>, which defaults to stdout if you don't say otherwise.

And for the full settings reference, the mothership is right here: https://docutils.sourceforge.io/docs/user/config.html 👑

👑 OPTIONS 👑

✨ General Docutils Options ✨

  • --output-path=<destination>, --output=<destination> — names where the output goes. This one obsoletes the <destination> positional argument (rip bozo, it's legacy now). Default: None, which means stdout 💜
  • --title=<title> — sets the document title as metadata, slay
  • --generator, -g — drops in a "Generated by Docutils" credit plus a link 🫶
  • --no-generator — no generator credit, periodt
  • --date, -d — sticks the date at the end of the document (UTC) 📅
  • --time, -t — sticks the time & date in there (UTC) ⏰
  • --no-datestamp — no datestamp of any kind, not even a little one
  • --root-prefix=<path> — the base directory used for absolute paths when it's reading from your local filesystem. Default is ""
  • --source-link, -s — includes a "View document source" link 🔗
  • --source-url=<URL> — uses <URL> for the source link; heads up, this implies --source-link
  • --no-source-link — no "View document source" link, we're shy today 🙈
  • --toc-entry-backlinks — links from section headers back to TOC entries (this is the default, bestie)
  • --toc-top-backlinks — links from section headers to the top of the TOC instead
  • --no-toc-backlinks — turns off backlinks to the table of contents entirely
  • --footnote-backlinks — links from footnotes/citations back to their references (default 🌸)
  • --no-footnote-backlinks — disables backlinks from footnotes and citations
  • --section-numbering — lets Docutils number your sections (default 💅)
  • --no-section-numbering — Docutils, hands off the numbering
  • --strip-comments — removes comment elements from the document tree
  • --leave-comments — leaves comment elements in the document tree (default)
  • --strip-elements-with-class=<class> — removes every element with classes="<class>" from the document tree. > Warning: potentially dangerous; use with caution. (Multiple-use option — you can stack it.)
  • --strip-class=<class> — removes all classes="<class>" attributes from elements in the document tree. > Warning: potentially dangerous; use with caution. (Multiple-use option, same deal.)
  • --report=<level>, -r <level> — reports system messages at or above <level>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5" 📢
  • --verbose, -v — reports all system messages. (Same as --report=1.)
  • --quiet, -q — reports no system messages at all. (Same as --report=5.) 🤫
  • --halt=<level> — halts execution at system messages at or above <level>. Levels work the same as --report. Default: 4 (severe) 🛑
  • --strict — halts at the slightest problem. Same as --halt=info. girl is sensitive, respect it 😭
  • --exit-status=<level> — enables a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (disabled)
  • --debug — enables debug-level system messages and diagnostics 🐛
  • --no-debug — disables debug output. (default)
  • --warnings=<file> — sends the output of system messages to <file>
  • --traceback — enables Python tracebacks when Docutils is halted
  • --no-traceback — disables 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> — writes output file dependencies to <file>
  • --config=<file> — reads configuration settings from <file>, if it exists
  • --version, -V — shows this program's version number and exits
  • --help, -h — shows this help message and exits

🌈 Generic Parser Options 🌈

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

🧚 reStructuredText Parser Options 🧚

  • --pep-references — recognizes and links 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 — recognizes and links 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> — sets the number of spaces for tab expansion (default 8)
  • --trim-footnote-reference-space — removes spaces before footnote references
  • --leave-footnote-reference-space — leaves spaces before footnote references
  • --syntax-highlight=<format> — token name set for parsing code with Pygments: one of "long", "short", or "none" (no parsing). Default is "long" ✨
  • --smart-quotes=<yes/no/alt> — changes straight quotation marks into typographic form: one of "yes", "no", "alt[ernative]" (default "no")
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — which characters to use as "smart quotes" for <language>
  • --word-level-inline-markup — inline markup is recognized at word boundaries only (adjacent to punctuation or whitespace). Force character-level inline markup recognition with "\" (backslash + space). This is the default.
  • --character-level-inline-markup — inline markup is recognized anywhere, regardless of the surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental, so, y'know, proceed with the vibes 🧪

🎀 Standalone Reader Options 🎀

  • --no-doc-title — disables the promotion of a lone top-level section title to document title (and the subsequent section title to document subtitle promotion, which is enabled by default)
  • --no-doc-info — disables the bibliographic field list transform (which is enabled by default)
  • --section-subtitles — activates the promotion of lone subsection titles to section subtitles (disabled by default)
  • --no-section-subtitles — deactivates the promotion of lone subsection titles

💜 "Docutils pseudo-XML" Writer Options 💜

  • --detailed — pretty-prints #text nodes 🔍
ok that's the whole thing, you ate that honestly 🍓

Sign-off time, bestie: this little masterpiece is rst2pseudoxml(1), filed under text processing 📚, and it lives in the same docutils source as all its siblings. Go forth and generate pseudo-XML, you main character 💅✨🦋

📦 where this page comes from