ron 0.2 → 0.3

data/man/ron.5.ron

@@ -3,6 +3,8 @@ ron(5) -- humane manual page authoring format
 
 ## SYNOPSIS
 
+A basic manual page in Ron:
+
     name(1) -- one sentence description
     ===================================
 
@@ -14,50 +16,50 @@ ron(5) -- humane manual page authoring format
 
     ## INLINE MARKUP
 
-    Inline markup should be used for `code` (displayed in
-    boldface) and _variables_ (displayed in underline).
+    Inline markup is used for `code` and `user input` (displayed
+    in boldface), and also <variables> or _emphasis_.
 
     Manual page references like sh(1), markdown(5), roff(7), etc.
     are displayed in boldface and hyperlinked in HTML output.
 
     ## DEFINITION LISTS
 
-    Definition lists are used to define arguments, variables,
-    or other terms:
+    Definition lists are used to define options, arguments,
+    variables, and other type of terms:
 
       * `-a`, `--arg1`=[_OPTION_]:
-        One or more paragraphs describing the 
+        One or more paragraphs describing the argument.
       * `-b`, `--arg2`:
-        Any number of these may be specified and they can be
-        nested.
+        Any number of these may be specified and may
+        be nested.
 
 ## DESCRIPTION
 
-`Ron` files are simple ascii texts that document things in the
+Ron files are simple ascii texts that document things in the
 style of UNIX man pages but with a syntax and feature-set less
-insane than that of roff(7). `Ron` files are piped through
-ron(1) to build and install traditional roff(7) man pages or
-to generate hyperlinked HTML documentation.
+insane than that of roff(7). Ron files are piped through ron(1)
+to build and install traditional roff(7) man pages or to generate
+hyperlinked HTML documentation.
 
-All `ron` files must conform to a simple subset of markdown(5), a
-humane text markup designed for writing on the web. It is neither
-possible nor desirable to express many of roff(7)'s complex
-typesetting features in `ron`.
+All ron formatted files must conform to a simple subset of
+markdown(5), a humane text markup designed for writing on the
+web. It is neither possible nor desirable to express many of
+roff(7)'s complex typesetting features in ron.
 
 ## MANPAGE TITLE
 
-All man pages have a _name_, belong to a _section_, and have a
-single sentence _tagline_ (useless but witty, preferably). `Ron`
+All man pages have a <name>, belong to a <section>, and have a
+single sentence <tagline> (useless but witty, preferably). Ron
 files must begin with a first-level heading that includes all of
 this information. For example, this very man page begins:
 
     ron(5) -- humane manual page authoring format
     =============================================
 
-Here, we're saying that the man page documents a thing named `ron`
-in manual section `5` -- the "file formats" section; see
-manpages(5) for full section list -- and that's quickly
-described as a "humane manual page authoring format".
+Here, we're saying that the man page documents a thing named
+`ron` in manual section `5` (the "file formats" section; see
+manpages(5) for full section list) and that's quickly described
+as a "humane manual page authoring format".
 
 These bits of information are used to fill in the document
 header, to create the `NAME` section, and also to establish
@@ -89,10 +91,10 @@ pages and external documents.
 
 ## INLINE MARKUP
 
-Man pages typically use a limited set of text formatting
-capabilities. There's basically <b>boldface</b> and
-<i>italics</i> (often displayed using <u>underline</u>). Ron
-uses the following bits of markdown(5) to accomplish this:
+Man pages have a limited set of text formatting capabilities at
+their disposal. There's basically <b>boldface</b> and
+<i>italics</i> (often displayed using <u>underline</u>). Ron uses
+the following bits of markdown(5) to accomplish this:
 
   * <code>\`backticks\`</code>:
     Code, flags, commands, and noun-like things; typically
@@ -100,7 +102,7 @@ uses the following bits of markdown(5) to accomplish this:
     within `backticks` is displayed literally; other inline markup
     is not processed.
   * `**double-stars**`:
-    Like `backticks` but may contain other inline markup.
+    Like `backticks` but inline markup is processed.
   * `_`_underbars_`_`:
     User-specified arguments, variables, or user input; typically
     displayed with <u>underline</u>.
@@ -121,15 +123,15 @@ describe arguments, options, and variables, the basic markdown(5)
 list syntax has been extended to support a definition list
 syntax.
 
-A definition list's syntax is exactly the same as markdown(5)'s
+Definition list syntax is exactly the same as markdown(5)'s
 unordered list syntax but requires that the first line of each
-list item be terminated with a colon "`:`". The first line
-(minus the colon) is the _term_; subsequent lines may be
-comprised of multiple paragraphs, code blocks, standard lists,
-and nested definition lists.
+list item be terminated with a colon "`:`". The first line (minus
+the colon) is the <term>; subsequent lines may be comprised of
+multiple paragraphs, code blocks, standard lists, and nested
+definition lists.
 
-An example definition list, taken from test(1)'s `DESCRIPTION`
-section:
+An example definition list, taken from BSD test(1)'s
+`DESCRIPTION` section:
 
      The following primaries are used to construct expressions:
 

data/man/ron.7

@@ -0,0 +1,201 @@
+.\" generated with Ron/v0.2
+.\" http://github.com/rtomayko/ron/
+.
+.TH "RON" "7" "December 2009" "Ryan Tomayko" "Ron Manual"
+.
+.SH "NAME"
+\fBron\fR \-\- the opposite of roff
+.
+.SH "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.
+.
+.P
+The Ron file format is based on Markdown. In fact, Ron 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 ron(5) manual page defines the
+format in more detail.
+.
+.SH "DOCUMENTATION"
+The \fB.ron\fR files located under the \fBman/\fR directory show off a wide
+range of ron capabilities and are the source of Ron's own documentation.
+The source files and generated HTML / roff output files are available
+at:
+.
+.IP "\(bu" 4
+\fIron(1)\fR \-
+build markdown based manual pages at the command line.
+.
+.br
+\fIsource file\fR, \fIroff output\fR
+.
+.IP "\(bu" 4
+\fIron(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 ron
+$ ron \-\-help 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Or, clone the git repository:
+.
+.IP "" 4
+.
+.nf
+
+$ git clone git://github.com/rtomayko/ron.git
+$ PATH=ron/bin:$PATH
+$ ron \-\-help 
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BASIC USAGE"
+To generate a roff man page from the included\fI\fBmarkdown.5.ron\fR\fR file and open it with man(1):
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-b man/markdown.5.ron
+building: man/markdown.5
+$ man man/markdown.5 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To generate a standalone HTML version:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-b \-\-html man/markdown.5.ron
+building: man/markdown.5.html
+$ open man/markdown.5.html 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To build roff and HTML versions of all ron files:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-b \-\-roff \-\-html man/*.ron 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If you just want to view a ron file as if it were a man page without
+building intermediate files:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-m man/markdown.5.ron 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The \fIron(1)\fR manual page
+includes comprehensive documentation on \fBron\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
+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.
+.
+.SH "COPYING"
+Ron is Copyright (C) 2009 \fIRyan Tomayko\fR
+See the file COPYING for information of licensing and distribution.
+.
+.SH "SEE ALSO"
+ron(1), ron(5), markdown(5)

data/man/ron.7.ron

@@ -1,57 +1,60 @@
-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
+ron -- 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 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 ron(5) manual page defines the
 format in more detail.
 
-INSTALL
--------
+## DOCUMENTATION
 
-Ron can be installed using rubygems:
+The `.ron` files located under the `man/` directory show off a wide
+range of ron capabilities and are the source of Ron's own documentation.
+The source files and generated HTML / roff output files are available
+at:
 
-    $ [sudo] gem install ron
+  * [ron(1)](http://rtomayko.github.com/ron/ron.1.html) -
+    build markdown based manual pages at the command line.  
+    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.1.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.1)
 
-Or, clone the git repository and install from
-source:
+  * [ron(5)](http://rtomayko.github.com/ron/ron.5.html) -
+    humane manual page authoring format syntax reference.  
+    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.5.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
 
-    $ git clone git://github.com/rtomayko/ron.git
-    $ cd ron
-    $ rake package
-    $ [sudo] rake install
+  * [markdown(5)](http://rtomayko.github.com/ron/markdown.5.html) -
+    humane text markup syntax (taken from
+    [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax),
+    John Gruber)  
+    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.5.ron),
+    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
 
-EXAMPLES
---------
+## INSTALL
 
-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:
+Install with Rubygems:
 
-    http://rtomayko.github.com/ron/ron.1.html
-    http://rtomayko.github.com/ron/ron.5.html
-    http://rtomayko.github.com/ron/markdown.5.html
+    $ [sudo] gem install ron
+    $ ron --help
+
+Or, clone the git repository:
 
-BASIC USAGE
------------
+    $ git clone git://github.com/rtomayko/ron.git
+    $ PATH=ron/bin:$PATH
+    $ ron --help
+
+## BASIC USAGE
 
 To generate a roff man page from the included
-`markdown.5.ron` file and open it in man(1):
+[`markdown.5.ron`](man/markdown.5.ron) file and open it with man(1):
 
     $ ron -b man/markdown.5.ron
     building: man/markdown.5
@@ -63,87 +66,68 @@ To generate a standalone HTML version:
     building: man/markdown.5.html
     $ open man/markdown.5.html
 
-To build roff and HTML versions of all ron
-files:
+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:
+If you just want to view a ron file as if it were a man page without
+building 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
+The [ron(1)](http://rtomayko.github.com/ron/ron.1.html) manual page
+includes comprehensive documentation on `ron` command line options.
+
+## ABOUT
+
+Some people think 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 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(5). HTML versions can use this to generate links between
   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
+- 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
+publishing tools.
+
+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.
 
-COPYRIGHT
----------
+## COPYING
+
+Ron is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
+See the file COPYING for information of licensing and distribution.
+
+## SEE ALSO
 
-Ron is Copyright (C) 2009 Ryan Tomayko
-See the file COPYING for more information.
+ron(1), ron(5), markdown(5)