ron 0.3 → 0.4

data/man/ron.1

@@ -1,226 +0,0 @@
-.\" 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

@@ -1,158 +0,0 @@
-ron(1) -- build markdown-based man pages
-========================================
-
-## SYNOPSIS
-
-`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.
-
-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.
-
-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` 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 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, `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.
-
-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:
-
-    $ ron < hello.1.ron
-
-Build a roff file based on the input filename:
-
-    $ ron -b hello.1.ron
-    building: hello.1
-    $ man hello.1
-
-Build and open a standalone HTML file based on the input filename:
-
-    $ ron -b --html test.1.ron
-    $ open test.1.html
-
-Build roff and HTML versions of all `.ron` files in the current
-directory:
-
-    $ ron -b --roff --html *.ron
-    building: hello.1
-    building: hello.1.html
-    building: world.1
-    building: world.1.html
-
-View a ron file in the same way as man(1) without building a roff file:
-
-    $ ron -m hello.1.ron
-
-Install the roff man page for a ron file:
-
-    $ ron -i hello.1.ron
-
-## 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
-
-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>
-
-## SEE ALSO
-
-ron(5), markdown(5), manpages(5), man(1), roff(7), groff(1)

data/man/ron.5

@@ -1,210 +0,0 @@
-.\" 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)