rst2xml(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

👑 rst2xml — the Docutils-native XML maker 👑

okay bestie, welcome to the rst2xml manual page, filed under the text processing section of the manual, section 1 💅 (yes we're doing the whole manpage thing, and yes it ate).

✨ Name ✨

rst2xml — the girl that converts reST documents to XML 🦋

🌸 Synopsis 🌸

rst2xml [options] [<source> [<destination>]]

💖 Description 💖

So basically: she generates Docutils-native XML documents out of standalone reStructuredText sources — here's the whole tea on that: https://docutils.sourceforge.io/docs/ref/doctree.html 🫶

She reads from <source> (and if you don't hand her one, default is stdin, no thoughts head empty) and writes to <destination> (and if you don't give her one of those either, default is stdout, she's just yapping to the terminal fr fr).

Want the full settings reference? It's right here: https://docutils.sourceforge.io/docs/user/config.html — go be nosy, iykyk 🌈

🎀 Options 🎀

🌟 General Docutils Options 🌟

  • --output-path=<destination>, --output=<destination> — name your output destination right here. Heads up: this one obsoletes the <destination> positional argument (she's moved on 💅). Default: None (so, stdout).
  • --title=<title> — set the document title as metadata. Cute, on brand.
  • --generator, -g — include a "Generated by Docutils" credit and link. Give credit where it's due ✨
  • --no-generator — do NOT include a generator credit. humble queen behavior.
  • --date, -d — include the date at the end of the document (that's UTC, btw).
  • --time, -t — include the time and the date (also UTC ⏰).
  • --no-datestamp — no datestamp of any kind. none. zero. not even a little one.
  • --root-prefix=<path> — base directory for absolute paths when she's reading from the local filesystem. Default is "" (empty string, she's lowkey minimal).
  • --source-link, -s — include a "View document source" link 👀
  • --source-url=<URL> — use <URL> for a source link; and plot twist, this implies --source-link.
  • --no-source-link — do NOT include a "View document source" link. mystery girl.
  • --toc-entry-backlinks — link from section headers to TOC entries. (default) 💫
  • --toc-top-backlinks — link from section headers to the top of the TOC. back to the beginning, iconic.
  • --no-toc-backlinks — disable backlinks to the table of contents entirely.
  • --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. anarchist vibes.
  • --strip-comments — remove comment elements from the document tree. gossip removal service.
  • --leave-comments — leave comment elements in the document tree. (default) keep the receipts.
  • --strip-elements-with-class=<class> — remove all elements with classes="<class>" from the document tree. ⚠️ Warning: potentially dangerous; use with caution. (This is a multiple-use option, so you can stack it.) > bestie please be careful, this one actually bites 💀
  • --strip-class=<class> — remove all classes="<class>" attributes from elements in the document tree. ⚠️ Warning: potentially dangerous; use with caution. (Multiple-use option too.) > again: caution. she means it 😭
  • --report=<level>, -r <level> — report system messages at or higher than <level>. The levels: "info" or "1", "warning"/"2" (that's the default), "error"/"3", "severe"/"4", "none"/"5" 📢
  • --verbose, -v — report all system messages. (Literally the same as --report=1.) she's telling you EVERYTHING.
  • --quiet, -q — report no system messages. (Same as --report=5.) not a single word.
  • --halt=<level> — halt execution at system messages at or above <level>. Levels work like in --report. Default: 4 (severe). she said stop right there 🛑
  • --strict — halt at the slightest problem. Same as --halt=info. perfectionist era.
  • --exit-status=<level> — enable a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (which is disabled).
  • --debug — enable debug-level system messages and diagnostics. detective mode 🔍
  • --no-debug — disable debug output. (default)
  • --warnings=<file> — send the output of system messages to <file>. 📬
  • --traceback — enable Python tracebacks when Docutils is halted. the full story, no cuts.
  • --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. (if it exists!! conditional queen.)
  • --version, -V — show this program's version number and exit.
  • --help, -h — show this help message and exit. hi bestie 👋

🧚 Generic Parser Options 🧚

  • --no-file-insertion — disable directives that insert the contents of an external file; they get replaced with a "warning" system message. no outside snacks allowed.
  • --file-insertion-enabled — enable directives that insert the contents of an external file. (default) okay fine, bring the snacks.
  • --no-raw — disable the "raw" directive; replaced with a "warning" system message. 🚫
  • --raw-enabled — enable the "raw" directive. (default) raw is back on the menu.
  • --line-length-limit=<length> — maximal number of characters in an input line. Default 10 000. (she's got limits, and that's healthy 💅)
  • --legacy-ids — keep identifiers backwards compatible. Default. nostalgic core.
  • --matching-ids — explicit targets use identifiers matching the reference name.
  • --validate — validate the document tree after parsing. vibe check ✅
  • --no-validation — do not validate the document tree. (default) we're freestyling.

🍓 reStructuredText Parser Options 🍓

  • --pep-references — recognize and link to standalone PEP references (like "PEP 258"). stan PEP.
  • --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"). stan RFC too, we don't play favorites.
  • --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. tab girlies rise.
  • --trim-footnote-reference-space — remove spaces before footnote references. tidy ✨
  • --leave-footnote-reference-space — leave spaces before footnote references. chaotic but valid.
  • --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> — change straight quotation marks to typographic form: one of "yes", "no", "alt[ernative]" (default "no"). curly quotes are a personality trait 🎀
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — characters to use as "smart quotes" for <language>.
  • --word-level-inline-markup — inline markup 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 recognized anywhere, regardless of surrounding characters. You must use backslash-escapes to avoid unwanted markup recognition. Useful for East Asian languages. Experimental. ⚠️ (experimental = she's still figuring it out, be nice)

💜 Standalone Reader Options 💜

  • --no-doc-title — disable the promotion of a lone top-level section title to document title (and the subsequent section title to document subtitle promotion; that whole thing is enabled by default). no promotions today.
  • --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). glow up: activated.
  • --no-section-subtitles — deactivate the promotion of lone subsection titles. glow down, respectfully.

🌈 "Docutils XML" Writer Options 🌈

  • --newlines — generate XML with newlines before and after tags.
  • --indents — generate XML with indents and newlines. (aesthetic ✨)
  • --no-xml-declaration — omit the XML declaration. Use with caution. > i'm just repeating what she said, this one's a risky move 😭
  • --no-doctype — omit the DOCTYPE declaration.

okay that's the entire page, you read the whole thing, I'm so proud of you 🫶 and for the record: this is the rst2xml page from the text processing manual, hanging out in section 1 — she's a classic, a legend, the moment 💅 no cap, go convert something pretty. mwah 💖

📦 where this page comes from