README.md in ronn-0.6.6 vs README.md in ronn-0.7.0

- old
+ new

@@ -1,59 +1,36 @@ -ronn -- the opposite of roff -============================ +# Ronn -## DESCRIPTION +Ronn builds manuals. It converts simple, human readable textfiles to roff for +terminal display, and also to HTML for the web. -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 +syntax extensions for features commonly found in manpages (definition lists, +link notation, etc.). The ronn-format(7) manual page defines the format in detail. -## DOCUMENTATION +The `*.ronn` files found in the [`man/`][1] directory show off a wide range of +ronn capabilities: -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)](http://rtomayko.github.com/ronn/ronn.1) - - convert markdown files to manpages.<br> + * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) command - [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn), [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1) - * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5) - - markdown-based text format for authoring manpages<br> - [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn), - [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5) + * [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7) - + [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7.ronn), + [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn-format.7) -## INSTALL +[1]: http://github.com/rtomayko/ronn/tree/master/man -Install with Rubygems: +## Examples - $ [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 @@ -63,58 +40,55 @@ View a ronn file as if it were a manpage without building intermediate files: $ ronn --man man/markdown.5.ronn +View roff output with man(1): + + $ man man/ronn.5 + The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes comprehensive documentation on `ronn` command line options. -## ABOUT +## Background -Some people say UNIX manual pages are a poor and outdated style of -documentation. I disagree: +Some think UNIX manual pages are a poor and outdated form 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. +- Manpages follow a well defined structure that's immediately familiar. This + gives developers a starting point when documenting new tools, libraries, and + formats. -- Man pages get to the point. Because they're written in an inverted style, with +- Manpages 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 + other sources of information, manpages 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. +- Historically, manpages use an extremely -- unbelievably -- limited set of + 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). +- Although two levels of section hierarchy are technically supported, most + manpages use only a single level. Unwieldy document hierarchies complicate + otherwise good documentation. Remember that 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. +- The classical terminal manpage 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. +- Manpages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7). + HTML versions can use this to generate links between pages. + 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. +The roff/mandoc/mdoc 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. +Ronn aims -## COPYING +## Copying -Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)<br> +Ronn is Copyright (C) 2010 [Ryan Tomayko](http://tomayko.com/about)<br> See the file COPYING for information of licensing and distribution. - -## SEE ALSO - -[ronn(1)](http://rtomayko.github.com/ronn/ronn.1), -[ronn(5)](http://rtomayko.github.com/ronn/ronn.5), -markdown(5)