ronn(5) -- markdown-based text format for authoring manpages
============================================================

## 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 or
    underline.

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

    Link to other 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.

    Markdown ordered and unordered lists too.

    Frequently used sections:

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

## DESCRIPTION

Ronn is a source format for authoring UNIX manpages. The syntax includes all
Markdown formatting features, plus conventions for expressing the structure and
various notations present in standard UNIX manpages.

Ronn files can be converted to traditional roff-formatted manpages or to HTML
using the ronn(1) command.

Not all roff(7) typesetting features can be expressed using ronn syntax.

## MANPAGE TITLE

Manpages have a <name>, <section> number, and one-line <description>. Ronn 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` ("user
commands").

## 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
<b>boldface</b> and <i>italics</i> (often displayed using <u>underline</u>).
Ronn uses the following bits of markdown(7) 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

The definition list syntax is exactly the same as markdown's unordered list
syntax but requires that the first line of each list item be terminated with a
colon "`:`" character. The contents of the first line (without 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(7)'s list syntax. This allows `ronn` documents to be piped through
normal markdown processors with minor degradation in output formatting.

## LINKS

Ronn supports all markdown(7) linking features. Additionally, section headings
can be linked using reference-style links:

    ## 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)