ronn 0.6.6 → 0.7.0

data/man/ronn.1.ronn

@@ -3,7 +3,7 @@ ronn(1) -- convert markdown files to manpages
 
 ## SYNOPSIS
 
-`ronn` [<options>] <file>...<br>
+`ronn` [<format>...] <file>...<br>
 `ronn` `-m`|`--man` <file>...<br>
 `ronn` `-S`|`--server` <file>...<br>
 `ronn` `--pipe` <file><br>
@@ -11,31 +11,29 @@ ronn(1) -- convert markdown files to manpages
 
 ## DESCRIPTION
 
-**Ronn** converts Markdown input to standard roff-formatted UNIX manpages or
-manpage styled HTML. The ronn(5) source format is based on markdown(7) but
-includes additional rules and syntax geared toward authoring manuals.
+**Ronn** converts textfiles to standard roff-formatted UNIX manpages or HTML.
+ronn-format(7) is based on markdown(7) but includes additional rules and syntax
+geared toward authoring manuals.
 
-In its default mode, `ronn` converts one or more input <file>s to HTML or UNIX
-roff output files. The `--roff`, `--html`, and `--fragment` options dictate
-which output files are generated. Multiple format arguments may be specified to
+In its default mode, `ronn` converts one or more input <file>s to HTML or roff
+output files. The `--roff`, `--html`, and `--fragment` options dictate which
+output files are generated. Multiple format arguments may be specified to
 generate multiple output files. Output files are named after and written to the
 same directory as input <file>s.
 
-The `--server` and `--man` options change the output behavior from output file
+The `--server` and `--man` options change the output behavior from file
 generation to serving dynamically generated HTML manpages or viewing <file> as
 with man(1).
 
 With no <file> arguments, `ronn` acts as simple filter. Ronn source text is read
-from standard input and roff output is written to standard output. The `--html`
-and `--fragment` options can be used to generate that format output instead of
-roff.
+from standard input and roff output is written to standard output. Use the
+`--html`, `--roff`, and/or `--fragment` options to select the output format.
 
 ## FILES
 
-The `ronn` command expects input to be formatted as ronn(5) text.  Source
-files are typically named '<name>.<section>.ronn' (e.g., `example.1.ronn`).
-The <name> and <section> should match the name and section defined in the
-<file>'s heading.
+The `ronn` command expects input to be valid ronn-format(7) text.  Source files
+are typically named <name>.<section>.ronn (e.g., `example.1.ronn`).  The <name>
+and <section> should match the name and section defined in the <file>'s heading.
 
 When building roff or HTML output files, destination filenames are determined by
 taking the basename of the input <file> and adding the appropriate file
@@ -45,7 +43,7 @@ and `example.1.html` with HTML output.
 
 ## OPTIONS
 
-These options control whether output is written to files, standard output, or
+These options control whether output is written to file(s), standard output, or
 directly to a man pager.
 
   * `-m`, `--man`:
@@ -105,7 +103,7 @@ the [ENVIRONMENT][].)
     displayed in the bottom-center footer area. The <file> mtime is used when no
     <date> is given, or the current time when no <file> is available.
 
-HTML output can be customized variously:
+HTML output can be customized through the use of CSS stylesheets:
 
   * `--style`=<module>[,<module>]...:
     The list of CSS stylesheets to apply to the document. Multiple <module>
@@ -132,13 +130,45 @@ Miscellaneous options:
     Disable troff warnings. Warnings are disabled by default. This option can be
     used to revert the effect of a previous `-w` argument.
 
+  * `-v`, `--version`:
+    Show ronn version and exit.
+
+## LINK INDEXES
+
+When generating HTML output, `ronn` hyperlinks manual references (like
+`grep(1)`, `ls(1)`, `markdown(7)`) in source text based on reference name to URL
+mappings defined in an `index.txt` file. Each line of the index file describes a
+single reference link, with whitespace separating the reference's <id> from its
+<location>. Blank lines are allowed; lines beginning with a `#` character are
+ignored:
+
+    # manuals included in this project:
+    whisky(1)    whisky.1.ronn
+    tango(5)     tango.5.ronn
+
+    # external manuals
+    grep(1)      http://man.cx/grep(1)
+    ls(1)        http://man.cx/ls(1)
+
+    # other URLs for use with markdown reference links
+    src          http://github.com/
+
+The <location> is an absolute or relative URL that usually points at an HTML
+version of manpage. It's possible to define references for things that aren't
+manpages.
+
+All manuals in an individual directory share the references defined in that
+directory's `index.txt` file. Index references may be used explicitly in
+Markdown reference style links using the syntax: `[`<text>`][`<id>`]`, where
+<text> is the link text and <id> is a reference name defined in the index.
+
 ## STYLES
 
 The `--style` option selects a list of CSS stylesheets to include in the
 generated HTML. Styles are applied in the order defined, so each can use the
 cascade to override previously defined styles.
 
-### Internal Stylesheets
+### Builtin Stylesheets
 
 These styles are included with the distribution:
 
@@ -188,10 +218,10 @@ allow targeting all generated elements:
      The main `<h1>` element. Hidden by default unless the manual has no <name>
      or <section> attributes.
 
-See the [internal style sources][internal] for examples.
+See the [builtin style sources][builtin] for examples.
 
-[internal]: http://github.com/rtomayko/ronn/tree/master/lib/ronn/template
-            "internal stylesheet sources"
+[builtin]: http://github.com/rtomayko/ronn/tree/master/lib/ronn/template
+          "Builtin Stylesheet .css files"
 
 ## EXAMPLES
 
@@ -268,8 +298,8 @@ version of this program would be welcome.
 
 ## COPYRIGHT
 
-Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+Ronn is Copyright (C) 2009 Ryan Tomayko <http://tomayko.com/about>
 
 ## SEE ALSO
 
-ronn(5), (7), manpages(5), man(1), roff(7), groff(1), markdown(7)
+ronn-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)

data/ronn.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = 'ronn'
-  s.version = '0.6.6'
-  s.date = '2010-06-13'
+  s.version = '0.7.0'
+  s.date = '2010-06-21'
 
   s.description = "The opposite of roff"
   s.summary     = "The opposite of roff"
@@ -14,12 +14,14 @@ Gem::Specification.new do |s|
     AUTHORS
     CHANGES
     COPYING
+    INSTALLING
     README.md
     Rakefile
     bin/ronn
     config.ru
     lib/ronn.rb
     lib/ronn/document.rb
+    lib/ronn/index.rb
     lib/ronn/roff.rb
     lib/ronn/server.rb
     lib/ronn/template.rb
@@ -32,12 +34,12 @@ Gem::Specification.new do |s|
     lib/ronn/template/screen.css
     lib/ronn/template/toc.css
     lib/ronn/utils.rb
+    man/index.html
+    man/index.txt
+    man/ronn-format.7
+    man/ronn-format.7.ronn
     man/ronn.1
     man/ronn.1.ronn
-    man/ronn.5
-    man/ronn.5.ronn
-    man/ronn.7
-    man/ronn.7.ronn
     ronn.gemspec
     test/angle_bracket_syntax.html
     test/angle_bracket_syntax.ronn
@@ -49,10 +51,12 @@ Gem::Specification.new do |s|
     test/definition_list_syntax.html
     test/definition_list_syntax.roff
     test/definition_list_syntax.ronn
-    test/document_test.rb
+    test/dots_at_line_start_test.roff
+    test/dots_at_line_start_test.ronn
     test/entity_encoding_test.html
     test/entity_encoding_test.roff
     test/entity_encoding_test.ronn
+    test/index.txt
     test/markdown_syntax.html
     test/markdown_syntax.roff
     test/markdown_syntax.ronn
@@ -61,10 +65,12 @@ Gem::Specification.new do |s|
     test/middle_paragraph.ronn
     test/missing_spaces.roff
     test/missing_spaces.ronn
-    test/ronn_test.rb
     test/section_reference_links.html
     test/section_reference_links.roff
     test/section_reference_links.ronn
+    test/test_ronn.rb
+    test/test_ronn_document.rb
+    test/test_ronn_index.rb
     test/titleless_document.html
     test/titleless_document.ronn
     test/underline_spacing_test.roff

data/test/angle_bracket_syntax.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>angle_bracket_syntax</code> - angle bracket syntax test</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>angle_bracket_syntax</code> - <span class="man-whatis">angle bracket syntax test</span>
+</p>
 
 <p>A <var>WORD</var> in angle brackets is converted to <var>WORD</var>,</p>
 

data/test/basic_document.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>simple</code> - a simple ron example</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>simple</code> - <span class="man-whatis">a simple ron example</span>
+</p>
 
 <p>This document created by ron.</p>
 

data/test/custom_title_document.html

@@ -1,6 +1,5 @@
 <div class='mp'>
-<h1>custom_title_document - This is a custom title</h1>
-
+<h1>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/definition_list_syntax.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>defition_list_syntax</code> - hiya</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>defition_list_syntax</code> - <span class="man-whatis">hiya</span>
+</p>
 
 <p>Definition lists look like unordered lists:</p>
 

data/test/dots_at_line_start_test.roff

@@ -0,0 +1,10 @@
+.TH "DOTS_AT_LINE_START_TEST" "" "January 1979" "" ""
+.
+.SH "NAME"
+\fBdots_at_line_start_test\fR
+.
+.P
+There\'s a weird issue where dots at the beginning of a line generate troff warnings due to escaping\.
+.
+.P
+\&\.\.\. let\'s see what happens\.

data/test/dots_at_line_start_test.ronn

@@ -0,0 +1,4 @@
+There's a weird issue where dots at the beginning of a line
+generate troff warnings due to escaping.
+
+... let's see what happens.

data/test/entity_encoding_test.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>hello</code> - hello world</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>hello</code> - <span class="man-whatis">hello world</span>
+</p>
 
 <p>Your output &lt;i&gt;might&lt;/i&gt; look like this:</p>
 
@@ -10,4 +12,24 @@
 * &lt;b&gt;GitHub&lt;/b&gt;
 </code></pre>
 
+<p>Here's some special entities:</p>
+
+<ul>
+<li>&amp;bull;       &bull;</li>
+<li>&amp;nbsp;       &nbsp;</li>
+<li>&amp;copy;       &copy;</li>
+<li>&amp;rdquo;      &rdquo;</li>
+<li>&amp;mdash;      &mdash;</li>
+<li>&amp;reg;        &reg;</li>
+<li>&amp;sec;        &sec;</li>
+<li>&amp;ge;         &ge;</li>
+<li>&amp;le;         &le;</li>
+<li>&amp;ne;         &ne;</li>
+<li>&amp;equiv;      &equiv;</li>
+</ul>
+
+
+<p>Here's a line that uses non-breaking spaces to force the
+last&nbsp;few&nbsp;words&nbsp;to&nbsp;wrap&nbsp;together.</p>
+
 </div>

data/test/entity_encoding_test.roff

@@ -18,4 +18,44 @@ Your output <i>might</i> look like this:
 .fi
 .
 .IP "" 0
-
+.
+.P
+Here\'s some special entities:
+.
+.IP "\(bu" 4
+&bull; \(bu
+.
+.IP "\(bu" 4
+&nbsp; \~
+.
+.IP "\(bu" 4
+&copy; \(co
+.
+.IP "\(bu" 4
+&rdquo; \(rs
+.
+.IP "\(bu" 4
+&mdash; \(em
+.
+.IP "\(bu" 4
+&reg; \(rg
+.
+.IP "\(bu" 4
+&sec; \(sc
+.
+.IP "\(bu" 4
+&ge; \(>=
+.
+.IP "\(bu" 4
+&le; \(<=
+.
+.IP "\(bu" 4
+&ne; \(!=
+.
+.IP "\(bu" 4
+&equiv; \(==
+.
+.IP "" 0
+.
+.P
+Here\'s a line that uses non\-breaking spaces to force the last\~few\~words\~to\~wrap\~together\.

data/test/entity_encoding_test.ronn

@@ -6,3 +6,20 @@ Your output <i>might</i> look like this:
     *
     * <b>GitHub</b>
     * <b>GitHub</b>
+
+Here's some special entities:
+
+  * &amp;bull;       &bull;
+  * &amp;nbsp;       &nbsp;
+  * &amp;copy;       &copy;
+  * &amp;rdquo;      &rdquo;
+  * &amp;mdash;      &mdash;
+  * &amp;reg;        &reg;
+  * &amp;sec;        &sec;
+  * &amp;ge;         &ge;
+  * &amp;le;         &le;
+  * &amp;ne;         &ne;
+  * &amp;equiv;      &equiv;
+
+Here's a line that uses non-breaking spaces to force the
+last&nbsp;few&nbsp;words&nbsp;to&nbsp;wrap&nbsp;together.

data/test/index.txt

@@ -0,0 +1,8 @@
+# test ronn index
+
+# local manuals
+basic_document(7)             basic_document.ronn
+definition_list_syntax(5)     definition_list_syntax.ronn
+
+# see also
+grep(1)                       http://man.cx/grep(1)

data/test/markdown_syntax.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>markdown</code> - humane markup syntax</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>markdown</code> - <span class="man-whatis">humane markup syntax</span>
+</p>
 
 <h2 id="SYNOPSIS">SYNOPSIS</h2>
 
@@ -949,7 +951,7 @@ also by John Gruber.</p>
 
 <h2 id="SEE-ALSO">SEE ALSO</h2>
 
-<p>ronn(5)<br />
+<p><span class="man-ref">ronn<span class="s">(5)</span></span><br />
 <a href="http://daringfireball.net/projects/markdown/" data-bare-link="true">http://daringfireball.net/projects/markdown/</a></p>
 
 </div>

data/test/markdown_syntax.roff

@@ -647,7 +647,7 @@ In other words, a \fInumber\-period\-space\fR sequence at the beginning of a lin
 .
 .nf
 
-1986\\\. What a great season\.
+1986\e\. What a great season\.
 .
 .fi
 .
@@ -1149,7 +1149,7 @@ To produce a literal asterisk or underscore at a position where it would otherwi
 .
 .nf
 
-\\*this text is surrounded by literal asterisks\\*
+\e*this text is surrounded by literal asterisks\e*
 .
 .fi
 .
@@ -1424,7 +1424,7 @@ Markdown allows you to use backslash escapes to generate literal characters whic
 .
 .nf
 
-\\*literal asterisks\\*
+\e*literal asterisks\e*
 .
 .fi
 .
@@ -1437,7 +1437,7 @@ Markdown provides backslash escapes for the following characters:
 .
 .nf
 
-\\   backslash
+\e   backslash
 `   backtick
 *   asterisk
 _   underscore

data/test/middle_paragraph.html

@@ -1,6 +1,8 @@
 <div class='mp'>
-<h2 id='NAME'>NAME</h2>
-<p><code>test</code> - just a ron test</p>
+<h2 id="NAME">NAME</h2>
+<p class="man-name">
+  <code>test</code> - <span class="man-whatis">just a ron test</span>
+</p>
 
 <h2 id="TEST">TEST</h2>