rst2pdf(1)

🌸 rst2pdf — the manual, but make it a group chat 🌸

okay so bestie, welcome to rst2pdf(1) — that's the text processing section of your manual pages, and yes this lil tool is the moment. sit down, hydrate, we're converting docs to PDFs and we're doing it directly, no LaTeX detour, no drama 💅

---

✨ SYNOPSIS ✨

rst2pdf [options] [input] [-o output]

that's it. that's the whole vibe. input goes in, PDF comes out 🦋

---

💖 DESCRIPTION 💖

so the usual way people make a PDF out of a reStructuredText (ReST) document is by routing the whole thing through LaTeX. which, fine, okay, it works. but rst2pdf said not me being basic and does it a whole different way: it builds the PDF directly, using the ReportLab library. no LaTeX middleman, no cap 🔥

---

👑 OPTIONS 👑

every single flag, no skips, we're thorough here because that's the energy:

• -h, --help — shows this help message and then exits, king behavior 🫶
• --config=FILE — the config file to use. Default is ~/.rst2pdf/config
• -o FILE, --output=FILE — write the PDF to FILE
• -s STYLESHEETS, --stylesheets=STYLESHEETS — a comma-separated list of custom stylesheets. Default is ""
• --stylesheet-path=FOLDERLIST — a colon-separated list of folders to search for stylesheets. Default is ""
• -c, --compressed — create a compressed PDF. Default is False
• --print-stylesheet — prints the default stylesheet and exits
• --font-folder=FOLDER — search this folder for fonts. (Deprecated) okay so this one is deprecated, noted, moving on
• --font-path=FOLDERLIST — a colon-separated list of folders to search for fonts. Default is ""
• --baseurl=URL — the base URL used for relative URLs
• -l LANG, --language=LANG — the language used for hyphenation and docutils localization. Default is None
• --header=HEADER — page header, but only if the document itself doesn't specify one
• --footer=FOOTER — page footer, same deal, only if the document doesn't specify one
• --section-header-depth=N — sections up to this depth get used in the header and footer's replacement of ###Section###. Default is 2
• --smart-quotes=VALUE — tries to convert ASCII quotes, ellipsis and dashes into the typographically correct equivalent. Default is 0

the possible values, and bestie listen, this is a whole numbered saga:

1. Suppress all transformations. (Do nothing.) literally nothing happens ✋
2. Performs default SmartyPants transformations: quotes (including backticks-style), em-dashes, and ellipses. "--" (dash dash) is used to signify an em-dash; there is no support for en-dashes.
3. Same as --smart-quotes=1, except that it uses the old-school typewriter shorthand for dashes: "--" (dash dash) for en-dashes, "---" (dash dash dash) for em-dashes.
4. Same as --smart-quotes=2, but inverts the shorthand for dashes: "--" (dash dash) for em-dashes, and "---" (dash dash dash) for en-dashes.

wait, careful — the list above is numbered 0 through 3 in the original (0, 1, 2, 3), so VALUE really does start at 0 for "do nothing". don't get it twisted 💀

• --fit-literal-mode=MODE — what to do when a literal is too wide. one of error, overflow, shrink, truncate. Default is "shrink"
• --fit-background-mode=MODE — how to fit the background image to the page. one of scale, scale_width or center. Default is "center"
• --inline-links — shows the target between parenthesis instead of as an active link
• --repeat-table-rows — repeats the header row for each splitted table
• --raw-html — support embedding raw HTML. Default: False
• -q, --quiet — print less information
• -v, --verbose — print debug information
• --very-verbose — print even more debug information 👀
• --version — print version number and exit
• --no-footnote-backlinks — disable footnote backlinks. Default: False
• --inline-footnotes — show footnotes inline. Default: True
• --default-dpi=NUMBER — DPI for objects sized in pixels. Default is 300
• --show-frame-boundary — show frame borders (only useful for debugging). Default is False
• --disable-splittables — don't use splittable flowables in some elements. only try this if you literally cannot process a document any other way, it's the last-resort button 🚨
• -b LEVEL, --break-level=LEVEL — maximum section level that starts in a new page. Default: 0
• --first-page-on-right — when using double sided pages, the first page will start on the right hand side. (Book Style)
• --blank-first-page — add a blank page at the beginning of the document
• --break-side=VALUE — how section breaks work. can be "even", and sections start in an even page, "odd", and sections start in odd pages, or "any" and sections start in the next page, be it even or odd. See also the -b option.
• --date-invariant — don't store the current date in the PDF. useful mainly for the test suite, where we don't want the PDFs to change
• -e EXTENSIONS — alias for --extension-module
• --extension-module=EXTENSIONS — add a helper extension module to this invocation of rst2pdf (module must end in .py and be on the python path)
• --custom-cover=FILE — template file used for the cover page. Default: cover.tmpl
• --use-floating-images — makes images with :align: attribute work more like in rst2html. Default: False
• --use-numbered-links — when using numbered sections, adds the numbers to all links referring to the section headers. Default: False
• --strip-elements-with-class=CLASS — remove elements with this CLASS from the output. can be used multiple times
• --record-dependencies=FILE — write output file dependencies to FILE

---

🌈 EXAMPLES 🌈

okay here's the iconic one-liner:

$ rst2pdf rest.txt -o out.pdf

it produces an out.pdf file which is a PDF version of the ReST document rest.txt. that's the whole trick, no notes, ate and left no crumbs 💖

---

🎀 Author 🎀

Chris Lamb <chris@chris-lamb.co.uk> for the Debian project 🫡

---

and that's the page bestie! this was rst2pdf(1) — manual name rst2pdf, in the text processing section, footer also reading rst2pdf(1) (so you always know where you are when you scroll back up 💅). go make some PDFs, you're gonna slay ✨🦋🌸