From 387b29c7302af8a5e045e0ef5ad8ec56f5c6c243 Mon Sep 17 00:00:00 2001 From: "Rico Sta. Cruz" Date: Sat, 18 Apr 2015 04:24:29 +0800 Subject: [PATCH] Fix ronn stuff --- ronn.1 | 349 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ronn.md | 69 +++++++---- 2 files changed, 397 insertions(+), 21 deletions(-) create mode 100644 ronn.1 diff --git a/ronn.1 b/ronn.1 new file mode 100644 index 000000000..f39de4090 --- /dev/null +++ b/ronn.1 @@ -0,0 +1,349 @@ +.TH "RONN" "1" "April 2015" "" "" +.SH "NAME" +\fBronn\fR \- convert markdown files to manpages +.SH SYNOPSIS +.P +\fBronn\fR [\|\.\.\.] \|\.\.\. +.br +\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \|\.\.\. +.br +\fBronn\fR \fB\-S\fR|\fB\-\-server\fR \|\.\.\. +.br +\fBronn\fR \fB\-\-pipe\fR +.br +\fBronn\fR < +.SH DESCRIPTION +.P +\fBRonn\fR 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\. +.P +In its default mode, \fBronn\fR converts one or more input s to HTML or 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 s\. +.P +The \fB\-\-server\fR and \fB\-\-man\fR options change the output behavior from file +generation to serving dynamically generated HTML manpages or viewing as +with man(1)\. +.P +With no arguments, \fBronn\fR acts as simple filter\. Ronn source text is read +from standard input and roff output is written to standard output\. Use the +\fB\-\-html\fR, \fB\-\-roff\fR, and/or \fB\-\-fragment\fR options to select the output format\. +.SH FILES +.P +The \fBronn\fR command expects input to be valid ronn\-format(7) text\. Source files +are typically named \|\.
\|\.ronn (e\.g\., \fBexample\.1\.ronn\fR)\. The +and
should match the name and section defined in the \|'s heading\. +.P +When building roff or HTML output files, destination filenames are determined by +taking the basename of the input 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 +.P +These options control whether output is written to file(s), standard output, or +directly to a man pager\. +.P +\fB\-m\fR, \fB\-\-man\fR +: Don't generate files, display 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 \fBMANPAGER\fR + environment variable\. +.RS 0 +.IP \(bu 2 +\fB\-S\fR, \fB\-\-server\fR: +Don't generate files, start an HTTP server at http://localhost:1207/ and +serve dynamically generated HTML for the set of input s\. 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 \|\. +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 +\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 +.IP \(bu 2 +\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 + arguments are provided\. + +.RE +.P +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\. +.RS 0 +.IP \(bu 2 +\fB\-r\fR, \fB\-\-roff\fR: +Generate roff output\. This is the default behavior when no s are given +and ronn source text is read from standard input\. +.IP \(bu 2 +\fB\-5\fR, \fB\-\-html\fR: +Generate output in HTML format\. +.IP \(bu 2 +\fB\-f\fR, \fB\-\-fragment\fR: +Generate output in HTML format but only the document fragment, not the +header, title, or footer\. + +.RE +.P +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][]\.) +.RS 0 +.IP \(bu 2 +\fB\-\-manual\fR=: +The name of the manual this man page belongs to; is prominently +displayed top\-center in the header area\. +.IP \(bu 2 +\fB\-\-organization\fR=: +The name of the group, organization, or individual responsible for +publishing the document; is displayed in the bottom\-left footer area\. +.IP \(bu 2 +\fB\-\-date\fR=: +The document's published date; must be formatted \fBYYYY\-MM\-DD\fR and is +displayed in the bottom\-center footer area\. The mtime is used when no + is given, or the current time when no is available\. + +.RE +.P +HTML output can be customized through the use of CSS stylesheets: +.RS 0 +.IP \(bu 2 +\fB\-\-style\fR=[,]\.\.\.: +The list of CSS stylesheets to apply to the document\. Multiple +arguments may be specified, but must be separated by commas or spaces\. +When is a simple word, search for files named \fB\|\.css\fR in all +directories listed in the \fBRONN_STYLE\fR \fI#ENVIRONMENT\fR environment variable, +and then search internal styles\. +When includes a \fI/\fR character, use it as the full path to a +stylesheet file\. +Internal styles are \fIman\fR (included by default), \fItoc\fR, and \fI80c\fR\|\. See +[STYLES][] for descriptions of features added by each module\. + +.RE +.P +Miscellaneous options: +.RS 0 +.IP \(bu 2 +\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\. +.IP \(bu 2 +\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\. +.IP \(bu 2 +\fB\-v\fR, \fB\-\-version\fR: +Show ronn version and exit\. + +.RE +.SH LINK INDEXES +.P +When generating HTML output, \fBronn\fR hyperlinks manual references (like +\fBgrep(1)\fR, \fBls(1)\fR, \fBmarkdown(7)\fR) in source text based on reference name to URL +mappings defined in an \fBindex\.txt\fR file\. Each line of the index file describes a +single reference link, with whitespace separating the reference's from its +.P +\|\. Blank lines are allowed; lines beginning with a \fB#\fR character are +ignored: +.P +.RS 2 +.nf +# 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/ +.fi +.RE +.P +The 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\. +.P +All manuals in an individual directory share the references defined in that +directory's \fBindex\.txt\fR file\. Index references may be used explicitly in +Markdown reference style links using the syntax: \fB[\fR\fB][\fR\fB]\fR, where +.P + is the link text and is a reference name defined in the index\. +.SH STYLES +.P +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 Builtin Stylesheets +.P +These styles are included with the distribution: +.RS 0 +.IP \(bu 2 +\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\. +.IP \(bu 2 +\fBprint\fR: +Basic print stylesheet\. The generated \fB