.\" generated with Ronn/v0.4.2
.\" http://github.com/rtomayko/ronn/
.
.TH "RONN" "7" "March 2010" "Ryan Tomayko" "Ronn Manual"
.
.SH "NAME"
\fBronn\fR \-\- the opposite of roff
.
.SH "DESCRIPTION"
Ronn is a humane text format and toolchain for creating UNIX man
pages, and things that appear as man pages from a distance. Use it
to build and install standard UNIX roff man pages or to generate
nicely formatted HTML manual pages for the web.
.
.P
The Ronn file format is based on Markdown. In fact, Ronn files are a
compatible subset of Markdown syntax but have a more rigid structure and
extend Markdown in some ways to provide features commonly found in man
pages (e.g., definition lists). The ronn(5) manual page defines the
format in more detail.
.
.SH "DOCUMENTATION"
The \fB.ronn\fR files located under the \fBman/\fR directory show off a wide
range of ronn capabilities and are the source of Ronn's own documentation.
The source files and generated HTML / roff output files are available
at:
.
.IP "\(bu" 4
\fIronn(1)\fR \-
build markdown based manual pages at the command line.
.
.br
\fIsource file\fR, \fIroff output\fR
.
.IP "\(bu" 4
\fIronn(5)\fR \-
humane manual page authoring format syntax reference.
.
.br
\fIsource file\fR, \fIroff output\fR
.
.IP "\(bu" 4
\fImarkdown(5)\fR \-
humane text markup syntax (taken from \fIMarkdown Syntax\fR,
John Gruber)
.
.br
\fIsource file\fR, \fIroff output\fR
.
.IP "" 0
.
.SH "INSTALL"
Install with Rubygems:
.
.IP "" 4
.
.nf

$ [sudo] gem install ronn
$ ronn \-\-help
.
.fi
.
.IP "" 0
.
.P
Or, clone the git repository:
.
.IP "" 4
.
.nf

$ git clone git://github.com/rtomayko/ronn.git
$ PATH=ronn/bin:$PATH
$ ronn \-\-help
.
.fi
.
.IP "" 0
.
.SH "BASIC USAGE"
To generate a roff man page from the included \fBmarkdown.5.ronn\fR file and
open it with man(1):
.
.IP "" 4
.
.nf

$ ronn \-b man/markdown.5.ronn
building: man/markdown.5
$ man man/markdown.5
.
.fi
.
.IP "" 0
.
.P
To generate a standalone HTML version:
.
.IP "" 4
.
.nf

$ ronn \-b \-\-html man/markdown.5.ronn
building: man/markdown.5.html
$ open man/markdown.5.html
.
.fi
.
.IP "" 0
.
.P
To build roff and HTML versions of all ronn files:
.
.IP "" 4
.
.nf

$ ronn \-b \-\-roff \-\-html man/*.ronn
.
.fi
.
.IP "" 0
.
.P
If you just want to view a ronn file as if it were a man page without
building intermediate files:
.
.IP "" 4
.
.nf

$ ronn \-m man/markdown.5.ronn
.
.fi
.
.IP "" 0
.
.P
The \fIronn(1)\fR manual page
includes comprehensive documentation on \fBronn\fR command line options.
.
.SH "ABOUT"
Some people think UNIX manual pages are a poor and outdated style of
documentation. I disagree:
.
.IP "\(bu" 4
Man pages follow a well defined structure that's immediately
familiar and provides a useful starting point for developers
documenting new tools, libraries, and formats.
.
.IP "\(bu" 4
Man pages get to the point. Because they're written in an inverted
style, with a SYNOPSIS section followed by additional detail,
prose and references to other sources of information, man pages
provide the best of both cheat sheet and reference style
documentation.
.
.IP "\(bu" 4
Man pages have extremely \-\- unbelievably \-\- limited text
formatting capabilities. You get a couple of headings, lists, bold,
underline and no more. This is a feature.
.
.IP "\(bu" 4
Although two levels of section hierarchy are technically
supported, most man pages use only a single level. Unwieldy
document hierarchies complicate otherwise good documentation.
Feynman covered all of physics \-\- heavenly bodies through QED \-\-
with only two levels of document hierarchy (\fIThe Feynman Lectures
on Physics\fR, 1970).
.
.IP "\(bu" 4
Man pages have a simple referencing syntax; e.g., sh(1), fork(2),
markdown(5). HTML versions can use this to generate links between
pages.
.
.IP "\(bu" 4
The classical terminal man page display is typographically well
thought out. Big bold section headings, justified monospace text,
nicely indented paragraphs, intelligently aligned definition
lists, and an informational header and footer.
.
.IP "" 0
.
.P
Unfortunately, trying to figure out how to create a man page is a
fairly tedious process. The roff/man macro languages are highly
extensible, fractured between multiple dialects, and include a bunch
of device specific stuff that's entirely irrelevant to modern
publishing tools.
.
.P
Ronn aims to address many of the issues with man page creation while
preserving the things that makes man pages a great form of
documentation.
.
.SH "COPYING"
Ronn is Copyright (C) 2009 \fIRyan Tomayko\fR
See the file COPYING for information of licensing and distribution.
.
.SH "SEE ALSO"
\fIronn(1)\fR, \fIronn(5)\fR, \fImarkdown(5)\fR