ronn 0.4

data/man/ronn.1

@@ -0,0 +1,220 @@
+.\" generated with Ronn/v0.3
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "RONN" "1" "March 2010" "Ryan Tomayko" "Ronn Manual"
+.
+.SH "NAME"
+\fBronn\fR \-\- build markdown\-based man pages
+.
+.SH "SYNOPSIS"
+\fBronn\fR [ \fIOPTIONS\fR ] \fIFILE\fR ...
+.
+.br
+\fBronn\fR \-\-build \fIFILE\fR ...
+.
+.br
+\fBronn\fR \-\-install \fIFILE\fR ...
+.
+.br
+\fBronn\fR \-\-man \fIFILE\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.
+.
+.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.
+.
+.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
+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).
+.
+.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.
+.
+.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:
+.
+.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'.
+.
+.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.
+.
+.IP
+If \fBMANHOME\fR is not defined, \fBronn\fR installs man pages to \fI/usr/local/man\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.
+.
+.P
+These options control the format used in generated output:
+.
+.TP
+\fB\-r\fR, \fB\-\-roff\fR
+Generate roff output. This is the default behavior when no other
+format argument is provided.
+.
+.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
+All document attributes displayed in the header and footer areas of
+generated content can be specified with these options:
+.
+.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.
+.
+.SH "EXAMPLES"
+Generate \fBroff(7)\fR output on stdout:
+.
+.IP "" 4
+.
+.nf
+$ ronn < hello.1.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Build a roff file based on the input filename:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b hello.1.ronn
+building: hello.1
+$ man hello.1
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Build and open a standalone HTML file based on the input filename:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b \-\-html test.1.ronn
+$ open test.1.html
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Build roff and HTML versions of all \fB.ronn\fR files in the current
+directory:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b \-\-roff \-\-html *.ronn
+building: hello.1
+building: hello.1.html
+building: world.1
+building: world.1.html
+.
+.fi
+.
+.IP "" 0
+.
+.P
+View a ronn file in the same way as man(1) without building a roff file:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-m hello.1.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Install the roff man page for a ronn file:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-i hello.1.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.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.
+.
+.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 "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.
+.
+.SH "COPYRIGHT"
+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)

data/man/ronn.1.ronn

@@ -0,0 +1,158 @@
+ronn(1) -- build markdown-based man pages
+========================================
+
+## SYNOPSIS
+
+`ronn` [ <OPTIONS> ] <FILE> ...  
+`ronn` --build <FILE> ...  
+`ronn` --install <FILE> ...  
+`ronn` --man <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.
+
+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.
+
+## 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).
+
+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.
+
+## 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_.
+
+  * `-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
+    through groff(1) and the paging program specified by the `MANPAGER`
+    environment variable.
+
+These options control the format used in generated output:
+
+  * `-r`, `--roff`:
+    Generate roff output. This is the default behavior when no other
+    format argument is provided.
+
+  * `-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.
+
+All document attributes displayed in the header and footer areas of
+generated content can be specified with these options:
+
+  * `--manual`=<MANUAL>:
+    The name of the manual this man page belongs to; <MANUAL> is
+    prominently displayed top-center in the header area.
+
+  * `--organization`=<NAME>:
+    The name of the group, organization, or individual responsible for
+    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.
+
+## EXAMPLES
+
+Generate `roff(7)` output on stdout:
+
+    $ ronn < hello.1.ronn
+
+Build a roff file based on the input filename:
+
+    $ ronn -b hello.1.ronn
+    building: hello.1
+    $ man hello.1
+
+Build and open a standalone HTML file based on the input filename:
+
+    $ ronn -b --html test.1.ronn
+    $ open test.1.html
+
+Build roff and HTML versions of all `.ronn` files in the current
+directory:
+
+    $ ronn -b --roff --html *.ronn
+    building: hello.1
+    building: hello.1.html
+    building: world.1
+    building: world.1.html
+
+View a ronn file in the same way as man(1) without building a roff file:
+
+    $ ronn -m hello.1.ronn
+
+Install the roff man page for a ronn file:
+
+    $ 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`.
+
+  * `MANPAGER`:
+    The paging program used for man pages. This is typically set to
+    something like 'less -is'.
+
+  * `PAGER`:
+    Used instead of `MANPAGER` when `MANPAGER` is not defined.
+
+## 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.
+
+## COPYRIGHT
+
+Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+
+## SEE ALSO
+
+ronn(5), markdown(5), manpages(5), man(1), roff(7), groff(1)

data/man/ronn.5

@@ -0,0 +1,190 @@
+.\" generated with Ronn/v0.3
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "RONN" "5" "March 2010" "Ryan Tomayko" "Ronn Manual"
+.
+.SH "NAME"
+\fBronn\fR \-\- humane manual page authoring format
+.
+.SH "SYNOPSIS"
+.
+.nf
+name(1) \-\- one sentence description
+===================================
+## SECTION HEADING
+A normal paragraph. This can span multiple lines and is
+terminated with two or more line endings \-\- just like
+Markdown.
+## INLINE MARKUP
+Inline markup is used for `code` and `user input` (displayed
+in boldface), and also <variables> or _emphasis_.
+Manual page references like sh(1), markdown(5), roff(7), etc.
+are displayed in boldface and hyperlinked in HTML output.
+## DEFINITION LISTS
+Definition lists are used to define options, arguments,
+variables, and other type of terms:
+  * `\-a`, `\-\-arg1`=[_OPTION_]:
+    One or more paragraphs describing the argument.
+  * `\-b`, `\-\-arg2`:
+    Any number of these may be specified and may
+    be nested.
+.
+.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.
+.
+.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.
+.
+.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:
+.
+.IP "" 4
+.
+.nf
+ronn(5) \-\- humane manual page authoring format
+=============================================
+.
+.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).
+.
+.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:
+.
+.IP "" 4
+.
+.nf
+## HEADING TEXT
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Or, a dash underline syntax:
+.
+.IP "" 4
+.
+.nf
+HEADING TEXT
+\-\-\-\-\-\-\-\-\-\-\-\-
+.
+.fi
+.
+.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.
+.
+.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:
+.
+.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.
+.
+.TP
+\fB**double\-stars**\fR
+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.
+.
+.TP
+\fB<angle\-quotes>\fR
+Same as \fIunderbars\fR. This is not compatible with Markdown.
+.
+.P
+Here is grep(1)'s DESCRIPTION section represented in \fBronn\fR:
+.
+.IP "" 4
+.
+.nf
+`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.
+.
+.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.
+.
+.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.
+.
+.P
+An example definition list, taken from BSD test(1)'s\fBDESCRIPTION\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
+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.
+.
+.SH "SEE ALSO"
+ronn(1), markdown(5), manpages(5)