ron 0.2 → 0.3

data/man/ron.1

@@ -0,0 +1,226 @@
+.\" generated with Ron/v0.2
+.\" http://github.com/rtomayko/ron/
+.
+.TH "RON" "1" "December 2009" "Ryan Tomayko" "Ron Manual"
+.
+.SH "NAME"
+\fBron\fR \-\- build markdown\-based man pages
+.
+.SH "SYNOPSIS"
+\fBron\fR [ \fIOPTIONS\fR ] \fIFILE\fR ...
+.
+.br
+\fBron\fR \-\-build \fIFILE\fR ...
+.
+.br
+\fBron\fR \-\-install \fIFILE\fR ...
+.
+.br
+\fBron\fR \-\-man \fIFILE\fR
+.
+.SH "DESCRIPTION"
+Ron 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 \fBron\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, \fBron\fR writes output in roff format.
+.
+.SH "FILES"
+The \fBron\fR command expects input to be formatted as ron(5) text.  Source
+files are typically named '\fINAME\fR.\fISECTION\fR.ron' (e.g., \fBhello.1.ron\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 \fBron \-b \-\-html \-\-roff hello.1.ron\fR generates a \fBhello.1\fR file with roff output and a \fBhello.1.html\fR file with HTML
+output.
+.
+.SH "OPTIONS"
+\fBron\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, \fBron\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
+
+$ ron < hello.1.ron 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Build a roff file based on the input filename:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-b hello.1.ron
+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
+
+$ ron \-b \-\-html test.1.ron
+$ open test.1.html 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Build roff and HTML versions of all \fB.ron\fR files in the current
+directory:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-b \-\-roff \-\-html *.ron
+building: hello.1
+building: hello.1.html
+building: world.1
+building: world.1.html 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+View a ron file in the same way as man(1) without building a roff file:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-m hello.1.ron 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Install the roff man page for a ron file:
+.
+.IP "" 4
+.
+.nf
+
+$ ron \-i hello.1.ron 
+.
+.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"
+Ron is written in Ruby and depends on nokogiri and rdiscount, native
+extension libraries that are non\-trivial to install on some systems. A
+more portable version of this program would be welcome.
+.
+.SH "COPYRIGHT"
+Ron is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+.
+.SH "SEE ALSO"
+ron(5), markdown(5), manpages(5), man(1), roff(7), groff(1)

data/man/ron.1.ron

@@ -3,97 +3,96 @@ ron(1) -- build markdown-based man pages
 
 ## SYNOPSIS
 
-`ron` [ <OPTIONS> ]  
+`ron` [ <OPTIONS> ] <FILE> ...  
 `ron` --build <FILE> ...  
 `ron` --install <FILE> ...  
 `ron` --man <FILE>
 
 ## DESCRIPTION
 
-`Ron` 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.
+Ron 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 `ron` 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, `ron`
-writes output in roff format.
+The `ron` 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, `ron` writes output in roff format.
 
 ## FILES
 
-The `ron` command expects input to be formatted as ron(5) text.
-Source files are typically named '<NAME>.<SECTION>.ron' (e.g.,
-`hello.1.ron`). The <NAME> and <SECTION> should match the name
-and section defined in <FILE>'s heading.
+The `ron` command expects input to be formatted as ron(5) text.  Source
+files are typically named '<NAME>.<SECTION>.ron' (e.g., `hello.1.ron`).
+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).
+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 `ron -b --html --roff hello.1.ron` would
-generate a `hello.1` file with roff output and a `hello.1.html` file
-with HTML output.
+For example, the command `ron -b --html --roff hello.1.ron` generates a
+`hello.1` file with roff output and a `hello.1.html` file with HTML
+output.
 
 ## OPTIONS
 
-`Ron`'s default mode of operation is to read a single document from
-standard input and to write the generated output to standard output.
-The following arguments change this behavior:
+`ron`'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'.
+    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.
+    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, `ron` 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.
+    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.
+    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.
+    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:
+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.
+    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.
+    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
 
@@ -121,8 +120,7 @@ directory:
     building: world.1
     building: world.1.html
 
-View a ron file in the same way as man(1) without building a roff
-file:
+View a ron file in the same way as man(1) without building a roff file:
 
     $ ron -m hello.1.ron
 
@@ -133,26 +131,27 @@ Install the roff man page for a ron file:
 ## ENVIRONMENT
 
   * `MANHOME`:
-    Location where roff formatted man pages should be installed.
-    Relevant only when the `--installed` argument is provided.
-    <PATH> is to the base of a man file hierarchy. e.g.,
-    `/usr/local/share/man`, `/home/rtomayko/man`.
+    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'.
+    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
 
-Ron is written in Ruby. C and/or standalone Perl implementations
-would be preferable for ease of packaging and distribution.
+Ron is written in Ruby and depends on nokogiri and rdiscount, native
+extension libraries that are non-trivial to install on some systems. A
+more portable version of this program would be welcome.
 
 ## COPYRIGHT
 
-`ron` is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
+Ron is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
 
 ## SEE ALSO
 

data/man/ron.5

@@ -0,0 +1,210 @@
+.\" generated with Ron/v0.2
+.\" http://github.com/rtomayko/ron/
+.
+.TH "RON" "5" "December 2009" "Ryan Tomayko" "Ron Manual"
+.
+.SH "NAME"
+\fBron\fR \-\- humane manual page authoring format
+.
+.SH "SYNOPSIS"
+A basic manual page in Ron:
+.
+.IP "" 4
+.
+.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
+.
+.IP "" 0
+.
+.SH "DESCRIPTION"
+Ron 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). Ron files are piped through ron(1)
+to build and install traditional roff(7) man pages or to generate
+hyperlinked HTML documentation.
+.
+.P
+All ron 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 ron.
+.
+.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). Ron
+files must begin with a first\-level heading that includes all of
+this information. For example, this very man page begins:
+.
+.IP "" 4
+.
+.nf
+
+ron(5) \-\- humane manual page authoring format
+============================================= 
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Here, we're saying that the man page documents a thing named\fBron\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 ron(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). Ron 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 \fBron\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 \fBron\fR documents to be
+piped through normal markdown processors with minor degradation
+in output formatting.
+.
+.SH "SEE ALSO"
+ron(1), markdown(5), manpages(5)