README.md in ronn-0.5 vs README.md in ronn-0.6.0

- old
+ new

@@ -1,45 +1,34 @@ ronn -- the opposite of roff -=========================== +============================ ## 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. +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 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. +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: +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) - - build markdown based manual pages at the command line. + convert markdown files to manpages.<br> [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) - - humane manual page authoring format syntax reference. + 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) - * [markdown(5)](http://rtomayko.github.com/ronn/markdown.5) - - humane text markup syntax (taken from - [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax), - John Gruber) - [source file](http://github.com/rtomayko/ronn/blob/master/man/markdown.5.ronn), - [roff output](http://github.com/rtomayko/ronn/blob/master/man/markdown.5) - ## INSTALL Install with Rubygems: $ [sudo] gem install ronn @@ -51,85 +40,81 @@ $ PATH=ronn/bin:$PATH $ ronn --help ## BASIC USAGE -To generate a roff man page from the included `markdown.5.ronn` file and -open it with man(1): +Build roff and HTML output files for one or more input files: - $ ronn -b man/markdown.5.ronn - building: man/markdown.5 - $ man man/markdown.5 + $ ronn man/ronn.5.ronn + roff: man/ronn.5 + html: man/ronn.5.html -To generate a standalone HTML version: +View a roff manpage with man(1): - $ ronn -b --html man/markdown.5.ronn - building: man/markdown.5.html - $ open man/markdown.5.html + $ man man/ronn.5 -To build roff and HTML versions of all ronn files: +Generate only a standalone HTML version of one or more files: - $ ronn -b --roff --html man/*.ronn + $ ronn --html man/markdown.5.ronn + html: man/markdown.5.html -If you just want to view a ronn file as if it were a man page without -building intermediate files: +Build roff versions of all ronn files in a directory: - $ ronn -m man/markdown.5.ronn + $ ronn --roff man/*.ronn -The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page -includes comprehensive documentation on `ronn` command line options. +View a ronn file as if it were a manpage without building intermediate files: + $ ronn --man man/markdown.5.ronn + +The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes +comprehensive documentation on `ronn` command line options. + ## ABOUT -Some people think UNIX manual pages are a poor and outdated style of +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 and provides a useful starting point for developers - documenting new tools, libraries, and formats. +- 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 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. +- 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). +- 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(5). HTML versions can use this to generate links between - pages. +- 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. +- 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, 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 +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 man page creation while -preserving the things that makes man pages a great form of -documentation. +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](http://tomayko.com/about) +Ronn is Copyright (C) 2009 [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)](http://rtomayko.github.com/ronn/markdown.5) +markdown(5)