ron 0.1 → 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,21 +91,23 @@ 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
     displayed in in <b>boldface</b>. Note that all text included
     within `backticks` is displayed literally; other inline markup
     is not processed.
+  * `**double-stars**`:
+    Like `backticks` but inline markup is processed.
   * `_`_underbars_`_`:
     User-specified arguments, variables, or user input; typically
-    displayed in <u>underline</u>.
-  * `**double stars**`:
-    Like `backticks` but may contain other inline markup.
+    displayed with <u>underline</u>.
+  * `<angle-quotes>`:
+    Same as _underbars_. This is not compatible with Markdown.
 
 Here is grep(1)'s DESCRIPTION section represented in `ron`:
 
@@ -119,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

@@ -0,0 +1,133 @@
+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.
+
+## DOCUMENTATION
+
+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:
+
+  * [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)
+
+  * [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)
+
+  * [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)
+
+## INSTALL
+
+Install with Rubygems:
+
+    $ [sudo] gem install ron
+    $ ron --help
+
+Or, clone the git repository:
+
+    $ 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`](man/markdown.5.ron) file and open it with 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 intermediate files:
+
+    $ ron -m man/markdown.5.ron
+
+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.
+
+- 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.
+
+## 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(1), ron(5), markdown(5)

data/ron.gemspec

@@ -3,8 +3,8 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
 
   s.name = 'ron'
-  s.version = '0.1'
-  s.date = '2009-11-05'
+  s.version = '0.3'
+  s.date = '2009-12-09'
 
   s.description = "The opposite of roff"
   s.summary     = "The opposite of roff"
@@ -15,27 +15,41 @@ Gem::Specification.new do |s|
   # = MANIFEST =
   s.files = %w[
     COPYING
-    README
+    README.md
     Rakefile
     bin/ron
     lib/ron.rb
     lib/ron/document.rb
     lib/ron/layout.html
     lib/ron/roff.rb
+    man/markdown.5
     man/markdown.5.ron
+    man/ron.1
     man/ron.1.ron
+    man/ron.5
     man/ron.5.ron
+    man/ron.7
+    man/ron.7.ron
     ron.gemspec
+    test/angle_bracket_syntax.html
+    test/angle_bracket_syntax.ron
+    test/basic_document.html
+    test/basic_document.ron
+    test/custom_title_document.html
+    test/custom_title_document.ron
+    test/definition_list_syntax.html
+    test/definition_list_syntax.ron
     test/document_test.rb
     test/ron_test.rb
-    test/simple.ron
+    test/titleless_document.html
+    test/titleless_document.ron
   ]
   # = MANIFEST =
 
   s.executables = ['ron']
   s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ }
 
-  s.extra_rdoc_files = %w[README COPYING]
+  s.extra_rdoc_files = %w[COPYING]
   s.add_dependency 'nokogiri',    '~> 1.4'
   s.add_dependency 'rdiscount',   '~> 1.3'
   s.add_development_dependency 'contest', '~> 0.1'

data/test/angle_bracket_syntax.html

@@ -0,0 +1,12 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>angle_bracket_syntax</code> -- angle bracket syntax test</p>
+<p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
+
+<pre><code>except when &lt;WORD&gt; is
+part of a preformatted
+code block,
+</code></pre>
+
+<p>or when <code>&lt;WORD&gt;</code> is enclosed in backticks.</p>
+
+<p>or when <var>WORD</var> has a &lt;dot.&gt; or &lt;foo:colon&gt;.</p>

data/test/angle_bracket_syntax.ron

@@ -0,0 +1,12 @@
+angle_bracket_syntax(5) -- angle bracket syntax test
+====================================================
+
+A <WORD> in angle brackets is converted to <var>WORD</var>,
+
+    except when <WORD> is
+    part of a preformatted
+    code block,
+
+or when `<WORD>` is enclosed in backticks.
+
+or when <WORD> has a <dot.> or <foo:colon>.

data/test/basic_document.html

@@ -0,0 +1,3 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>simple</code> -- a simple ron example</p>
+<p>This document created by ron.</p>

data/test/{simple.ron → basic_document.ron}

@@ -1,2 +1,4 @@
 simple(7) -- a simple ron example
 =================================
+
+This document created by ron.

data/test/custom_title_document.html

@@ -0,0 +1,3 @@
+<h1>custom_title_document -- This is a custom title</h1>
+<p>It doesn't define the name or section of this manual page and is
+output as a simple <code>&lt;h1&gt;</code> instead of a <code>NAME</code> section.</p>

data/test/custom_title_document.ron

@@ -0,0 +1,5 @@
+This is a custom title
+======================
+
+It doesn't define the name or section of this manual page and is
+output as a simple `<h1>` instead of a `NAME` section.

data/test/definition_list_syntax.html

@@ -0,0 +1,21 @@
+<h2 id='NAME'>NAME</h2>
+<p><code>defition_list_syntax</code> -- hiya</p>
+<p>Definition lists look like unordered lists:</p>
+
+<dl>
+<dt class="flush">term</dt>
+<dd><p>definition</p></dd>
+<dt>another one</dt>
+<dd>
+<p>The definition may span
+multiple lines and even</p>
+
+<p>start</p>
+
+<p>new paragraphs</p>
+</dd>
+<dt>
+<code>--somearg</code>=<var>VALUE</var>
+</dt>
+<dd><p>We can do that too.</p></dd>
+</dl>

data/test/definition_list_syntax.ron

@@ -0,0 +1,18 @@
+defition_list_syntax(5) -- hiya
+===============================
+
+Definition lists look like unordered lists:
+
+  * term:
+    definition
+
+  * another one:
+    The definition may span
+    multiple lines and even
+
+    start
+
+    new paragraphs
+
+  * `--somearg`=<VALUE>:
+    We can do that too.