CM2MAN(1)

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

✨ CM2MAN(1) — bestie edition ✨

okay so this is cm2man, and it ships with the recommonmark Python package 🐍 (Debian's 0.7.1+ds-5 build, February 2023, for the record 👀). Sit down, grab a strawberry 🍓, and let's get you fluent.

💖 NAME 💖

cm2man — convert a CommonMark file into a man page. that's the whole job. she does one thing and she slays it 💅

🌸 SYNOPSIS 🌸

cm2man [options] [<source> [<destination>]]

🦋 DESCRIPTION 🦋

So basically: you hand her markdown, she hands you back a manpage. iconic behaviour fr fr.

She reads from <source> — and if you don't give her one, she just reads from stdin like the low-maintenance queen she is. She writes to <destination>, and if you don't give her one of those either, it's stdout, no cap.

💡 if you want the full settings reference — like, the deep lore — go look at https://docutils.sourceforge.io/docs/user/config.html. she is not gatekeeping, she is literally linking it.

👑 OPTIONS 👑

🌈 General Docutils Options 🌈

  • --title=TITLE — sets the document title as metadata. name her, bestie.
  • --generator, -g — drops in a "Generated by Docutils" credit and a link, so everyone knows who did it.
  • --no-generator — no generator credit. she's staying mysterious 🙈
  • --date, -d — sticks the date at the end of the document (UTC).
  • --time, -t — sticks the time & date (UTC) on there. timestamp queen ⏰
  • --no-datestamp — no datestamp of any kind. zero. none. gone.
  • --source-link, -s — adds a "View document source" link.
  • --source-url=<URL> — use <URL> for that source link; heads up, this implies --source-link automatically.
  • --no-source-link — no "View document source" link. she's not sharing her sources 💀
  • --toc-entry-backlinks — links from section headers back to TOC entries. (this is the default, so it's already the vibe ✨)
  • --toc-top-backlinks — links from section headers to the top of the TOC instead.
  • --no-toc-backlinks — kills backlinks to the table of contents entirely. brutal. periodt.
  • --footnote-backlinks — links from footnotes/citations to references. (default 🫶)
  • --no-footnote-backlinks — no backlinks from footnotes and citations.
  • --section-numbering — turns on section numbering, done by Docutils. (default!)
  • --no-section-numbering — turns section numbering off. goodbye numbers 🔢
  • --strip-comments — removes comment elements from the document tree.
  • --leave-comments — leaves comment elements in the tree. (default 🌸)
  • --strip-elements-with-class=<class> — nukes every element with classes="<class>" from the document tree.
⚠️ warning: potentially dangerous; use with caution. and it's 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 above <level>. your choices are: "info" or "1", "warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5".
  • --verbose, -v — report all system messages. (same as "--report=1".) she's telling you everything, bestie 🗣️
  • --quiet, -q — report no system messages. (same as "--report=5".) silence. zen. 🧘
  • --halt=<level> — halt execution at system messages at or above <level>. levels work like in --report. default: 4 (severe).
  • --strict — halt at the slightest problem. same as "--halt=info". she is not playing around 😤
  • --exit-status=<level> — enables a non-zero exit status for non-halting system messages at or above <level>. default: 5 (which means disabled).
  • --debug — enables debug-level system messages and diagnostics. detective mode 🔍
  • --no-debug — disables debug output. (default)
  • --warnings=<file> — sends the output of system messages to <file>.
  • --traceback — enables Python tracebacks when Docutils is halted.
  • --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]> — specify the text encoding and optionally the error handler for output. 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]> — specify text encoding and optionally an error handler for error output. default text encoding: system encoding. default error handler: backslashreplace.
  • --error-encoding-error-handler=ERROR_ENCODING_ERROR_HANDLER — the error handler for unencodable characters in error output. default: backslashreplace.
  • --language=<name>, -l <name> — 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 doesn't exist, no drama, she moves on 💜)
  • --version, -V — show this program's version number and exit.
  • --help, -h — show this help message and exit. the classic 🎀

🧚 Generic Parser Options 🧚

  • --no-file-insertion — disables directives that insert the contents of an external file; they get replaced with a "warning" system message.
  • --file-insertion-enabled — enables those external-file-inserting directives. (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 maximal number of characters in an input line. default 10 000. that's a lot of characters, bestie 😭

💜 Standalone Reader Options 💜

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

🌟 AUTHOR 🌟

Steve Genoud and Luca Barbato — the duo behind all this. shoutout 🫶

Copyright (C) 2014 Steve Genoud and Luca Barbato

and that's the whole page, bestie 💖 you are now officially fluent in cm2man. go make some manpages, main character energy only.

— written by the lovely people behind recommonmark, Debian build 0.7.1+ds-5, February 2023. thanks for coming to her TED talk 🎀💅

📦 where this page comes from