nronn 0.10.1.pre2

data/man/ronn-format.7.ronn

@@ -0,0 +1,157 @@
+ronn-format(7) -- manual authoring format based on Markdown
+===========================================================
+
+## SYNOPSIS
+
+    name(1) -- short, single-sentence description
+    =============================================
+
+    ## SYNOPSIS
+
+    `name` [<optional>...] <flags>
+
+    ## DESCRIPTION
+
+    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
+    (HTML) or underline (roff).
+
+    Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
+    HTML output.
+
+    Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
+    TEXT][#SEE-ALSO].
+
+    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.
+
+    Frequently used sections:
+
+    ## OPTIONS
+    ## SYNTAX
+    ## ENVIRONMENT
+    ## RETURN VALUES
+    ## STANDARDS
+    ## SECURITY CONSIDERATIONS
+    ## BUGS
+    ## HISTORY
+    ## AUTHOR
+    ## COPYRIGHT
+    ## SEE ALSO
+
+## DESCRIPTION
+
+The ronn(1) command converts text in a simple markup to Unix manual pages. The
+syntax includes all Markdown formatting features, plus conventions for
+expressing the structure and various notations present in standard Unix
+manpages.
+
+Not all roff(7) typesetting features can be expressed using ronn syntax.
+
+## MANPAGE TITLE
+
+Manpages have a <name>, <section>, and a one-line <description>. Files must
+start with a level one heading defining these attributes:
+
+    ls(1) -- list directory contents
+    ================================
+
+Indicates that the manpage is named `ls` in manual section `1` ("user
+commands").
+
+## SECTION HEADINGS
+
+Man section headings are expressed with markdown level two headings. There
+are two syntaxes for level two headings.
+
+Hash prefix syntax:
+
+    ## HEADING TEXT
+
+Dash underline syntax:
+
+    HEADING TEXT
+    ------------
+
+Section headings should be all uppercase and may not contain inline markup.
+
+## INLINE MARKUP
+
+Manpages have a limited set of text formatting capabilities. There's basically
+<b>boldface</b> and <i>italics</i> (often displayed using <u>underline</u>).
+Ronn uses the following bits of markdown(7) to accomplish this:
+
+  * <code>\`backticks\`</code> (markdown compatible):
+    Code, flags, commands, and noun-like things; typically displayed in in
+    <b>boldface</b>. All text included within `backticks` is displayed
+    literally; other inline markup is not processed. HTML output:
+    `<code>`.
+
+  * `**double-stars**` (markdown compatible):
+    Also displayed in boldface. Unlike backticks, inline markup is processed.
+    HTML output: `<strong>`.
+
+  * `<anglequotes>` (non-compatible markdown extension):
+    User-specified arguments, variables, or user input. Typically displayed with
+    <u>underline</u> in roff output. HTML output: `<var/>`.
+
+  * `_`_underbars_`_` (markdown compatible):
+    Emphasis. May be used for literal option values. Typically displayed with
+    <u>underline</u> in roff output. HTML output: `<em>`.
+
+Here is grep(1)'s DESCRIPTION section represented in `ronn`:
+
+    `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.
+
+## DEFINITION LISTS
+
+The definition list syntax is compatible with markdown's unordered list syntax
+but requires that the first line of each list item be terminated with a colon
+"`:`" character. The contents of the first line 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 BSD test(1)'s *DESCRIPTION* section:
+
+     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.
+
+## LINKS
+
+All markdown(7) linking features are supported.
+
+Markdown reference-style links can be used to link to specific sections by name:
+
+    ## SECTION 1
+
+    See the following section.
+
+    ## SECTION 2
+
+    See [SECTION 1][] or [to put it another way][SECTION 1].
+
+The anchor name would be `#SECTION-1` and `#SECTION-2`. All non-word characters
+are removed and spaces are replaced by dashes.
+
+## SEE ALSO
+
+ronn(1), markdown(7), roff(7)

data/man/ronn.1

@@ -0,0 +1,227 @@
+.\" generated with Ronn-NG/v0.10.1
+.\" http://github.com/apjanke/ronn-ng/tree/0.10.1.pre1
+.TH "RONN" "1" "January 2020" "Ronn-NG 0.10.1.pre1" "Ronn Manual"
+.SH "NAME"
+\fBronn\fR \- convert markdown files to manpages
+.SH "SYNOPSIS"
+\fBronn\fR [\fIformat\fR\|\.\|\.\|\.] \fIfile\fR\|\.\|\.\|\.
+.br
+\fBronn\fR \fB\-m\fR|\fB\-\-man\fR \fIfile\fR\|\.\|\.\|\.
+.br
+\fBronn\fR \fB\-S\fR|\fB\-\-server\fR \fIfile\fR\|\.\|\.\|\.
+.br
+\fBronn\fR \fB\-\-pipe\fR \fIfile\fR
+.br
+\fBronn\fR < \fIfile\fR
+.br
+\fBronn\fR \fB\-E\fR|\fB\-\-encoding\fR \fIencoding\fR \|\.\|\.\|\.
+.SH "DESCRIPTION"
+\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 \fIfile\fRs 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 \fIfile\fRs\.
+.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 \fIfile\fR as with man(1)\.
+.P
+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\. Use the \fB\-\-html\fR, \fB\-\-roff\fR, and/or \fB\-\-fragment\fR options to select the output format\.
+.SH "FILES"
+The \fBronn\fR command expects input to be valid ronn\-format(7) 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
+Source files must be in UTF\-8 encoding, or the encoding specified by the \fB\-E\fR/\fB\-\-encoding\fR option, regardless of the locale that \fBronn\fR is running under\.
+.P
+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"
+These options control whether output is written to file(s), standard output, or directly to a man pager\.
+.IP "\(bu" 4
+\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\.
+.IP "\(bu" 4
+\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
+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
+.IP "\(bu" 4
+\fB\-\-port\fR=\fIport\fR When used with \fB\-S\fR/\fB\-\-server\fR, runs the server at the specified port instead of the default port 1207\.
+.IP "\(bu" 4
+\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\.
+.IP "\(bu" 4
+\fB\-o\fR=\fIdirectory\fR, \fB\-\-output\-dir\fR=\fIdirectory\fR: Write generated files to the specified directory instead of the default location\.
+.IP "\(bu" 4
+\fB\-E\fR=\fIencoding\fR, \fB\-\-encoding\fR=<encoding: Specify the encoding that input files are in\. Default is UTF\-8, regardless of user's locale settings\. Input sent to STDIN is always treated as UTF\-8, regardless of whether \fB\-E\fR is passed\.
+.IP "" 0
+.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\.
+.TP
+\fB\-r\fR, \fB\-\-roff\fR
+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\.
+.TP
+\fB\-f\fR, \fB\-\-fragment\fR
+Generate output in HTML format but only the document fragment, not the header, title, or footer\.
+.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 \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\.
+.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\.
+.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\.
+.P
+HTML output can be customized through the use of CSS stylesheets:
+.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\.
+.TP
+\fB\-v\fR, \fB\-\-version\fR
+Show ronn version and exit\.
+.SH "LINK INDEXES"
+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 \fIid\fR from its \fIlocation\fR\. Blank lines are allowed; lines beginning with a \fB#\fR character are ignored:
+.IP "" 4
+.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
+.IP "" 0
+.P
+The \fIlocation\fR 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\fItext\fR\fB][\fR\fIid\fR\fB]\fR, where \fItext\fR is the link text and \fIid\fR is a reference name defined in the index\.
+.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 "Builtin 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 builtin style sources \fIhttp://github\.com/apjanke/ronn\-ng/tree/master/lib/ronn/template\fR for examples\.
+.SH "EXAMPLES"
+Build roff and HTML output files and view the roff manpage using man(1):
+.IP "" 4
+.nf
+$ 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 only the roff manpage for all \fB\.ronn\fR files in the current directory:
+.IP "" 4
+.nf
+$ ronn \-\-roff *\.ronn
+roff: mv\.1
+roff: ls\.1
+roff: cd\.1
+roff: sh\.1
+.fi
+.IP "" 0
+.P
+Build only the HTML manpage for a few files and apply the \fBdark\fR and \fBtoc\fR stylesheets:
+.IP "" 4
+.nf
+$ ronn \-\-html \-\-style=dark,toc mv\.1\.ronn ls\.1\.ronn
+html: mv\.1\.html
+html: ls\.1\.html
+.fi
+.IP "" 0
+.P
+Generate roff output on standard output and write to file:
+.IP "" 4
+.nf
+$ ronn <hello\.1\.ronn >hello\.1
+.fi
+.IP "" 0
+.P
+View a ronn file in the same way as man(1) without building a roff file:
+.IP "" 4
+.nf
+$ ronn \-\-man hello\.1\.ronn
+.fi
+.IP "" 0
+.P
+Serve HTML manpages at \fIhttp://localhost:1207/\fR for all \fB*\.ronn\fR files under a \fBman/\fR directory:
+.IP "" 4
+.nf
+$ ronn \-\-server man/*\.ronn
+$ open http://localhost:1207/
+.fi
+.IP "" 0
+.SH "ENVIRONMENT"
+.TP
+\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'\.
+.TP
+\fBPAGER\fR
+Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined\.
+.SH "COPYRIGHT"
+Ronn\-NG is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR and (C) 2018 Andrew Janke \fIhttps://apjanke\.net\fR
+.SH "SEE ALSO"
+groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn\-format(7)