rst2s5(1)

📦
version 0.23 · 6 versions
, in ubuntu stonking

💖 rst2s5(1) — text processing 💖

hey bestie 🫶 you just opened the manual for rst2s5. it's giving "slide deck from plain text" and honestly? iconic. ✨

📛 Name

rst2s5 — convert reST documents to S5 slides. no cap. 💅

🎬 Synopsis

rst2s5 [options] [<source> [<destination>]]

📖 Description

okay so real talk: this generates S5 HTML slideshow documents from standalone reStructuredText sources <<https://docutils.sourceforge.io/docs/user/slide-shows.html>>. It reads from <source> (default is stdin) and writes to <destination> (default is stdout). If you want the full settings reference, see <https://docutils.sourceforge.io/docs/user/config.html>. it's literally a whole slideshow pipeline and I'm obsessed. 🦋✨

🛠️ Options 🛠️

🌈 General Docutils Options 🌈

  • --output-path=<destination>, --output=<destination> — This is the output destination name, bestie. It obsoletes the <destination> positional argument. Default: None (stdout). so if you're like "where do I put the slides?" this is your girl. 💖
  • --title=<title> — Specify the document title as metadata. it's the little name tag for your doc. 🎀
  • --generator, -g — Include a "Generated by Docutils" credit and link. give credit where it's due, periodt.
  • --no-generator — Do not include a generator credit. no credit, no link, no drama.
  • --date, -d — Include the date at the end of the document (UTC). timestamp incoming. ⏰
  • --time, -t — Include the time & date (UTC). even more timestamp energy.
  • --no-datestamp — Do not include a datestamp of any kind. zero timestamps. none. nada.
  • --root-prefix=<path> — Base directory for absolute paths when reading from the local filesystem. Default "". lowkey the anchor for your absolute paths. ⚓
  • --source-link, -s — Include a "View document source" link. for the nosy besties who wanna peek. 👀
  • --source-url=<URL> — Use <URL> for a source link; implies --source-link. it's like --source-link but with a custom URL. slay.
  • --no-source-link — Do not include a "View document source" link. no peeking allowed. 🙈
  • --toc-entry-backlinks — Link from section headers to TOC entries. (default) backlinks from your headers to the table of contents? yes bestie. 🔗
  • --toc-top-backlinks — Link from section headers to the top of the TOC. same vibe, but to the top. ⬆️
  • --no-toc-backlinks — Disable backlinks to the table of contents. no TOC backlinks, no problem.
  • --footnote-backlinks — Link from footnotes/citations to references. (default) footnote glow-up. ✨
  • --no-footnote-backlinks — Disable backlinks from footnotes and citations. footnotes stay unlinked. periodt.
  • --section-numbering — Enable section numbering by Docutils. (default) numbers on your sections, because order is self-care. 🔢
  • --no-section-numbering — Disable section numbering by Docutils. no numbers, just vibes.
  • --strip-comments — Remove comment elements from the document tree. bye-bye comments. 💀
  • --leave-comments — Leave comment elements in the document tree. (default) comments stay, bestie.
  • --strip-elements-with-class=<class> — Remove all elements with classes="<class>" from the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.) this one is highkey powerful, so don't just yolo it. ⚠️
  • --strip-class=<class> — Remove all classes="<class>" attributes from elements in the document tree. Warning: potentially dangerous; use with caution. (Multiple-use option.) again: powerful, use with caution. ⚠️
  • --report=<level>, -r <level> — Report system messages at or higher than <level>: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5". it's the volume knob for system messages. 🔊
  • --verbose, -v — Report all system messages. (Same as "--report=1".) all the messages, all the time.
  • --quiet, -q — Report no system messages. (Same as "--report=5".) shhh. 🤫
  • --halt=<level> — Halt execution at system messages at or above <level>. Levels as in --report. Default: 4 (severe). it stops the second things get too severe. 🛑
  • --strict — Halt at the slightest problem. Same as "--halt=info". no chill mode, activated. 💅
  • --exit-status=<level> — Enable a non-zero exit status for non-halting system messages at or above <level>. Default: 5 (disabled). so the shell knows something went down. 🚨
  • --debug — Enable debug-level system messages and diagnostics. debug girlies, rise. 🐛
  • --no-debug — Disable debug output. (default) no debug, just peace.
  • --warnings=<file> — Send the output of system messages to <file>. redirect those warnings, bestie. 📝
  • --traceback — Enable Python tracebacks when Docutils is halted. when it breaks, show the whole receipt. 🧾
  • --no-traceback — Disable Python tracebacks. (default) no receipts, just vibes.
  • --input-encoding=<name[:handler]> — Specify the encoding and optionally the error handler of input text. Default: utf-8. input encoding, handled. 💖
  • --output-encoding=<name[:handler]> — Specify the text encoding and optionally the error handler for output. Default: utf-8. output encoding, also handled.
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — Specify text encoding and optionally the error handler for error output. Default: system encoding. errors get their own encoding. iconic.
  • --language=<tag>, -l <tag> — Specify the language (as BCP 47 language tag). Default: en. set the language, bestie. 🌍
  • --record-dependencies=<file> — Write output file dependencies to <file>. keep track of what depends on what. 🔗
  • --config=<file> — Read configuration settings from <file>, if it exists. config file? read it if it's there. 📁
  • --version, -V — Show this program's version number and exit. version check, then bounce. 👑
  • --help, -h — Show this help message and exit. the classic. help me help you. 🫶

🧚 Generic Parser Options 🧚

  • --no-file-insertion — Disable directives that insert the contents of an external file; replaced with a "warning" system message. no sneaky file inserts. ⚠️
  • --file-insertion-enabled — Enable directives that insert the contents of an external file. (default) file inserts are on, bestie. 📥
  • --no-raw — Disable the "raw" directive; replaced with a "warning" system message. raw directive? not today. ⚠️
  • --raw-enabled — Enable the "raw" directive. (default) raw is on. periodt.
  • --line-length-limit=<length> — Maximal number of characters in an input line. Default 10 000. long lines? not on my watch. 📏
  • --legacy-ids — Keep identifiers backwards compatible. Default. legacy IDs for the win.
  • --matching-ids — Explicit targets use identifiers matching the reference name. IDs that match the reference name. slay.
  • --validate — Validate the document tree after parsing. check the tree after parsing. ✅
  • --no-validation — Do not validate the document tree. (default) no validation, just vibes.

🐍 reStructuredText Parser Options 🐍

  • --pep-references — Recognize and link to standalone PEP references (like "PEP 258"). PEP links, activated. 🐍
  • --pep-base-url=<URL> — Base URL for PEP references (default "<https://peps.python.org/>"). the base URL for PEP links.
  • --pep-file-url-template=<URL> — Template for PEP file part of URL. (default "pep-%04d"). the template for the PEP file part.
  • --rfc-references — Recognize and link to standalone RFC references (like "RFC 822"). RFC links, let's go. 📜
  • --rfc-base-url=<URL> — Base URL for RFC references (default "<https://tools.ietf.org/html/>"). base URL for RFC links.
  • --tab-width=<width> — Set number of spaces for tab expansion (default 8). tabs become spaces, exactly how many you say. 📐
  • --trim-footnote-reference-space — Remove spaces before footnote references. trim those spaces. ✂️
  • --leave-footnote-reference-space — Leave spaces before footnote references. leave those spaces alone.
  • --syntax-highlight=<format> — Token name set for parsing code with Pygments: one of "long", "short", or "none" (no parsing). Default is "long". syntax highlighting, but make it fashion. 🎨
  • --smart-quotes=<yes/no/alt> — Change straight quotation marks to typographic form: one of "yes", "no", "alt[ernative]" (default "no"). curly quotes? only if you say so. 💅
  • --smartquotes-locales=<language:quotes[,language:quotes,...]> — Characters to use as "smart quotes" for <language>. per-language smart quotes. 🌍
  • --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). Default. word-level inline markup is the default vibe.
  • --character-level-inline-markup — Inline markup recognized anywhere, regardless of surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental. character-level markup, anywhere, but experimental so be careful. 🧪

📚 Standalone Reader Options 📚

  • --no-doc-title — Disable the promotion of a lone top-level section title to document title (and subsequent section title to document subtitle promotion; enabled by default). don't promote that lone title. 🙅
  • --no-doc-info — Disable the bibliographic field list transform (enabled by default). no bibliographic field list transform. periodt.
  • --section-subtitles — Activate the promotion of lone subsection titles to section subtitles (disabled by default). subsection titles become section subtitles. ✨
  • --no-section-subtitles — Deactivate the promotion of lone subsection titles. no promotion, no subtitles.

🌐 HTML Writer Options 🌐

  • --template=<file> — Template file. (UTF-8 encoded, default: "/usr/share/docutils/writers/html4css1/template.txt"). your template, your rules. 🎀
  • --stylesheet=<URL[,URL,...]> — Comma separated list of stylesheet URLs. Overrides previous --stylesheet and --stylesheet-path settings. stylesheets by URL, and it overrides the previous settings. 💅
  • --stylesheet-path=<file[,file,...]> — Comma separated list of stylesheet paths. 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 HTML file. (default: "html4css1.css"). stylesheets by path, with expansion and rewriting. 🔗
  • --stylesheet-dirs=<dir[,dir,...]> — Comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. (default: ".,/usr/share/docutils/writers/html4css1,/usr/share/docutils/writers/html5_polyglot"). the directories where stylesheets live. 🏠
  • --embed-stylesheet — Embed the stylesheet(s) in the output HTML file. The stylesheet files must be accessible during processing. (default). embed the styles, but the files gotta be reachable. 📎
  • --link-stylesheet — Link to the stylesheet(s) in the output HTML file. link instead of embed. 🔗
  • --initial-header-level=<level> — Specify the initial header level. Does not affect document title & subtitle (see --no-doc-title). (default: 1 for "<h1>"). set the starting header level. 1️⃣
  • --footnote-references=<format> — Format for footnote references: one of "superscript" or "brackets". (default: "brackets"). footnote refs, styled. 💅
  • --attribution=<format> — Format for block quote attributions: one of "dash" (em-dash prefix), "parentheses"/"parens", or "none". (default: "dash"). how you want your block quote attributions to look. 🎭
  • --compact-lists — Remove extra vertical whitespace between items of "simple" bullet lists and enumerated lists. (default). compact lists, less space. 📏
  • --no-compact-lists — Disable compact simple bullet and enumerated lists. no compact lists, more space.
  • --compact-field-lists — Remove extra vertical whitespace between items of simple field lists. (default). compact field lists. ✨
  • --no-compact-field-lists — Disable compact simple field lists. no compact field lists.
  • --table-style=<style> — Class value(s) assigned to all tables. Defined styles: borderless, booktabs, align-left, align-center, align-right, colwidths-auto, colwidths-grid. give your tables a class, bestie. 📊
  • --math-output=<format[option(s)]> — Math output format (one of "MathML", "HTML", "MathJax", or "LaTeX") and option(s). (default: "HTML math.css"). math output, formatted. ➗
  • --xml-declaration — Prepend an XML declaration (default). XML declaration, up top. 📜
  • --no-xml-declaration — Omit the XML declaration. no XML declaration. 🙅
  • --cloak-email-addresses — Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards-compliant browsers. hide those emails from the harvesters, but keep them clickable. 🕵️

🖥️ HTML4 Writer Options 🖥️

  • --field-name-limit=<level> — Specify 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". field names get a width limit; 0 means no limit. 💅
  • --option-limit=<level> — sets the max width, in characters, for options inside option lists 💅. Any option that's longer than this will just take over a whole row of the table that renders the list (it's giving main character energy, honestly). Default is 14 characters. Pass 0 and you get no limit at all ✨.

🦋 S5 Slideshow Specific Options 🦋

okay so this is the part where we talk S5, and for the S5/HTML writer there's one thing you need to know up front, bestie:

For the S5/HTML writer, the --no-toc-backlinks option (defined in General Docutils Options above) is the default, and should not be changed. 🫶 Don't touch it. It's perfect. Leave it alone.
  • --theme=<name> — pick an installed S5 theme by name 🌸. This one overrides --theme-url. The default theme name is default. The theme files get copied into a ui/<theme> directory, sitting in the same directory as the destination file (that's your output HTML). ⚠️ Heads up though: existing theme files will not be overwritten (unless --overwrite-theme-files is used — more on that below).
  • --theme-url=<URL> — point at an S5 theme by URL 🔗. The destination file (output HTML) will just link to this theme; nothing gets copied at all, no cap. This one overrides --theme.
  • --overwrite-theme-files — lets existing theme files in the ui/<theme> directory get overwritten ✨. The default is to not overwrite theme files, so this is you actively choosing chaos (respectfully).
  • --keep-theme-files — keeps whatever theme files are already sitting in the ui/<theme> directory, and does not overwrite any of them 💖. This is the default, bestie. Chill behaviour.
  • --view-mode=<mode> — sets the initial view mode. Your choices are "slideshow" [default] or "outline" 👑. Pick your vibe.
  • --hidden-controls — normally hides the presentation controls while you're in slideshow mode 🙈. This is the default.
  • --visible-controls — always shows the presentation controls in slideshow mode ✨. The default is to hide the controls, so this is you saying "actually, I want to see them."
  • --current-slide — turns on the current slide indicator, which looks like "1 / 15" 🔥. The default is to keep it disabled.
  • --no-current-slide — turns the current slide indicator off 💅. This is the default.

and that's the whole page, bestie 🎀 you made it to the very end, which is lowkey iconic of you. the footer down there just says rst2s5(1) — that's the manual page name, and it's all it signs off with (no version number, no date, just the page title keeping it mysterious 🦋). go forth and make slides ✨👑💜

📦 where this page comes from