ronn(1) -- build markdown-based man pages
========================================

## SYNOPSIS

`ronn` [ <OPTIONS> ] <FILE> ...  
`ronn` --build <FILE> ...  
`ronn` --install <FILE> ...  
`ronn` --man <FILE>

## DESCRIPTION

Ronn is a humane text format and toolchain for authoring man pages, and
things that appear as man pages from a distance. Use it to build and
install standard UNIX / roff(7) formatted man pages and to generate
nicely formatted HTML manual pages.

The `ronn` command converts one or more named input <FILE>s (or standard
input when no files are named or the file name `-` is given) from humane
man page markup to one or more destination output formats. If no output
format is selected explicitly, `ronn` writes output in roff format.

## FILES

The `ronn` command expects input to be formatted as ronn(5) text.  Source
files are typically named '<NAME>.<SECTION>.ronn' (e.g., `hello.1.ronn`).
The <NAME> and <SECTION> should match the name and section defined in
<FILE>'s heading.

When building roff and/or HTML output files with the `--build` argument,
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, the command `ronn -b --html --roff hello.1.ronn` generates a
`hello.1` file with roff output and a `hello.1.html` file with HTML
output.

## OPTIONS

`ronn`'s default mode of operation is to read a single document from
standard input and to write the result to standard output. The following
arguments change this behavior:

  * `-b`, `--build`:
    Write output directly to files instead of standard output. When the
    `--roff` option is provided, writes roff output to <file>.<section>.
    When the `--html` option is provided, writes output to
    '<file>.<section>.html'.

  * `-i`, `--install`:
    Install the roff formatted man page to the local system such that it
    can be displayed by man(1). The `MANHOME` environment variable is
    used to determine the prefix where man pages should be installed
    when defined.

    If `MANHOME` is not defined, `ronn` installs man pages to
    _/usr/local/man_.

  * `-m`, `--man`:
    Display <FILE>s 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.

These options control the format used in generated output:

  * `-r`, `--roff`:
    Generate roff output. This is the default behavior when no other
    format argument is provided.

  * `-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.

All document attributes displayed in the header and footer areas of
generated content can be specified with these options:

  * `--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.

## EXAMPLES

Generate `roff(7)` output on stdout:

    $ ronn < hello.1.ronn

Build a roff file based on the input filename:

    $ ronn -b hello.1.ronn
    building: hello.1
    $ man hello.1

Build and open a standalone HTML file based on the input filename:

    $ ronn -b --html test.1.ronn
    $ open test.1.html

Build roff and HTML versions of all `.ronn` files in the current
directory:

    $ ronn -b --roff --html *.ronn
    building: hello.1
    building: hello.1.html
    building: world.1
    building: world.1.html

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

    $ ronn -m hello.1.ronn

Install the roff man page for a ronn file:

    $ ronn -i hello.1.ronn

## ENVIRONMENT

  * `MANHOME`:
    Location where roff formatted man pages are installed.  Relevant
    only when the `--install` argument is provided.  <PATH> is to the
    base of a man file hierarchy. e.g., `/usr/local/share/man`,
    `/home/rtomayko/man`.

  * `MANPAGER`:
    The paging program used for man pages. This is typically set to
    something like 'less -is'.

  * `PAGER`:
    Used instead of `MANPAGER` when `MANPAGER` is not defined.

## BUGS

Ronn is written in Ruby and depends on hpricot and rdiscount, extension
libraries that are non-trivial to install on some systems. A more portable
version of this program would be welcome.

## COPYRIGHT

Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>

## SEE ALSO

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