ronn -- the opposite of roff

DESCRIPTION

Ronn is a text format and toolchain for creating UNIX manpages. It converts markdown to standard UNIX roff manpages and formatted HTML manuals for the web.

The source format includes all of Markdown but has a more rigid structure and includes extensions that provide features commonly found in manpages (definition lists, link notation, etc.). The ronn(5) manual page defines the format in detail.

DOCUMENTATION

The .ronn files located under the man/ 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:

ronn(1) - convert markdown files to manpages.
source file, roff output
ronn(5) - markdown-based text format for authoring manpages
source file, roff output

INSTALL

Install with Rubygems:

$ [sudo] gem install ronn
$ ronn --help

Or, clone the git repository:

$ git clone git://github.com/rtomayko/ronn.git
$ PATH=ronn/bin:$PATH
$ ronn --help

BASIC USAGE

Build roff and HTML output files for one or more input files:

$ ronn man/ronn.5.ronn
roff: man/ronn.5
html: man/ronn.5.html

View a roff manpage with man(1):

$ man man/ronn.5

Generate only a standalone HTML version of one or more files:

$ ronn --html man/markdown.5.ronn
html: man/markdown.5.html

Build roff versions of all ronn files in a directory:

$ ronn --roff man/*.ronn

View a ronn file as if it were a manpage without building intermediate files:

$ ronn --man man/markdown.5.ronn

The ronn(1) manual page includes comprehensive documentation on ronn command line options.

ABOUT

Some people say UNIX manual pages are a poor and outdated style of documentation. I disagree:

Man pages follow a well defined structure that's immediately familiar. This provides developers with a useful starting point when documenting new tools, libraries, and formats.
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.
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.
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 (The Feynman Lectures on Physics, 1970).
Man pages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7). HTML versions can use this to generate links between pages.
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.

Unfortunately, figuring out how to create a manpage 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 irrelevant to modern publishing tools.

Ronn aims to address many of the issues with manpage creation while preserving the things that makes manpages a great form of documentation.

COPYING

Ronn is Copyright (C) 2009 Ryan Tomayko
See the file COPYING for information of licensing and distribution.