RONN-FORMAT(7) Ronn Manual RONN-FORMAT(7)
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
The ronn(1) command converts text in a simple markup to UNIX manual pages. The syntax includes all Markdown formatting features, plus con-
ventions for expressing the structure and various notations present in standard UNIX manpages.
Not all roff(7) typesetting features can be expressed using ronn syntax.
MANPAGE TITLE
Manpages have a name, section, and a one-line description. Files must start with a level one heading defining these attributes:
ls(1) -- list directory contents
================================
Indicates that the manpage is named ls in manual section 1 (
SECTION HEADINGS
Man section headings are expressed with markdown level two headings. There are two syntaxes for level two headings.
Hash prefix syntax:
## HEADING TEXT
Dash underline syntax:
HEADING TEXT
------------
Section headings should be all uppercase and may not contain inline markup.
INLINE MARKUP
Manpages have a limited set of text formatting capabilities. There's basically boldface and italics (often displayed using underline). Ronn
uses the following bits of markdown(7) to accomplish this:
`backticks` (markdown compatible)
Code, flags, commands, and noun-like things; typically displayed in 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 is grep(1)'s DESCRIPTION section represented in ronn:
`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 requires that the first line of each list item be termi-
nated with a colon
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.
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. All non-word characters are removed and spaces are replaced by dashes.
SEE ALSO
ronn(1), markdown(7), roff(7)
Ronn 0.7.0 June 2010 RONN-FORMAT(7)