RONN-FORMAT(7)

🌸 RONN-FORMAT(7) 🌸

okay bestie, welcome to ronn-format — the manual authoring format based on Markdown, straight out of the Ronn Manual. this is the whole vibe, no gatekeeping 💖

---

✨ NAME ✨

ronn-format — manual authoring format based on Markdown 🎀

---

✨ SYNOPSIS ✨

name(1) -- short, single-sentence description
=============================================

## SYNOPSIS

`name` [<optional>...] <flags>

## DESCRIPTION

A normal paragraph. This can span multiple lines and is terminated with two
or more line endings -- just like Markdown.

Inline markup for `code`, `user input`, and **strong** are displayed
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
(HTML) or underline (roff).

Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
HTML output.

Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
TEXT][#SEE-ALSO].

Definition lists:

  * `-a`, `--argument`=[<value>]:
    One or more paragraphs describing the argument.

  * You can put whatever you *want* here, really:
    Nesting and paragraph spacing are respected.

Frequently used sections:

## OPTIONS
## SYNTAX
## ENVIRONMENT
## RETURN VALUES
## STANDARDS
## SECURITY CONSIDERATIONS
## BUGS
## HISTORY
## AUTHOR
## COPYRIGHT
## SEE ALSO

---

✨ DESCRIPTION ✨

so, the ronn(1) command converts text in a simple markup into Unix manual pages. the syntax has all the Markdown formatting features, plus conventions for expressing the structure and the various notations that show up in standard Unix manpages. it's giving "Markdown but make it manpage" 💅

heads up though: not all roff(7) typesetting features can be expressed using ronn syntax. like, some of them just don't translate, no cap 😭

---

✨ MANPAGE TITLE ✨

every manpage has a name, a section, and a one-line description. and bestie, the file has to start with a level one heading defining these attributes:

ls(1) -- list directory contents
================================

that right there tells you the manpage is named ls in manual section 1 (which is "user commands"). periodt 👑

---

✨ SECTION HEADINGS ✨

man section headings get expressed with markdown level two headings. there are two syntaxes for level two headings, pick your fighter:

Hash prefix syntax:

## HEADING TEXT

Dash underline syntax:

HEADING TEXT
------------

and the rules: section headings should be all uppercase and may not contain inline markup. sorry, no bolded headings, the format said no 🙈

---

✨ INLINE MARKUP ✨

manpages have a limited set of text formatting capabilities — basically it's boldface and italics (which are often displayed using underline). ronn uses these bits of markdown(7) to pull that off:

• `backticks` (markdown compatible) — code, flags, commands, and noun-like things; typically displayed in boldface. all text included within backticks is displayed literally; other inline markup is not processed. HTML output: <code>.
• **double-stars** (markdown compatible) — also displayed in boldface. unlike backticks, inline markup is processed. HTML output: <strong>.
• <anglequotes> (non-compatible markdown extension) — user-specified arguments, variables, or user input. typically displayed with underline in roff output. HTML output: <var/>.
• _underbars_ (markdown compatible) — emphasis. may be used for literal option values. typically displayed with underline in roff output. HTML output: <em>.

here's grep(1)'s DESCRIPTION section represented in ronn, as a lil treat:

`Grep` searches the named input <FILE> (or standard input if
no files are named, or the file name `-` is given) for lines
containing a match to the given <PATTERN>. By default, `grep`
prints the matching lines.

---

✨ DEFINITION LISTS ✨

the definition list syntax is compatible with markdown's unordered list syntax but it requires that the first line of each list item be terminated with a colon ":" character. the contents of that first line is the term; the subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists. obsessed, honestly 🫶

here's an example definition list, taken from BSD test(1)'s DESCRIPTION section:

The following primaries are used to construct expressions:

  * `-b` <file>:
    True if <file> exists and is a block special file.

  * `-c` <file>:
    True if _file_ exists and is a character special file.

  * `-d` <file>:
    True if file exists and is a directory.

---

✨ LINKS ✨

all markdown(7) linking features are supported. yes, all of them ✨

markdown reference-style links can be used to link to specific sections by name:

## SECTION 1

See the following section.

## SECTION 2

See [SECTION 1][] or [to put it another way][SECTION 1].

the anchor name would be #SECTION-1 and #SECTION-2. and the way it works: all non-word characters are removed and spaces are replaced by dashes. iykyk 💅

---

✨ SEE ALSO ✨

ronn(1), markdown(7), roff(7)

---

and that's the whole page, bestie!! this was Ronn-NG 0.10.1, dated January 2024, and it's literally called RONN-FORMAT(7) in case you forgot where you were 💖 go write some gorgeous manpages, you've got this 🎀🦋🌸