CM2LATEX(1)

📦
version 0.7.1 · 4 versions
, in debian bookworm, ubuntu noble

💅 cm2latex(1) 💅

okay so bestie, you found it — this is the manual page for cm2latex, straight outta the recommonmark Python package. It's giving "I write Markdown but I need LaTeX energy" and honestly? Iconic. Sit down, grab a 🍓, let's get into it.

✨ NAME ✨

cm2latex — convert CommonMark file to LaTeX source 🦋

🎀 SYNOPSIS 🎀

cm2latex [options] [<source> [<destination>]]

💖 DESCRIPTION 💖

So the whole vibe is: you feed it Markdown, it hands you a LaTeX document. Main character behavior fr fr.

It reads from <source> — and plot twist, if you don't give it a source, it just reads from stdin like a chill little gremlin. And it writes to <destination>, but if you don't specify one? stdout, babe. Periodt.

If you want the full settings reference (and there are SO many settings, I'm not even kidding), go look at:

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

👑 OPTIONS 👑

Okay this is the long part and I need you to stay with me. Every single flag is here, no skips, no shortcuts. 💅

🌸 General Docutils Options: 🌸

  • --title=TITLE — set the document title, but as metadata, not as a big dramatic header. It's the quiet title. The mysterious title. 🙈
  • --generator, -g — adds a cute little "Generated by Docutils" credit and link. Give credit where credit is due, bestie. ✨
  • --no-generator — nope, no generator credit. You're keeping it lowkey.
  • --date, -d — slaps the date at the end of the document (UTC).
  • --time, -t — slaps the time and date at the end (UTC). Fancier.
  • --no-datestamp — no datestamp of any kind. None. Zero. Not a crumb. 💀
  • --source-link, -s — adds a "View document source" link so people can peek behind the curtain.
  • --source-url=<URL> — use <URL> for that source link. Heads up: this implies --source-link all on its own.
  • --no-source-link — no "View document source" link. The curtain stays closed. 🎭
  • --toc-entry-backlinks — links go from section headers back to TOC entries. (default)
  • --toc-top-backlinks — links go from section headers to the top of the TOC instead.
  • --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.
  • --section-numbering — Docutils numbers your sections. (default) Slay.
  • --no-section-numbering — Docutils does not number your sections.
  • --strip-comments — yeets comment elements out of the document tree. 🧹
  • --leave-comments — leaves comment elements right where they are. (default)
  • --strip-elements-with-class=<class> — removes every element with classes="<class>" from the document tree. > ⚠️ Warning: potentially dangerous; use with caution. Also: this is a multiple-use option, so you can stack it. 💀
  • --strip-class=<class> — removes all classes="<class>" attributes from elements in the document tree. > ⚠️ Warning: potentially dangerous; use with caution. Also a multiple-use option.
  • --report=<level>, -r <level> — report system messages at or higher than <level>. Your menu of levels: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5".
  • --verbose, -v — report all system messages. Literally the same as "--report=1". Spill everything. 🗣️
  • --quiet, -q — report no system messages at all. Same as "--report=5". Silence. 🤫
  • --halt=<level> — stop execution at system messages at or above <level>. Same level menu as --report. Default: 4 (severe).
  • --strict — halt at the slightest problem. Same as "--halt=info". She's sensitive, okay? 😭
  • --exit-status=<level> — turn on 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. For when you wanna see everything. 👀
  • --no-debug — disables debug output. (default)
  • --warnings=<file> — send the output of system messages to <file>.
  • --traceback — enables Python tracebacks when Docutils halts. The full dramatic backtrace. 🎬
  • --no-traceback — disables Python tracebacks. (default)
  • --input-encoding=<name[:handler]>, -i <name[:handler]> — specify the encoding, and optionally the error handler, for input text. Default: <auto-detect>:strict.
  • --input-encoding-error-handler=INPUT_ENCODING_ERROR_HANDLER — the error handler for undecodable characters. Choices: "strict" (default), "ignore", and "replace".
  • --output-encoding=<name[:handler]>, -o <name[:handler]> — the text encoding for output, plus optionally its error handler. Default: utf-8:strict.
  • --output-encoding-error-handler=OUTPUT_ENCODING_ERROR_HANDLER — error handler for unencodable output characters: "strict" (default), "ignore", "replace", "xmlcharrefreplace", "backslashreplace".
  • --error-encoding=<name[:handler]>, -e <name[:handler]> — text encoding and optionally the error handler for error output. Default text encoding: the system encoding. Default error handler: backslashreplace.
  • --error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER — error handler for unencodable characters in error output. Default: backslashreplace.
  • --language=<name>, -l <name> — pick the language (as a BCP 47 language tag). Default: en.
  • --record-dependencies=<file> — writes output file dependencies into <file>. Receipts. 🧾
  • --config=<file> — reads configuration settings from <file>... but only if it exists. No file, no drama.
  • --version, -V — show the program's version number and dip. 👋
  • --help, -h — show this help message and dip.

🌈 Generic Parser Options: 🌈

  • --no-file-insertion — disables directives that insert the contents of an external file. Instead you get a "warning" system message. Sorry bestie. 😭
  • --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 max number of characters in an input line. Default 10 000.

🦋 Standalone Reader Options: 🦋

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

💜 LaTeX-Specific Options: 💜

Okay this section is the whole personality of the page, buckle up. 🎀

  • --documentclass=DOCUMENTCLASS — specify the LaTeX documentclass. Default: "article".
  • --documentoptions=DOCUMENTOPTIONS — specify document options. You can give multiple, separated by commas. Default: "a4paper".
  • --footnote-references=<format> — the format for footnote references: either "superscript" or "brackets". Default: "superscript".
  • --use-latex-citations — use the \cite command for citations. (future default) 👀
  • --figure-citations — use figure floats for citations. Heads up: it might get mixed with real figures. (provisional default)
  • --attribution=<format> — format for block quote attributions: "dash" (em-dash prefix), "parentheses"/"parens", or "none". Default: "dash".
  • --stylesheet=<file[,file,...]> — specify LaTeX packages/stylesheets. A style gets referenced with "\usepackage" if the extension is ".sty" or omitted, and with "\input" otherwise. This overrides previous --stylesheet and --stylesheet-path settings. 💥
  • --stylesheet-path=<file[,file,...]> — a comma separated list of LaTeX packages/stylesheets. Relative paths get expanded if a matching file is found in the --stylesheet-dirs. With --linkstylesheet, the path is rewritten relative to the output *.tex file.
  • --link-stylesheet — link to the stylesheet(s) in the output file. (default)
  • --embed-stylesheet — embed the stylesheet(s) in the output file. Note: stylesheets must be accessible during processing.
  • --stylesheet-dirs=<dir[,dir,...]> — comma-separated list of directories where stylesheets are found. Used by --stylesheet-path when expanding relative path arguments. Default: ".".
  • --latex-preamble=LATEX_PREAMBLE — customization via LaTeX code in the preamble. Default: select PDF standard fonts (Times, Helvetica, Courier).
  • --template=<file> — specify the template file. Default: "default.tex".
  • --use-latex-toc — table of contents by LaTeX. (default)
  • --use-docutils-toc — table of contents by Docutils (no page numbers, soz).
  • --use-part-section — add parts on top of the section hierarchy.
  • --use-docutils-docinfo — attach author and date to the document info table. (default)
  • --use-latex-docinfo — attach author and date to the document title instead.
  • --topic-abstract — typeset the abstract as a topic. (default)
  • --use-latex-abstract — use the LaTeX abstract environment for the document's abstract.
  • --hyperlink-color=HYPERLINK_COLOR — the color of any hyperlinks embedded in text. Default: "blue" (use "false" to disable).
  • --hyperref-options=HYPERREF_OPTIONS — extra options for the "hyperref" package.
  • --compound-enumerators — enable compound enumerators for nested enumerated lists (like "1.2.a.ii"). Cute, right? ✨
  • --no-compound-enumerators — disable compound enumerators for nested enumerated lists. (default)
  • --section-prefix-for-enumerators — enable section ("." subsection ...) prefixes for compound enumerators. Careful: this has no effect without --compound-enumerators.
  • --no-section-prefix-for-enumerators — disable section prefixes for compound enumerators. (default)
  • --section-enumerator-separator=<char> — set the separator between the section number and the enumerator for compound enumerated lists. Default: "-".
  • --literal-block-env=LITERAL_BLOCK_ENV — when possible, use the specified environment for literal-blocks. Default: "" (falls back to "alltt").
  • --use-verbatim-when-possible — deprecated alias for "--literal-block-env=verbatim". It's giving legacy, bestie. 🫠
  • --table-style=<format> — table style. "standard" gets horizontal and vertical lines, "booktabs" (LaTeX booktabs style) gets only horizontal lines above and below the table and below the header, or "borderless". Default: "standard".
  • --graphicx-option=GRAPHICX_OPTION — LaTeX graphicx package option. Possible values are "dvipdfmx", "dvips", "dvisvgm", "luatex", "pdftex", and "xetex". Default: "".
  • --font-encoding=FONT_ENCODING — LaTeX font encoding. Possible values are "", "T1" (default), "OT1", "LGR,T1" or any other combination of options to the fontenc package.
  • --reference-label=REFERENCE_LABEL — by default the latex-writer puts the reference title into hyperreferences. Specify "ref*" or "pageref*" to get the section number or the page number instead.
  • --use-bibtex=USE_BIBTEX — specify style and database for bibtex, for example "--use-bibtex=mystyle,mydb1,mydb2".
  • --legacy-class-functions — bestie, this one goes old school: it uses the legacy functions with a class value list for \DUtitle and \DUadmonition. Retro vibes 💅
  • --new-class-functions — the glow-up option ✨ it uses \DUrole and "DUclass" wrappers for class values, and it tucks your admonition content inside an environment. This is the default, so it's already what you're getting unless you say otherwise.
  • --legacy-column-widths — uses the legacy algorithm to figure out table column widths. It's the provisional default rn, so like… it's what happens, but it's not forever, ok? 🙈
  • --new-column-widths — uses the new algorithm for table column widths. It's the future default 👑 so get familiar, the algorithm is in its main character era.
  • --docutils-footnotes — footnotes get numbers/symbols, courtesy of Docutils. This is the default 🎀
heads up bestie: the alternative to that last one, --latex-footnotes, is not implemented yet 😭 so don't come for it, it literally does not exist yet.

💖 AUTHOR 💖

Steve Genoud and Luca Barbato 🫶

Copyright (C) 2014 Steve Genoud and Luca Barbato

and that's the whole page, bestie, you made it to the end 🎉 this gorgeous lil doc comes from recommonmark, Debian 0.7.1+ds-5, dated February 2023 — iconic behavior, fr fr. now go convert some markdown to LaTeX, you've got this 💅✨

📦 where this page comes from