rst2html4(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

💖 rst2html4 — the girlies' guide to reST → XHTML 💖

okay bestie, welcome to rst2html4, a manual page from section 1 (text processing) 🎀 she's giving "I turn your reStructuredText into XHTML" and honestly? she ate. ✨

🌸 NAME 🌸

rst2html4 — convert reST documents to XHTML 🦋

no cap, that's the whole job. she takes your reST and hands you back some fresh XHTML.

✨ SYNOPSIS ✨

rst2html4 [options] [<source> [<destination>]]

so you got your options, and then optionally a source and a destination, in that order. the square brackets mean they're optional, she's flexible like that 💅

👑 DESCRIPTION 👑

so here's the vibe: rst2html4 generates XHTML 1.1 documents from standalone reStructuredText sources 💖

the reST spec she's working off lives at <https://docutils.sourceforge.io/docs/user/html.html#html4css1> — go read it, it's iconic.

she reads from source — and if you don't hand her one, the default is stdin 🌈 — and she writes to destination, where the default is stdout ⭐. so like, she can just vibe in a pipe if you want. no files required, she's low maintenance.

and if you want the full settings reference (like, the deep lore of every config option), it's right here:

<https://docutils.sourceforge.io/docs/user/config.html>

fr fr, bookmark that one. 🫶

...more coming in part 2, don't go anywhere bestie 💜

✨ OPTIONS ✨

okay bestie this is the main event, the options list, the whole fitting room 💅 every flag rst2html4 will accept, grouped by which part of the machinery it belongs to. scroll, screenshot, live your truth.

🫶 General Docutils Options 🫶

these are the ones that talk to Docutils itself, the whole ecosystem, not just the HTML bit. literally the foundation, the base layer, the primer 🎀

  • --output-path=<destination>, --output=<destination> — where the output actually goes, the destination name. heads up: this makes the old <destination> positional argument obsolete (rip bozo). Default: None, which means stdout, so it just spills out into your terminal.
  • --title=<title> — set the document title as metadata. metadata only, it's not doing a whole rebrand for you.
  • --generator, -g — adds a "Generated by Docutils" credit and link. give the tool its flowers 💐
  • --no-generator — no generator credit. no credit, no notes, we move in silence.
  • --date, -d — slaps the date at the end of the document, in UTC.
  • --time, -t — the time and the date, both, in UTC. main character timestamps ✨
  • --no-datestamp — no datestamp of any kind. at all. zero. none.
  • --root-prefix=<path> — the base directory used for absolute paths when it's reading from the local filesystem. Default: "".
  • --source-link, -s — include a "View document source" link.
  • --source-url=<URL> — use <URL> for that source link. sneaky detail: this one implies --source-link, so you don't have to ask twice.
  • --no-source-link — do not include a "View document source" link. hiding the receipts i see 🙈
  • --toc-entry-backlinks — links from section headers back to the TOC entries. this is the (default) behavior, so you're already living it.
  • --toc-top-backlinks — links from section headers to the very top of the TOC instead of the entry itself.
  • --no-toc-backlinks — backlinks to the table of contents? disabled. gone.
  • --footnote-backlinks — links from footnotes/citations back to their references. (default) 💖
  • --no-footnote-backlinks — no backlinks from footnotes and citations. they can't find their way home.
  • --section-numbering — section numbering by Docutils, turned on. this is the (default).
  • --no-section-numbering — section numbering by Docutils, turned off. no numbers, just vibes.
  • --strip-comments — removes comment elements from the document tree.
  • --leave-comments — leaves comment elements in the document tree. (default).
  • --strip-elements-with-class=<class> — nukes every element with classes="<class>" from the document tree. ⚠️ Warning: potentially dangerous; use with caution. Also: Multiple-use option, so you can stack it.
  • --strip-class=<class> — removes all classes="<class>" attributes from elements in the document tree (the elements stay, the class tag dips). ⚠️ Warning: potentially dangerous; use with caution. Also a Multiple-use option.
  • --report=<level>, -r <level> — report system messages at or above <level>. your levels are: info or 1, warning/2 (default), error/3, severe/4, none/5.
  • --verbose, -v — report all system messages. same thing as --report=1, just shorter to type.
  • --quiet, -q — report no system messages. same thing as --report=5. shhh 🤫
  • --halt=<level> — halt execution when system messages hit at or above <level>. levels work like --report. Default: 4 (severe).
  • --strict — halts at the slightest problem, no chill whatsoever. same as --halt=info.
  • --exit-status=<level> — makes it exit with a non-zero status for non-halting system messages at or above <level>. Default: 5 (which means disabled).
  • --debug — enables debug-level system messages and diagnostics. the flashlight 🔦
  • --no-debug — disables debug output. (default).
  • --warnings=<file> — sends the output of system messages into <file>.
  • --traceback — enables Python tracebacks when Docutils gets halted. buckle up 🎢
  • --no-traceback — disables Python tracebacks. (default).
  • --input-encoding=<name[:handler]> — specify the encoding of input text, and optionally the error handler too. Default: utf-8.
  • --output-encoding=<name[:handler]> — specify the text encoding for output and optionally the error handler. Default: utf-8.
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — specify text encoding and optionally the error handler for error output. Default: the system encoding.
  • --language=<tag>, -l <tag> — specify the language as a BCP 47 language tag. Default: en.
  • --record-dependencies=<file> — writes output file dependencies into <file>.
  • --config=<file> — read configuration settings from <file>, if it exists. no file, no drama.
  • --version, -V — shows this program's version number, then exits.
  • --help, -h — shows this help message, then exits. hi, hello, welcome 💖

🌈 Generic Parser Options 🌈

the parser's own little ruleset, shared across the parser family. very "we all agreed on this" energy.

  • --no-file-insertion — disables directives that insert the contents of an external file. instead of doing the thing, it swaps in 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> — the maximum number of characters in one input line. Default 10 000.
  • --legacy-ids — keeps identifiers backwards compatible. this one is the Default.
  • --matching-ids — explicit targets use identifiers matching the reference name.
  • --validate — validates the document tree after parsing. check your work bestie ✨
  • --no-validation — does not validate the document tree. (default).

🦋 reStructuredText Parser Options 🦋

this is the reStructuredText-specific section, and honestly it's giving extremely online with the PEP and RFC link recognition. iconic.

  • --pep-references — recognizes standalone PEP references (like "PEP 258") and links them.
  • --pep-base-url=<URL> — the base URL for PEP references. Default is "https://peps.python.org/".
  • --pep-file-url-template=<URL> — template for the PEP file part of the URL. Default "pep-%04d".
  • --rfc-references — recognizes standalone RFC references (like "RFC 822") and links them.
  • --rfc-base-url=<URL> — base URL for RFC references. Default "https://tools.ietf.org/html/".
  • --tab-width=<width> — how many spaces a tab expands to. Default 8.
  • --trim-footnote-reference-space — removes the spaces before footnote references. tidy 💅
  • --leave-footnote-reference-space — leaves the spaces before footnote references alone.
  • --syntax-highlight=<format> — the token name set used for parsing code with Pygments. one of "long", "short", or "none" (which means no parsing at all). Default is "long".
  • --smart-quotes=<yes/no/alt> — turns straight quotation marks into typographic form. one of "yes", "no", "alt[ernative]". Default "no".
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — the characters to use as "smart quotes" for a given <language>.
  • --word-level-inline-markup — inline markup only gets recognized at word boundaries, meaning adjacent to punctuation or whitespace. if you really want character-level recognition, force it with "" (that's backslash + space). this is the Default.
  • --character-level-inline-markup — inline markup gets recognized anywhere, no matter what's surrounding it. so you have to use backslash-escapes to avoid unwanted markup recognition. useful for East Asian languages. labeled Experimental, so, you know, proceed with intention. 🧪

👑 Standalone Reader Options 👑

the reader that reads your document all by itself. it has opinions about titles.

  • --no-doc-title — disables promoting a lone top-level section title into the document title. (which also kills the follow-up move: promoting the subsequent section title into the document subtitle, which is enabled by default.)
  • --no-doc-info — disables the bibliographic field list transform. (that one's enabled by default.)
  • --section-subtitles — activates promoting lone subsection titles into section subtitles. (disabled by default.)
  • --no-section-subtitles — deactivates promoting lone subsection titles. that's it. that's the whole job.

💜 HTML Writer Options 💜

where the HTML actually gets its look. styling, structure, the outfit 💅

  • --template=<file> — the template file. UTF-8 encoded. Default: "/usr/share/docutils/writers/html4css1/template.txt".
  • --stylesheet=<URL[,URL,...]> — comma separated list of stylesheet URLs. this overrides any previous --stylesheet and --stylesheet-path settings, so it wins, periodt.
  • --stylesheet-path=<file[,file,...]> — comma separated list of stylesheet paths. relative paths get expanded if a matching file turns up in the --stylesheet-dirs. with --link-stylesheet, the path gets rewritten relative to the output HTML file. Default: "html4css1.css".
  • --stylesheet-dirs=<dir[,dir,...]> — comma-separated list of directories where stylesheets live. used by --stylesheet-path when it's expanding relative path arguments. Default: ".,/usr/share/docutils/writers/html4css1,/usr/share/docutils/writers/html5_polyglot".
  • --embed-stylesheet — embeds the stylesheet(s) right into the output HTML file. the stylesheet files have to be accessible while it's processing. (default).
  • --link-stylesheet — links to the stylesheet(s) in the output HTML file instead.
  • --initial-header-level=<level> — sets the initial header level. note it does not touch the document title & subtitle (go look at --no-doc-title for that). Default: 1 for "<h1>".
  • --footnote-references=<format> — format for footnote references, one of "superscript" or "brackets". Default: "brackets".
  • --attribution=<format> — format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". Default: "dash".
  • --compact-lists — removes the extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default).
  • --no-compact-lists — disables compact simple bullet and enumerated lists. let them breathe.
  • --compact-field-lists — removes extra vertical whitespace between items of simple field lists. (default).
  • --no-compact-field-lists — disables compact simple field lists.
  • --table-style=<style> — the class value(s) assigned to all tables. defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid.
  • --math-output=<format[option(s)]> — math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") plus option(s). Default: "HTML math.css".
  • --xml-declaration — prepends an XML declaration. (default).
  • --no-xml-declaration — omits the XML declaration.
  • --cloak-email-addresses — obfuscates email addresses to confuse harvesters, while still keeping email links usable in standards-compliant browsers. sneaky and thoughtful at the same time 🧚

🎀 HTML4 Writer Options 🎀

last stretch bestie, just the html4-specific width knobs.

  • --field-name-limit=<level> — the maximum width, in characters, for one-column field names. longer field names will span an entire row of the table used to render the field list. Default is 14 characters. use 0 for "no limit".
  • --option-limit=<level> — the maximum width, in characters, for options in option lists. longer options will span an entire row of the table used to render the option list. Default is 14 characters. use 0 for "no limit".

and that's the whole page, you made it to the end 🫶 this was the rst2html4(1) manual from Docutils — the version and date live down in the source footer, so go check the page you pulled this from for the exact ones. now go convert something and slay 💖✨👑

📦 where this page comes from