RubyDoc.info: File: README – Documentation for ron (0.2)

ron(7) – the opposite of roff

DESCRIPTION

Ron 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.

The ron file format is based on Markdown. In fact, ron files are 100% Markdown compatible but have a more rigidly defined structure and extend Markdown in some ways to provide features commonly found in man pages (e.g., definition lists). The ron(5) manual page included with this distribution defines the format in more detail.

INSTALL

Ron can be installed using rubygems:

$ [sudo] gem install ron

Or, clone the git repository and install from source:

$ git clone git://github.com/rtomayko/ron.git
$ cd ron
$ rake package
$ [sudo] rake install

EXAMPLES

The .ron files located under the repository’s ./man directory show off a wide range of ron capabilities. The HTML versions of these files are available at:

http://rtomayko.github.com/ron/ron.1.html
http://rtomayko.github.com/ron/ron.5.html
http://rtomayko.github.com/ron/markdown.5.html

BASIC USAGE

To generate a roff man page from the included markdown.5.ron file and open it in man(1):

$ ron -b man/markdown.5.ron
building: man/markdown.5
$ man man/markdown.5

To generate a standalone HTML version:

$ ron -b --html man/markdown.5.ron
building: man/markdown.5.html
$ open man/markdown.5.html

To build roff and HTML versions of all ron files:

$ ron -b --roff --html man/*.ron

If you just want to view a ron file as if it were a man page without building any intermediate files:

$ ron -m man/markdown.5.ron

The ron(1) manual page included with this distribution includes full documentation on ron command line options.

RATIONALE

Some people think UNIX manual pages are a poor and outdated form of documentation. I disagree.

Man pages typically follow a well defined structure that’s immediately familiar and provides a useful starting point for developers 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 finally references to other sources of information, man pages provide the best of both cheat sheet and reference style documentation.
Man pages have very limited text formatting capabilities. This is a feature. You get bold and underline, basically, and they’re typically applied consistently across man pages.
Most man pages use only a single level of section hierarchy (although two levels are technically supported). Hierarchy destroys otherwise good documentation by adding unnecessary complexity. Feynman described the whole of quantum electro dynamics with only two levels of hierarchy. How can you possibly need more? Man pages force you to keep it simple.
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.
The classical terminal man page display is typographically well thought out. Big bold section headings, justified monospaced text, nicely indented paragraphs, intelligently aligned definition lists, and an informational header and footer.

All that being said, trying to figure out how to create a man page can be a really tedious process. The roff/man macro languages are highly extensible, fractured between multiple dialects, and include a bunch of stuff that’s entirely irrelevant to modern man page creation. It’s also horribly ugly compared to today’s humane text formats or even HTML (just sayin’).

Ron aims to address many of the issues with man page creation while preserving the things that makes man pages a great form of documentation.