ronn 0.5 → 0.6.0

data/man/ronn.1.ronn

@@ -1,140 +1,257 @@
-ronn(1) -- build markdown-based man pages
-========================================
+ronn(1) -- convert markdown files to manpages
+=============================================
 
 ## SYNOPSIS
 
-`ronn` [ <OPTIONS> ] <FILE> ...  
-`ronn` --build <FILE> ...  
-`ronn` --install <FILE> ...  
-`ronn` --man <FILE>
+`ronn` [<options>] <file>...<br>
+`ronn` `-m`|`--man` <file>...<br>
+`ronn` `-S`|`--server` <file>...<br>
+`ronn` `--pipe` <file><br>
+`ronn` < <file>
 
 ## DESCRIPTION
 
-Ronn is a humane text format and toolchain for authoring man pages, and
-things that appear as man pages from a distance. Use it to build and
-install standard UNIX / roff(7) formatted man pages and to generate
-nicely formatted HTML manual pages.
+**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.
 
-The `ronn` command converts one or more named input <FILE>s (or standard
-input when no files are named or the file name `-` is given) from humane
-man page markup to one or more destination output formats. If no output
-format is selected explicitly, `ronn` writes output in roff format.
+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
+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
+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.
 
 ## FILES
 
 The `ronn` command expects input to be formatted as ronn(5) text.  Source
-files are typically named '<NAME>.<SECTION>.ronn' (e.g., `hello.1.ronn`).
-The <NAME> and <SECTION> should match the name and section defined in
-<FILE>'s heading.
-
-When building roff and/or HTML output files with the `--build` argument,
-destination filenames are determined by taking the basename of the input
-<FILE> and adding the appropriate file extension (or removing the file
-extension in the case of roff output).
+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.
 
-For example, the command `ronn -b --html --roff hello.1.ronn` generates a
-`hello.1` file with roff output and a `hello.1.html` file with HTML
-output.
+When building roff or HTML output files, destination filenames are determined by
+taking the basename of the input <file> and adding the appropriate file
+extension (or removing the file extension in the case of roff output).  For
+example, executing `ronn example.1.ronn` generates `example.1` with roff output
+and `example.1.html` with HTML output.
 
 ## OPTIONS
 
-`ronn`'s default mode of operation is to read a single document from
-standard input and to write the result to standard output. The following
-arguments change this behavior:
-
-  * `-b`, `--build`:
-    Write output directly to files instead of standard output. When the
-    `--roff` option is provided, writes roff output to <file>.<section>.
-    When the `--html` option is provided, writes output to
-    '<file>.<section>.html'.
-
-  * `-i`, `--install`:
-    Install the roff formatted man page to the local system such that it
-    can be displayed by man(1). The `MANHOME` environment variable is
-    used to determine the prefix where man pages should be installed
-    when defined.
-
-    If `MANHOME` is not defined, `ronn` installs man pages to
-    _/usr/local/man_.
+These options control whether output is written to files, standard output, or
+directly to a man pager.
 
   * `-m`, `--man`:
-    Display <FILE>s as if man(1) were invoked on the roff output file.
-    This simulates default man behavior by piping the roff output
+    Don't generate files, display <file>s as if man(1) were invoked on the roff
+    output file. This simulates default man behavior by piping the roff output
     through groff(1) and the paging program specified by the `MANPAGER`
     environment variable.
 
-These options control the format used in generated output:
+  * `-S`, `--server`:
+    Don't generate files, start an HTTP server at <http://localhost:1207/> and
+    serve dynamically generated HTML for the set of input <file>s. A file named
+    *example.2.ronn* is served as */example.2.html*. There's also an index page
+    at the root with links to each <file>.
+
+    The server respects the `--style` and document attribute options
+    (`--manual`, `--date`, etc.). These same options can be varied at request
+    time by giving them as query parameters: `?manual=FOO&style=dark,toc`
+
+    *NOTE: The builtin server is designed to assist in the process of writing
+    and styling manuals. It is in no way recommended as a general purpose web
+    server.*
+
+  * `--pipe`:
+    Don't generate files, write generated output to standard output. This is the
+    default behavior when ronn source text is piped in on standard input and no
+    <file> arguments are provided.
+
+Format options control the files `ronn` generates, or the output format when the
+`--pipe` argument is specified. When no format options are given, both `--roff`
+and `--html` are assumed.
 
   * `-r`, `--roff`:
-    Generate roff output. This is the default behavior when no other
-    format argument is provided.
+    Generate roff output. This is the default behavior when no <file>s are given
+    and ronn source text is read from standard input.
 
   * `-5`, `--html`:
     Generate output in HTML format.
 
   * `-f`, `--fragment`:
-    Generate output in HTML format but only the document fragment, not
-    the header, title, or footer.
+    Generate output in HTML format but only the document fragment, not the
+    header, title, or footer.
 
-All document attributes displayed in the header and footer areas of
-generated content can be specified with these options:
+Document attributes displayed in the header and footer areas of generated
+content are specified with these options. (These values may also be set via
+the [ENVIRONMENT][].)
 
-  * `--manual`=<MANUAL>:
-    The name of the manual this man page belongs to; <MANUAL> is
-    prominently displayed top-center in the header area.
+  * `--manual`=<manual>:
+    The name of the manual this man page belongs to; <manual> is prominently
+    displayed top-center in the header area.
 
-  * `--organization`=<NAME>:
+  * `--organization`=<name>:
     The name of the group, organization, or individual responsible for
-    publishing the document; <NAME> is displayed in the bottom-left
-    footer area.
+    publishing the document; <name> is displayed in the bottom-left footer area.
+
+  * `--date`=<date>:
+    The document's published date; <date> must be formatted `YYYY-MM-DD` and is
+    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:
+
+  * `--style`=<module>[,<module>]...:
+    The list of CSS stylesheets to apply to the document. Multiple <module>
+    arguments may be specified, but must be separated by commas or spaces.
+
+    When <module> is a simple word, search for files named <module>`.css` in all
+    directories listed in the [`RONN_STYLE`](#ENVIRONMENT) environment variable,
+    and then search internal styles.
+
+    When <module> includes a _/_ character, use it as the full path to a
+    stylesheet file.
+
+    Internal styles are _man_ (included by default), _toc_, and _80c_.  See
+    [STYLES][] for descriptions of features added by each module.
+
+Miscellaneous options:
+
+  * `-w`, `--warnings`:
+    Show troff warnings on standard error when performing roff conversion.
+    Warnings are most often the result of a bug in ronn's HTML to roff conversion
+    logic.
+
+  * `-W`:
+    Disable troff warnings. Warnings are disabled by default. This option can be
+    used to revert the effect of a previous `-w` argument.
+
+## STYLES
 
-  * `--date`=<DATE>:
-    The document's published date; <DATE> must be formatted `YYYY-MM-DD`
-    and is 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.
+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
+
+These styles are included with the distribution:
+
+   * `man`:
+     Basic manpage styles: typography, definition lists, indentation. This is
+     always included regardless of `--style` argument. It is however possible to
+     replace the default `man` module with a custom one by placing a `man.css`
+     file on the `RONN_STYLE` path.
+
+   * `print`:
+     Basic print stylesheet. The generated `<style>` tag includes a
+     `media=print` attribute.
+
+   * `toc`:
+     Enables the Table of Contents navigation. The TOC markup is included in
+     generated HTML by default but hidden with an inline `display:none` style
+     rule; the `toc` module turns it on and applies basic TOC styles.
+
+   * `dark`:
+     Light text on a dark background.
+
+   * `80c`:
+     Changes the display width to mimic the display of a classic 80 character
+     terminal. The default display width causes lines to wrap at a gratuitous
+     100 characters.
+
+### Custom Stylesheets
+
+Writing custom stylesheets is straight-forward. The following core selectors
+allow targeting all generated elements:
+
+   * `.mp`:
+     The manual page container element. Present on full documents and document
+     fragments.
+
+   * `body#manpage`:
+     Signifies that the page was fully-generated by Ronn and contains a single
+     manual page (`.mp` element).
+
+   * `.man-decor`:
+     The three-item heading and footing elements both have this class.
+
+   * `.man-head`, `.man-foot`:
+     The heading and footing, respectively.
+
+   * `.man-title`:
+     The main `<h1>` element. Hidden by default unless the manual has no <name>
+     or <section> attributes.
+
+See the [internal style sources][internal] for examples.
+
+[internal]: http://github.com/rtomayko/ronn/tree/master/lib/ronn/template
+            "internal stylesheet sources"
 
 ## EXAMPLES
 
-Generate `roff(7)` output on stdout:
+Build roff and HTML output files and view the roff manpage using man(1):
 
-    $ ronn < hello.1.ronn
+    $ ronn some-great-program.1.ronn
+    roff: some-great-program.1
+    html: some-great-program.1.html
+    $ man ./some-great-program.1
 
-Build a roff file based on the input filename:
+Build only the roff manpage for all `.ronn` files in the current directory:
 
-    $ ronn -b hello.1.ronn
-    building: hello.1
-    $ man hello.1
+    $ ronn --roff *.ronn
+    roff: mv.1
+    roff: ls.1
+    roff: cd.1
+    roff: sh.1
 
-Build and open a standalone HTML file based on the input filename:
+Build only the HTML manpage for a few files and apply the `dark` and `toc`
+stylesheets:
 
-    $ ronn -b --html test.1.ronn
-    $ open test.1.html
+    $ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
+    html: mv.1.html
+    html: ls.1.html
 
-Build roff and HTML versions of all `.ronn` files in the current
-directory:
+Generate roff output on standard output and write to file:
 
-    $ ronn -b --roff --html *.ronn
-    building: hello.1
-    building: hello.1.html
-    building: world.1
-    building: world.1.html
+    $ ronn <hello.1.ronn >hello.1
 
 View a ronn file in the same way as man(1) without building a roff file:
 
-    $ ronn -m hello.1.ronn
+    $ ronn --man hello.1.ronn
+
+Serve HTML manpages at <http://localhost:1207/> for all `*.ronn` files
+under a `man/` directory:
 
-Install the roff man page for a ronn file:
+    $ ronn --server man/*.ronn
+    $ open http://localhost:1207/
 
-    $ ronn -i hello.1.ronn
 
 ## ENVIRONMENT
 
-  * `MANHOME`:
-    Location where roff formatted man pages are installed.  Relevant
-    only when the `--install` argument is provided.  <PATH> is to the
-    base of a man file hierarchy. e.g., `/usr/local/share/man`,
-    `/home/rtomayko/man`.
+  * `RONN_MANUAL`:
+    A default manual name to be displayed in the top-center header area.
+    The `--manual` option takes precedence over this value.
+
+  * `RONN_ORGANIZATION`:
+    The default manual publishing group, organization, or individual to be
+    displayed in the bottom-left footer area. The `--organization` option takes
+    precedence over this value.
+
+  * `RONN_DATE`:
+    The default manual date in `YYYY-MM-DD` format. Displayed in the
+    bottom-center footer area. The `--date` option takes precedence over this
+    value.
+
+  * `RONN_STYLE`:
+    A `PATH`-style list of directories to check for stylesheets given to the
+    `--style` option. Directories are separated by a _:_; blank entries are
+    ignored. Use _._ to include the current working directory.
 
   * `MANPAGER`:
     The paging program used for man pages. This is typically set to
@@ -145,7 +262,7 @@ Install the roff man page for a ronn file:
 
 ## BUGS
 
-Ronn is written in Ruby and depends on hpricot and rdiscount, extension
+**Ronn** is written in Ruby and depends on hpricot and rdiscount, extension
 libraries that are non-trivial to install on some systems. A more portable
 version of this program would be welcome.
 
@@ -155,4 +272,4 @@ Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
 
 ## SEE ALSO
 
-ronn(5), markdown(5), manpages(5), man(1), roff(7), groff(1)
+ronn(5), (7), manpages(5), man(1), roff(7), groff(1), markdown(7)

data/man/ronn.5

@@ -1,89 +1,93 @@
-.\" generated with Ronn/v0.4.2
+.\" generated with Ronn/v0.6.0
 .\" http://github.com/rtomayko/ronn/
 .
-.TH "RONN" "5" "March 2010" "Ryan Tomayko" "Ronn Manual"
+.TH "RONN" "5" "June 2010" "0.6.0" "Ronn 0.6.0"
 .
 .SH "NAME"
-\fBronn\fR \-\- humane manual page authoring format
+\fBronn\fR \- markdown\-based text format for authoring manpages
 .
 .SH "SYNOPSIS"
 .
 .nf
 
-name(1) \-\- one sentence description
-===================================
+name(1) \-\- short, single\-sentence description
+=============================================
+
+## SYNOPSIS
+
+`name` [<optional>\.\.\.] <flags>
+
+## DESCRIPTION
 
-## SECTION HEADING
+A normal paragraph\. This can span multiple lines and is terminated with two
+or more line endings \-\- just like Markdown\.
 
-A normal paragraph. This can span multiple lines and is
-terminated with two or more line endings \-\- just like
-Markdown.
+Inline markup for `code`, `user input`, and **strong** are displayed
+boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics or
+underline\.
 
-## INLINE MARKUP
+Manual references like sh(1), markdown(7), roff(7), etc\. are displayed in
+boldface and hyperlinked in HTML output\.
 
-Inline markup is used for `code` and `user input` (displayed
-in boldface), and also <variables> or _emphasis_.
+Link to other sections like [STANDARDS][], [SEE ALSO][], or
+[WITH A DIFFERENT LINK TEXT][#SEE\-ALSO]\.
 
-Manual page references like sh(1), markdown(5), roff(7), etc.
-are displayed in boldface and hyperlinked in HTML output.
+Definition lists:
 
-## DEFINITION LISTS
+  * `\-a`, `\-\-argument`=[<value>]:
+    One or more paragraphs describing the argument\.
+  * You can put whatever you *want* here, really:
+    Nesting and paragraph spacing are respected\.
 
-Definition lists are used to define options, arguments,
-variables, and other type of terms:
+Markdown ordered and unordered lists too\.
 
-  * `\-a`, `\-\-arg1`=[_OPTION_]:
-    One or more paragraphs describing the argument.
-  * `\-b`, `\-\-arg2`:
-    Any number of these may be specified and may
-    be nested.
+Frequently used sections:
+
+## OPTIONS
+## SYNTAX
+## ENVIRONMENT
+## RETURN VALUES
+## STANDARDS
+## SECURITY CONSIDERATIONS
+## BUGS
+## HISTORY
+## AUTHOR
+## COPYRIGHT
+## SEE ALSO
 .
 .fi
 .
 .SH "DESCRIPTION"
-Ronn 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). Ronn files are piped through ronn(1)
-to build and install traditional roff(7) man pages or to generate
-hyperlinked HTML documentation.
+Ronn is a source format for authoring UNIX manpages\. The syntax includes all Markdown formatting features, plus conventions for expressing the structure and various notations present in standard UNIX manpages\.
+.
+.P
+Ronn files can be converted to traditional roff\-formatted manpages or to HTML using the ronn(1) command\.
 .
 .P
-All ronn 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 ronn.
+Not all roff(7) typesetting features can be expressed using ronn syntax\.
 .
 .SH "MANPAGE TITLE"
-All man pages have a \fIname\fR, belong to a \fIsection\fR, and have a
-single sentence \fItagline\fR (useless but witty, preferably). Ronn
-files must begin with a first\-level heading that includes all of
-this information. For example, this very man page begins:
+Manpages have a \fIname\fR, \fIsection\fR number, and one\-line \fIdescription\fR\. Ronn files must start with a level one heading defining these attributes:
 .
 .IP "" 4
 .
 .nf
 
-ronn(5) \-\- humane manual page authoring format
-=============================================
+ls(1) \-\- list directory contents
+================================
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Here, we're saying that the man page documents a thing named \fBronn\fR in manual section \fB5\fR (the "file formats" section; see
-manpages(5) for full section list) and that's quickly described
-as a "humane manual page authoring format".
-.
-.P
-These bits of information are used to fill in the document
-header, to create the \fBNAME\fR section, and also to establish
-output filenames when processed with ronn(1).
+Indicates that the manpage is named \fBls\fR in manual section \fB1\fR (\"user commands\")\.
 .
 .SH "SECTION HEADINGS"
-Man section headings are expressed with markdown level two
-headings. markdown(5) provides two syntaxes for level two
-headings. A hash prefix syntax:
+Man section headings are expressed with markdown level two headings\. There are two syntaxes for level two headings\.
+.
+.P
+Hash prefix syntax:
 .
 .IP "" 4
 .
@@ -96,7 +100,7 @@ headings. A hash prefix syntax:
 .IP "" 0
 .
 .P
-Or, a dash underline syntax:
+Dash underline syntax:
 .
 .IP "" 4
 .
@@ -110,98 +114,92 @@ HEADING TEXT
 .IP "" 0
 .
 .P
-Section headings should be in all uppercase and may not contain
-other inline markup.
-.
-.P
-Most manual pages include at least one of the \fBSYNOPSIS\fR, \fBDESCRIPTION\fR, and/or \fBOPTIONS\fR sections. Additional sections
-commonly included are \fBSYNTAX\fR, \fBENVIRONMENT\fR, \fBHISTORY\fR, \fBRETURN
-VALUES\fR, \fBBUGS\fR, \fBSECURITY CONSIDERATIONS\fR, \fBSTANDARDS\fR / \fBCONFORMING TO\fR, \fBAUTHOR\fR, and \fBCOPYRIGHT\fR. Finally, most man
-pages end with a \fBSEE ALSO\fR section that references other manual
-pages and external documents.
+Section headings should be all uppercase and may not contain inline markup\.
 .
 .SH "INLINE MARKUP"
-Man pages have a limited set of text formatting capabilities at
-their disposal. There's basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR). Ronn uses
-the following bits of markdown(5) to accomplish this:
+Manpages have a limited set of text formatting capabilities\. There\'s basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR)\. Ronn uses the following bits of markdown(7) to accomplish this:
 .
 .TP
 \fB`backticks`\fR
-Code, flags, commands, and noun\-like things; typically
-displayed in in \fBboldface\fR. Note that all text included
-within \fBbackticks\fR is displayed literally; other inline markup
-is not processed.
+Code, flags, commands, and noun\-like things; typically displayed in in \fBboldface\fR\. Note that all text included within \fBbackticks\fR is displayed literally; other inline markup is not processed\.
 .
 .TP
 \fB**double\-stars**\fR
-Like \fBbackticks\fR but inline markup is processed.
+Like \fBbackticks\fR but inline markup is processed\.
 .
 .TP
 \fB_\fR\fIunderbars\fR\fB_\fR
-User\-specified arguments, variables, or user input; typically
-displayed with \fIunderline\fR.
+User\-specified arguments, variables, or user input; typically displayed with \fIunderline\fR\.
 .
 .TP
 \fB<angle\-quotes>\fR
-Same as \fIunderbars\fR. This is not compatible with Markdown.
+Same as \fIunderbars\fR\. This is not compatible with Markdown\.
 .
 .P
-Here is grep(1)'s DESCRIPTION section represented in \fBronn\fR:
+Here is grep(1)\'s DESCRIPTION section represented in \fBronn\fR:
 .
 .IP "" 4
 .
 .nf
 
-`Grep` searches the named input _FILE_ (or standard input if
+`Grep` searches the named input <FILE> (or standard input if
 no files are named, or the file name `\-` is given) for lines
-containing a match to the given _PATTERN_. By default, `grep`
-prints the matching lines.
+containing a match to the given <PATTERN>\. By default, `grep`
+prints the matching lines\.
 .
 .fi
 .
 .IP "" 0
 .
 .SH "DEFINITION LISTS"
-Because definition lists are so often used in manual pages to
-describe arguments, options, and variables, the basic markdown(5)
-list syntax has been extended to support a definition list
-syntax.
+The definition list syntax is exactly the same as markdown\'s unordered list syntax but requires that the first line of each list item be terminated with a colon \"\fB:\fR\" character\. The contents of the first line (without the colon) is the \fIterm\fR; subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists\.
 .
 .P
-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 "\fB:\fR". The first line (minus
-the colon) is the \fIterm\fR; subsequent lines may be comprised of
-multiple paragraphs, code blocks, standard lists, and nested
-definition lists.
+An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
+.
+.IP "" 4
+.
+.nf
+
+ The following primaries are used to construct expressions:
+
+   * `\-b` <file>:
+     True if <file> exists and is a block special file\.
+
+   * `\-c` <file>:
+     True if _file_ exists and is a character special file\.
+
+   * `\-d` <file>:
+     True if file exists and is a directory\.
+.
+.fi
+.
+.IP "" 0
 .
 .P
-An example definition list, taken from BSD test(1)'s \fBDESCRIPTION\fR section:
+The definition list syntax is intentionally backward compatible with markdown(7)\'s list syntax\. This allows \fBronn\fR documents to be piped through normal markdown processors with minor degradation in output formatting\.
+.
+.SH "LINKS"
+Ronn supports all markdown(7) linking features\. Additionally, section headings can be linked using reference\-style links:
 .
 .IP "" 4
 .
 .nf
 
- The following primaries are used to construct expressions:
+## SECTION 1
 
-   * `\-b` _file_:
-     True if _file_ exists and is a block special file.
+See the following section\.
 
-   * `\-c` _file_:
-     True if _file_ exists and is a character special file.
+## SECTION 2
 
-   * `\-d` _file_:
-     True if file exists and is a directory.
+See [SECTION 1][] or [to put it another way][SECTION 1]\.
 .
 .fi
 .
 .IP "" 0
 .
 .P
-The definition list syntax is intentionally backward compatible
-with markdown(5)'s list syntax. This allows \fBronn\fR documents to be
-piped through normal markdown processors with minor degradation
-in output formatting.
+The anchor name would be \fB#SECTION\-1\fR and \fB#SECTION\-2\fR\. All non\-word characters are removed and spaces are replaced by dashes\.
 .
 .SH "SEE ALSO"
-ronn(1), markdown(5), manpages(5)
+ronn(1), markdown(7), roff(7)