ronn(5) -- humane manual page authoring format
==============================================

## SYNOPSIS

    name(1) -- one sentence description
    ===================================

    ## SECTION HEADING

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

    ## INLINE MARKUP

    Inline markup is used for `code` and `user input` (displayed
    in boldface), and also <variables> or _emphasis_.

    Manual page references like sh(1), markdown(5), roff(7), etc.
    are displayed in boldface and hyperlinked in HTML output.

    ## DEFINITION LISTS

    Definition lists are used to define options, arguments,
    variables, and other type of terms:

      * `-a`, `--arg1`=[_OPTION_]:
        One or more paragraphs describing the argument.
      * `-b`, `--arg2`:
        Any number of these may be specified and may
        be nested.

## DESCRIPTION

Ronn files are simple ascii texts that document things in the
style of UNIX man pages but with a syntax and feature-set less
insane than that of roff(7). Ronn files are piped through ronn(1)
to build and install traditional roff(7) man pages or to generate
hyperlinked HTML documentation.

All ronn formatted files must conform to a simple subset of
markdown(5), a humane text markup designed for writing on the
web. It is neither possible nor desirable to express many of
roff(7)'s complex typesetting features in ronn.

## MANPAGE TITLE

All man pages have a <name>, belong to a <section>, and have a
single sentence <tagline> (useless but witty, preferably). Ronn
files must begin with a first-level heading that includes all of
this information. For example, this very man page begins:

    ronn(5) -- humane manual page authoring format
    =============================================

Here, we're saying that the man page documents a thing named
`ronn` in manual section `5` (the "file formats" section; see
manpages(5) for full section list) and that's quickly described
as a "humane manual page authoring format".

These bits of information are used to fill in the document
header, to create the `NAME` section, and also to establish
output filenames when processed with ronn(1).

## SECTION HEADINGS

Man section headings are expressed with markdown level two
headings. markdown(5) provides two syntaxes for level two
headings. A hash prefix syntax:

    ## HEADING TEXT

Or, a dash underline syntax:

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

Section headings should be in all uppercase and may not contain
other inline markup.

Most manual pages include at least one of the `SYNOPSIS`,
`DESCRIPTION`, and/or `OPTIONS` sections. Additional sections
commonly included are `SYNTAX`, `ENVIRONMENT`, `HISTORY`, `RETURN
VALUES`, `BUGS`, `SECURITY CONSIDERATIONS`, `STANDARDS` /
`CONFORMING TO`, `AUTHOR`, and `COPYRIGHT`. Finally, most man
pages end with a `SEE ALSO` section that references other manual
pages and external documents.

## INLINE MARKUP

Man pages have a limited set of text formatting capabilities at
their disposal. There's basically <b>boldface</b> and
<i>italics</i> (often displayed using <u>underline</u>). Ronn uses
the following bits of markdown(5) to accomplish this:

  * <code>\`backticks\`</code>:
    Code, flags, commands, and noun-like things; typically
    displayed in in <b>boldface</b>. Note that all text included
    within `backticks` is displayed literally; other inline markup
    is not processed.
  * `**double-stars**`:
    Like `backticks` but inline markup is processed.
  * `_`_underbars_`_`:
    User-specified arguments, variables, or user input; typically
    displayed with <u>underline</u>.
  * `<angle-quotes>`:
    Same as _underbars_. This is not compatible with Markdown.

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

Because definition lists are so often used in manual pages to
describe arguments, options, and variables, the basic markdown(5)
list syntax has been extended to support a definition list
syntax.

Definition list syntax is exactly the same as markdown(5)'s
unordered list syntax but requires that the first line of each
list item be terminated with a colon "`:`". The first line (minus
the colon) is the <term>; subsequent lines may be comprised of
multiple paragraphs, code blocks, standard lists, and nested
definition lists.

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.

The definition list syntax is intentionally backward compatible
with markdown(5)'s list syntax. This allows `ronn` documents to be
piped through normal markdown processors with minor degradation
in output formatting.

## SEE ALSO

ronn(1), markdown(5), manpages(5)