ronn 0.5 → 0.6.0

data/lib/ronn/template/print.css

@@ -0,0 +1,5 @@
+.mp { max-width:none }
+.man-navigation { display:none !important }
+.mp a[href]:not([href^="#"]):not([data-bare-link]):after {
+  content:" " attr(href);
+}

data/lib/ronn/template/screen.css

@@ -0,0 +1,105 @@
+/* STRUCTURE, INDENT, MARGINS */
+
+body                                { margin:0 }
+#man                                { max-width:88ex; padding:0 2ex 1ex 2ex }
+
+#man p, #man pre,
+#man ul, #man ol, #man dl           { margin:0 0 20px 0 }
+#man h2                             { margin:10px 0 0 0 }
+
+#man > p, #man > pre,
+#man > ul, #man > ol, #man > dl     { margin-left:8ex }
+#man h3                             { margin:0 0 0 4ex }
+
+#man dt                             { margin:0; clear:left }
+#man dt.flush                       { float:left; width:8ex }
+#man dd                             { margin:0 0 0 9ex }
+#man h1, #man h2, #man h3, #man h4  { clear:left }
+
+#man pre                            { margin-bottom:20px }
+#man pre+h2, #man pre+h3            { margin-top:22px }
+#man h2+pre, #man h3+pre            { margin-top:5px }
+
+#man img                            { display:block;margin:auto }
+#man h1.man-title                   { display:none }
+
+/* FONTS */
+
+#man, #man code, #man pre,
+#man tt, #man kbd, #man samp,
+#man h3, #man h4 {
+    font-family:monospace;
+    font-size:14px;
+    line-height:1.42857142857143;
+}
+#man h2, #man ol.man {
+  font-size:16px;
+  line-height:1.25
+}
+#man h1 {
+  font-size:20px;
+  line-height:2;
+}
+
+/* TEXT STYLES */
+
+#man {
+  text-align:justify;
+  background:#fff;
+}
+#man, #man code, #man pre, #man pre code,
+#man tt, #man kbd, #man samp            { color:#131211 }
+#man h1, #man h2, #man h3, #man h4      { color:#030201 }
+#man ol.man, #man ol.man li             { color:#636261 }
+
+#man code, #man strong, #man b {
+    font-weight:bold;
+    color:#131211;
+}
+
+#man em, #man var, #man u {
+    font-style:italic;
+    color:#434241;
+    text-decoration:none;
+}
+
+#man pre {
+    background:#edeceb;
+    padding:5px 1ex;
+    border-left:1ex solid #ddd;
+}
+#man pre code {
+    font-weight:normal;
+    background:inherit;
+}
+
+/* DOCUMENT HEADER AND FOOTER AREAS */
+
+#man ol.man, #man ol.man li {
+    margin:3px 0 10px 0;
+    padding:0;
+    float:left;
+    width:33%;
+    list-style-type:none;
+    text-transform:uppercase;
+    color:#999;
+    letter-spacing:1px;
+}
+#man ol.man                  { width:100% }
+#man ol.man li.tl            { text-align:left }
+#man ol.man li.tc            { text-align:center; letter-spacing:4px }
+#man ol.man li.tr            { text-align:right; float:right }
+
+/* SECTION TOC NAVIGATION */
+
+#man div.man-navigation {
+    position:fixed;
+    top:0;
+    left:96ex;
+    height:100%;
+    width:100%;
+    padding:1ex 0 0 2ex;
+    border-left:0.25ex solid #DCDCDC;
+    background-color: #F5F5F5;
+}
+#man div.man-navigation a { display:block; margin-bottom:1.5ex }

data/lib/ronn/template/toc.css

@@ -0,0 +1,27 @@
+/* toc.css - enable table of contents */
+
+.man-navigation {
+    display:block !important;
+    position:fixed;
+    top:0;
+    left:113ex; /* .mp width + padding */
+    height:100%;
+    width:100%;
+    padding:48px 0 0 0;
+    border-left:1px solid #dbdbdb;
+    background:#eee;
+}
+.man-navigation a,
+.man-navigation a:hover,
+.man-navigation a:link,
+.man-navigation a:visited {
+    display:block;
+    margin:0;
+    padding:5px 2px 5px 30px;
+    color:#999;
+    text-decoration:none;
+}
+.man-navigation a:hover {
+    color:#111;
+    text-decoration:underline;
+}

data/man/ronn.1

@@ -1,171 +1,230 @@
-.\" generated with Ronn/v0.4.2
+.\" generated with Ronn/v0.6.0
 .\" http://github.com/rtomayko/ronn/
 .
-.TH "RONN" "1" "April 2010" "Ryan Tomayko" "Ronn Manual"
+.TH "RONN" "1" "June 2010" "0.6.0" "Ronn 0.6.0"
 .
 .SH "NAME"
-\fBronn\fR \-\- build markdown\-based man pages
+\fBronn\fR \- convert markdown files to manpages
 .
 .SH "SYNOPSIS"
-\fBronn\fR [ \fIOPTIONS\fR ] \fIFILE\fR ...
+\fBronn\fR [\fIoptions\fR] \fIfile\fR\.\.\.
 .
 .br
-\fBronn\fR \-\-build \fIFILE\fR ...
+\fBronn\fR\fB\-m\fR|\fB\-\-man\fR\fIfile\fR\.\.\.
 .
 .br
-\fBronn\fR \-\-install \fIFILE\fR ...
+\fBronn\fR\fB\-S\fR|\fB\-\-server\fR\fIfile\fR\.\.\.
 .
 .br
-\fBronn\fR \-\-man \fIFILE\fR
+\fBronn\fR\fB\-\-pipe\fR\fIfile\fR
+.
+.br
+\fBronn\fR\fI<file\fR
 .
 .SH "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.
+\fBRonn\fR 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\.
 .
 .P
-The \fBronn\fR command converts one or more named input \fIFILE\fRs (or standard
-input when no files are named or the file name \fB\-\fR is given) from humane
-man page markup to one or more destination output formats. If no output
-format is selected explicitly, \fBronn\fR writes output in roff format.
+In its default mode, \fBronn\fR converts one or more input \fIfile\fRs to HTML or UNIX roff output files\. The \fB\-\-roff\fR, \fB\-\-html\fR, and \fB\-\-fragment\fR 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 \fIfile\fRs\.
 .
-.SH "FILES"
-The \fBronn\fR command expects input to be formatted as ronn(5) text.  Source
-files are typically named '\fINAME\fR.\fISECTION\fR.ronn' (e.g., \fBhello.1.ronn\fR).
-The \fINAME\fR and \fISECTION\fR should match the name and section defined in \fIFILE\fR's heading.
+.P
+The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from output file generation to serving dynamically generated HTML manpages or viewing \fIfile\fR as with man(1)\.
 .
 .P
-When building roff and/or HTML output files with the \fB\-\-build\fR argument,
-destination filenames are determined by taking the basename of the input \fIFILE\fR and adding the appropriate file extension (or removing the file
-extension in the case of roff output).
+With no \fIfile\fR arguments, \fBronn\fR acts as simple filter\. Ronn source text is read from standard input and roff output is written to standard output\. The \fB\-\-html\fR and \fB\-\-fragment\fR options can be used to generate that format output instead of roff\.
+.
+.SH "FILES"
+The \fBronn\fR command expects input to be formatted as ronn(5) text\. Source files are typically named \'\fIname\fR\.\fIsection\fR\.ronn\' (e\.g\., \fBexample\.1\.ronn\fR)\. The \fIname\fR and \fIsection\fR should match the name and section defined in the \fIfile\fR\'s heading\.
 .
 .P
-For example, the command \fBronn \-b \-\-html \-\-roff hello.1.ronn\fR generates a \fBhello.1\fR file with roff output and a \fBhello.1.html\fR file with HTML
-output.
+When building roff or HTML output files, destination filenames are determined by taking the basename of the input \fIfile\fR and adding the appropriate file extension (or removing the file extension in the case of roff output)\. For example, executing \fBronn example\.1\.ronn\fR generates \fBexample\.1\fR with roff output and \fBexample\.1\.html\fR with HTML output\.
 .
 .SH "OPTIONS"
-\fBronn\fR'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:
+These options control whether output is written to files, standard output, or directly to a man pager\.
 .
 .TP
-\fB\-b\fR, \fB\-\-build\fR
-Write output directly to files instead of standard output. When the \fB\-\-roff\fR option is provided, writes roff output to \fIfile\fR.\fIsection\fR.
-When the \fB\-\-html\fR option is provided, writes output to
-'\fIfile\fR.\fIsection\fR.html'.
+\fB\-m\fR, \fB\-\-man\fR
+Don\'t generate files, display \fIfile\fRs 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 \fBMANPAGER\fR environment variable\.
 .
 .TP
-\fB\-i\fR, \fB\-\-install\fR
-Install the roff formatted man page to the local system such that it
-can be displayed by man(1). The \fBMANHOME\fR environment variable is
-used to determine the prefix where man pages should be installed
-when defined.
+\fB\-S\fR, \fB\-\-server\fR
+Don\'t generate files, start an HTTP server at \fIhttp://localhost:1207/\fR and serve dynamically generated HTML for the set of input \fIfile\fRs\. A file named \fIexample\.2\.ronn\fR is served as \fI/example\.2\.html\fR\. There\'s also an index page at the root with links to each \fIfile\fR\.
 .
 .IP
-If \fBMANHOME\fR is not defined, \fBronn\fR installs man pages to \fI/usr/local/man\fR.
+The server respects the \fB\-\-style\fR and document attribute options (\fB\-\-manual\fR, \fB\-\-date\fR, etc\.)\. These same options can be varied at request time by giving them as query parameters: \fB?manual=FOO&style=dark,toc\fR
+.
+.IP
+\fINOTE: 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\.\fR
 .
 .TP
-\fB\-m\fR, \fB\-\-man\fR
-Display \fIFILE\fRs 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 \fBMANPAGER\fR
-environment variable.
+\fB\-\-pipe\fR
+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 \fIfile\fR arguments are provided\.
 .
 .P
-These options control the format used in generated output:
+Format options control the files \fBronn\fR generates, or the output format when the \fB\-\-pipe\fR argument is specified\. When no format options are given, both \fB\-\-roff\fR and \fB\-\-html\fR are assumed\.
 .
 .TP
 \fB\-r\fR, \fB\-\-roff\fR
-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 \fIfile\fRs are given and ronn source text is read from standard input\.
 .
 .TP
 \fB\-5\fR, \fB\-\-html\fR
-Generate output in HTML format.
+Generate output in HTML format\.
 .
 .TP
 \fB\-f\fR, \fB\-\-fragment\fR
-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\.
 .
 .P
-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 \fIENVIRONMENT\fR\.)
 .
 .TP
-\fB\-\-manual\fR=\fIMANUAL\fR
-The name of the manual this man page belongs to; \fIMANUAL\fR is
-prominently displayed top\-center in the header area.
+\fB\-\-manual\fR=\fImanual\fR
+The name of the manual this man page belongs to; \fImanual\fR is prominently displayed top\-center in the header area\.
 .
 .TP
-\fB\-\-organization\fR=\fINAME\fR
-The name of the group, organization, or individual responsible for
-publishing the document; \fINAME\fR is displayed in the bottom\-left
-footer area.
+\fB\-\-organization\fR=\fIname\fR
+The name of the group, organization, or individual responsible for publishing the document; \fIname\fR is displayed in the bottom\-left footer area\.
 .
 .TP
-\fB\-\-date\fR=\fIDATE\fR
-The document's published date; \fIDATE\fR must be formatted \fBYYYY\-MM\-DD\fR
-and is displayed in the bottom\-center footer area. The \fIFILE\fR mtime
-is used when no \fIDATE\fR is given, or the current time when no \fIFILE\fR
-is available.
+\fB\-\-date\fR=\fIdate\fR
+The document\'s published date; \fIdate\fR must be formatted \fBYYYY\-MM\-DD\fR and is displayed in the bottom\-center footer area\. The \fIfile\fR mtime is used when no \fIdate\fR is given, or the current time when no \fIfile\fR is available\.
+.
+.P
+HTML output can be customized variously:
+.
+.TP
+\fB\-\-style\fR=\fImodule\fR[,\fImodule\fR]\.\.\.
+The list of CSS stylesheets to apply to the document\. Multiple \fImodule\fR arguments may be specified, but must be separated by commas or spaces\.
+.
+.IP
+When \fImodule\fR is a simple word, search for files named \fImodule\fR\fB\.css\fR in all directories listed in the \fI\fBRONN_STYLE\fR\fR environment variable, and then search internal styles\.
+.
+.IP
+When \fImodule\fR includes a \fI/\fR character, use it as the full path to a stylesheet file\.
+.
+.IP
+Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\. See \fISTYLES\fR for descriptions of features added by each module\.
+.
+.P
+Miscellaneous options:
+.
+.TP
+\fB\-w\fR, \fB\-\-warnings\fR
+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\.
+.
+.TP
+\fB\-W\fR
+Disable troff warnings\. Warnings are disabled by default\. This option can be used to revert the effect of a previous \fB\-w\fR argument\.
+.
+.SH "STYLES"
+The \fB\-\-style\fR 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\.
+.
+.SS "Internal Stylesheets"
+These styles are included with the distribution:
+.
+.TP
+\fBman\fR
+Basic manpage styles: typography, definition lists, indentation\. This is always included regardless of \fB\-\-style\fR argument\. It is however possible to replace the default \fBman\fR module with a custom one by placing a \fBman\.css\fR file on the \fBRONN_STYLE\fR path\.
+.
+.TP
+\fBprint\fR
+Basic print stylesheet\. The generated \fB<style>\fR tag includes a \fBmedia=print\fR attribute\.
+.
+.TP
+\fBtoc\fR
+Enables the Table of Contents navigation\. The TOC markup is included in generated HTML by default but hidden with an inline \fBdisplay:none\fR style rule; the \fBtoc\fR module turns it on and applies basic TOC styles\.
+.
+.TP
+\fBdark\fR
+Light text on a dark background\.
+.
+.TP
+\fB80c\fR
+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\.
+.
+.SS "Custom Stylesheets"
+Writing custom stylesheets is straight\-forward\. The following core selectors allow targeting all generated elements:
+.
+.TP
+\fB\.mp\fR
+The manual page container element\. Present on full documents and document fragments\.
+.
+.TP
+\fBbody#manpage\fR
+Signifies that the page was fully\-generated by Ronn and contains a single manual page (\fB\.mp\fR element)\.
+.
+.TP
+\fB\.man\-decor\fR
+The three\-item heading and footing elements both have this class\.
+.
+.TP
+\fB\.man\-head\fR, \fB\.man\-foot\fR
+The heading and footing, respectively\.
+.
+.TP
+\fB\.man\-title\fR
+The main \fB<h1>\fR element\. Hidden by default unless the manual has no \fIname\fR or \fIsection\fR attributes\.
+.
+.P
+See the internal style sources \fIhttp://github\.com/rtomayko/ronn/tree/master/lib/ronn/template\fR for examples\.
 .
 .SH "EXAMPLES"
-Generate \fBroff(7)\fR output on stdout:
+Build roff and HTML output files and view the roff manpage using man(1):
 .
 .IP "" 4
 .
 .nf
 
-$ 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
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Build a roff file based on the input filename:
+Build only the roff manpage for all \fB\.ronn\fR files in the current directory:
 .
 .IP "" 4
 .
 .nf
 
-$ 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
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Build and open a standalone HTML file based on the input filename:
+Build only the HTML manpage for a few files and apply the \fBdark\fR and \fBtoc\fR stylesheets:
 .
 .IP "" 4
 .
 .nf
 
-$ 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
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Build roff and HTML versions of all \fB.ronn\fR files in the current
-directory:
+Generate roff output on standard output and write to file:
 .
 .IP "" 4
 .
 .nf
 
-$ 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
 .
 .fi
 .
@@ -178,20 +237,21 @@ View a ronn file in the same way as man(1) without building a roff file:
 .
 .nf
 
-$ ronn \-m hello.1.ronn
+$ ronn \-\-man hello\.1\.ronn
 .
 .fi
 .
 .IP "" 0
 .
 .P
-Install the roff man page for a ronn file:
+Serve HTML manpages at \fIhttp://localhost:1207/\fR for all \fB*\.ronn\fR files under a \fBman/\fR directory:
 .
 .IP "" 4
 .
 .nf
 
-$ ronn \-i hello.1.ronn
+$ ronn \-\-server man/*\.ronn
+$ open http://localhost:1207/
 .
 .fi
 .
@@ -200,27 +260,34 @@ $ ronn \-i hello.1.ronn
 .SH "ENVIRONMENT"
 .
 .TP
-\fBMANHOME\fR
-Location where roff formatted man pages are installed.  Relevant
-only when the \fB\-\-install\fR argument is provided.  \fIPATH\fR is to the
-base of a man file hierarchy. e.g., \fB/usr/local/share/man\fR, \fB/home/rtomayko/man\fR.
+\fBRONN_MANUAL\fR
+A default manual name to be displayed in the top\-center header area\. The \fB\-\-manual\fR option takes precedence over this value\.
+.
+.TP
+\fBRONN_ORGANIZATION\fR
+The default manual publishing group, organization, or individual to be displayed in the bottom\-left footer area\. The \fB\-\-organization\fR option takes precedence over this value\.
+.
+.TP
+\fBRONN_DATE\fR
+The default manual date in \fBYYYY\-MM\-DD\fR format\. Displayed in the bottom\-center footer area\. The \fB\-\-date\fR option takes precedence over this value\.
+.
+.TP
+\fBRONN_STYLE\fR
+A \fBPATH\fR\-style list of directories to check for stylesheets given to the \fB\-\-style\fR option\. Directories are separated by a \fI:\fR; blank entries are ignored\. Use \fI\.\fR to include the current working directory\.
 .
 .TP
 \fBMANPAGER\fR
-The paging program used for man pages. This is typically set to
-something like 'less \-is'.
+The paging program used for man pages\. This is typically set to something like \'less \-is\'\.
 .
 .TP
 \fBPAGER\fR
-Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined.
+Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
 .
 .SH "BUGS"
-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.
+\fBRonn\fR 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\.
 .
 .SH "COPYRIGHT"
-Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko\.com/about>
 .
 .SH "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)