RONN(1)

💅 RONN(1) — the Ronn Manual ✨

okay bestie, buckle up 💖 this is ronn, and she's about to turn your cute little markdown files into actual Unix manpages. no cap. let's get into it.

---

🎀 NAME

ronn — convert markdown files to manpages 🦋

---

🌸 SYNOPSIS

ronn [format...] file...
ronn -m|--man file...
ronn -S|--server file...
ronn --pipe file
ronn < file
ronn -E|--encoding encoding ...

---

✨ DESCRIPTION

So like, ronn converts textfiles into standard roff-formatted Unix manpages or HTML. ronn-format(7) is based on markdown(7), but it's got extra rules and syntax bolted on that are geared toward authoring manuals. it's giving "markdown but make it manpage". 👑

In its default mode, ronn converts one or more input files to HTML or roff output files. The --roff, --html, and --fragment options dictate which output files are generated. Multiple format arguments may be specified to generate multiple output files. Output files are named after — and written to — the same directory as the input files. lowkey tidy of her. 🧚

The --server and --man options change the output behavior from file generation to serving dynamically generated HTML manpages, or viewing the file as with man(1).

With no file arguments, ronn acts as a simple filter. Ronn source text is read from standard input and roff output is written to standard output. Use the --html, --roff, and/or --fragment options to select the output format. 🫶

---

🦋 FILES

The ronn command expects input to be valid ronn-format(7) text. Source files are typically named name.section.ronn (e.g., example.1.ronn). The name and section should match the name and section defined in the file's heading. fr fr, keep them matching or it's gonna be weird. 😭

Source files must be in UTF-8 encoding, or the encoding specified by the -E/--encoding option, regardless of the locale that ronn is running under. periodt.

When building roff or HTML output files, destination filenames are determined by taking the basename of the input file and adding the appropriate file extension (or removing the file extension in the case of roff output). For example, executing ronn example.1.ronn generates example.1 with roff output and example.1.html with HTML output. the way she just knows where to put things 💅

---

🌈 OPTIONS

These options control whether output is written to file(s), standard output, or directly to a man pager. main character energy, honestly.

• -m, --man — Don't generate files, display files as if man(1) were invoked on the roff output file. This simulates default man behavior by piping the roff output through groff(1) and the paging program specified by the MANPAGER environment variable.
• -S, --server — Don't generate files, start an HTTP server at http://localhost:1207/ and serve dynamically generated HTML for the set of input files. A file named example.2.ronn is served as /example.2.html. There's also an index page at the root with links to each file. 🔥

The server respects the --style and document attribute options (--manual, --date, etc.). These same options can be varied at request time by giving them as query parameters: ?manual=FOO&style=dark,toc

NOTE: The builtin server is designed to assist in the process of writing and styling manuals. It is in no way recommended as a general purpose web server. not me warning you twice 🚨 do NOT deploy this thing to prod, bestie.

• --port=port — When used with -S/--server, runs the server at the specified port instead of the default port 1207.
• --pipe — Don't generate files, write generated output to standard output. This is the default behavior when ronn source text is piped in on standard input and no file arguments are provided.
• -o=directory, --output-dir=directory — Write generated files to the specified directory instead of the default location.
• -E=encoding, --encoding=encoding — Specify the encoding that input files are in. Default is UTF-8, regardless of user's locale settings. Input sent to STDIN is always treated as UTF-8, regardless of whether -E is passed. she said locale who? don't know her. 💀

Format options control the files ronn generates, or the output format when the --pipe argument is specified. When no format options are given, both --roff and --html are assumed. (generous queen 🎀)

• -r, --roff — Generate roff output. This is the default behavior when no files are given and ronn source text is read from standard input.
• -5, --html — Generate output in HTML format.
• -f, --fragment — Generate output in HTML format but only the document fragment, not the header, title, or footer.

Document attributes displayed in the header and footer areas of generated content are specified with these options. (These values may also be set via the ENVIRONMENT.)

• --manual=manual — The name of the manual this man page belongs to; manual is prominently displayed top-center in the header area.
• --organization=name — The name of the group, organization, or individual responsible for publishing the document; name is displayed in the bottom-left footer area.
• --date=date — The document's published date; date must be formatted YYYY-MM-DD and is displayed in the bottom-center footer area. The file mtime is used when no date is given, or the current time when no file is available.

HTML output can be customized through the use of CSS stylesheets: 💖

• --style=module[,module]... — The list of CSS stylesheets to apply to the document. Multiple module arguments may be specified, but must be separated by commas or spaces.

When module is a simple word, search for files named module.css in all directories listed in the RONN_STYLE environment variable, and then search internal styles.

When module includes a / character, use it as the full path to a stylesheet file.

Internal styles are man (included by default), toc, and 80c. See STYLES for descriptions of features added by each module.

Miscellaneous options: ✨

• -w, --warnings — Show troff warnings on standard error when performing roff conversion. Warnings are most often the result of a bug in ronn's HTML to roff conversion logic.
• -W — Disable troff warnings. Warnings are disabled by default. This option can be used to revert the effect of a previous -w argument.
• -v, --version — Show ronn version and exit. bye bestie 👋

---

🔗 LINK INDEXES

When generating HTML output, ronn hyperlinks manual references (like grep(1), ls(1), markdown(7)) in source text based on reference name to URL mappings defined in an index.txt file. Each line of the index file describes a single reference link, with whitespace separating the reference's id from its location. Blank lines are allowed; lines beginning with a # character are ignored:

# manuals included in this project:
whisky(1)    whisky.1.ronn
tango(5)     tango.5.ronn

# external manuals
grep(1)      https://man7.org/linux/man-pages/man1/grep.1.html
ls(1)        https://man7.org/linux/man-pages/man1/ls.1.html

# other URLs for use with markdown reference links
src          https://github.com/

The location is an absolute or relative URL that usually points at an HTML version of manpage. It's possible to define references for things that aren't manpages. 👀 yes she's flexible like that.

All manuals in an individual directory share the references defined in that directory's index.txt file. Index references may be used explicitly in Markdown reference style links using the syntax: [text][id], where text is the link text and id is a reference name defined in the index. iykyk 🫶

---

🎨 STYLES

The --style option selects a list of CSS stylesheets to include in the generated HTML. Styles are applied in the order defined, so each can use the cascade to override previously defined styles. it's giving layers, it's giving drama, we love her. 💅

🧁 Builtin Stylesheets

These styles are included with the distribution:

• man — Basic manpage styles: typography, definition lists, indentation. This is always included regardless of --style argument. It is however possible to replace the default man module with a custom one by placing a man.css file on the RONN_STYLE path.
• print — Basic print stylesheet. The generated <style> tag includes a media=print attribute.
• toc — Enables the Table of Contents navigation. The TOC markup is included in generated HTML by default but hidden with an inline display:none style rule; the toc module turns it on and applies basic TOC styles.
• dark — Light text on a dark background. 🖤 the aesthetic is immaculate.
• 80c — Changes the display width to mimic the display of a classic 80 character terminal. The default display width causes lines to wrap at a gratuitous 100 characters. (a gratuitous 100?? she said absolutely not 😭)

🪄 Custom Stylesheets

Writing custom stylesheets is straight-forward. The following core selectors allow targeting all generated elements:

• .mp — The manual page container element. Present on full documents and document fragments.
• body#manpage — Signifies that the page was fully-generated by Ronn and contains a single manual page (.mp element).
• .man-decor — The three-item heading and footing elements both have this class.
• .man-head, .man-foot — The heading and footing, respectively.
• .man-title — The main <h1> element. Hidden by default unless the manual has no name or section attributes.

See the builtin style sources https://github.com/apjanke/ronn-ng/tree/main/lib/ronn/template for examples. go peek, she doesn't gatekeep ✨

---

🌟 EXAMPLES

Build roff and HTML output files and view the roff manpage using man(1):

$ ronn some-great-program.1.ronn
roff: some-great-program.1
html: some-great-program.1.html
$ man ./some-great-program.1

Build only the roff manpage for all .ronn files in the current directory:

$ ronn --roff *.ronn
roff: mv.1
roff: ls.1
roff: cd.1
roff: sh.1

Build only the HTML manpage for a few files and apply the dark and toc stylesheets:

$ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
html: mv.1.html
html: ls.1.html

Generate roff output on standard output and write to file:

$ ronn <hello.1.ronn >hello.1

View a ronn file in the same way as man(1) without building a roff file:

$ ronn --man hello.1.ronn

Serve HTML manpages at http://localhost:1207/ for all *.ronn files under a man/ directory:

$ ronn --server man/*.ronn
$ open http://localhost:1207/

---

🌿 ENVIRONMENT 🌿

okay bestie, these are the lil environment variables that whisper sweet nothings into ronn's ear before it even reads your command line 💖 they're like the preset vibes of your shell. let's go one by one:

• RONN_MANUAL — the default manual name that shows up all cute in the top-center header area. and listen: the --manual option is the main character here, it takes precedence over this value. 💅
• RONN_ORGANIZATION — the default manual publishing group, organization, or individual (yes, you can be a solo icon 👑) displayed down in the bottom-left footer area. same deal — --organization overrules it.
• RONN_DATE — the default manual date, and it MUST be in YYYY-MM-DD format, no cap. it gets displayed in the bottom-center footer area. and yup, --date takes precedence over it too.
• RONN_STYLE — a PATH-style list of directories to check for stylesheets that get handed to the --style option. directories are separated by a :, and blank entries are just ignored (we don't see them, we don't care 🙈). use . if you wanna include the current working directory. 🎀
• MANPAGER — the paging program used for man pages. typically set to something like 'less -is'. it's giving classic. ✨
• PAGER — used instead of MANPAGER when MANPAGER isn't defined. the backup bestie. 🫶

---

📜 COPYRIGHT 📜

fr fr, credit where credit is due:

Ronn-NG is Copyright (C) 2009 Ryan Tomayko https://tomayko.com/about, (C) 2018-2023 Andrew Janke https://apjanke.net, and other contributors. See the AUTHORS file in the Ronn-NG distribution for full details.

like, there are receipts. go read the AUTHORS file if you want the whole guest list. 🌸

---

👀 SEE ALSO 👀

go be nosy, bestie, these are all iconic in their own right:

groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn-format(7)

---

and that's the whole page, no crumbs left 🍓 you read a full man page and that's genuinely main character behavior.

this one's from Ronn-NG 0.10.1, dated January 2024, and it lives under the name RONN(1). slay, go write some docs 💖✨🦋