ronn 0.4

data/man/ronn.5.ronn

@@ -0,0 +1,152 @@
+ronn(5) -- humane manual page authoring format
+==============================================
+
+## SYNOPSIS
+
+    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.
+
+## 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.
+
+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.
+
+## MANPAGE TITLE
+
+All man pages have a <name>, belong to a <section>, and have a
+single sentence <tagline> (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:
+
+    ronn(5) -- humane manual page authoring format
+    =============================================
+
+Here, we're saying that the man page documents a thing named
+`ronn` in manual section `5` (the "file formats" section; see
+manpages(5) for full section list) and that's quickly described
+as a "humane manual page authoring format".
+
+These bits of information are used to fill in the document
+header, to create the `NAME` section, and also to establish
+output filenames when processed with ronn(1).
+
+## 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:
+
+    ## HEADING TEXT
+
+Or, a dash underline syntax:
+
+    HEADING TEXT
+    ------------
+
+Section headings should be in all uppercase and may not contain
+other inline markup.
+
+Most manual pages include at least one of the `SYNOPSIS`,
+`DESCRIPTION`, and/or `OPTIONS` sections. Additional sections
+commonly included are `SYNTAX`, `ENVIRONMENT`, `HISTORY`, `RETURN
+VALUES`, `BUGS`, `SECURITY CONSIDERATIONS`, `STANDARDS` /
+`CONFORMING TO`, `AUTHOR`, and `COPYRIGHT`. Finally, most man
+pages end with a `SEE ALSO` section that references other manual
+pages and external documents.
+
+## INLINE MARKUP
+
+Man pages have a limited set of text formatting capabilities at
+their disposal. There's basically <b>boldface</b> and
+<i>italics</i> (often displayed using <u>underline</u>). Ronn uses
+the following bits of markdown(5) to accomplish this:
+
+  * <code>\`backticks\`</code>:
+    Code, flags, commands, and noun-like things; typically
+    displayed in in <b>boldface</b>. Note that all text included
+    within `backticks` is displayed literally; other inline markup
+    is not processed.
+  * `**double-stars**`:
+    Like `backticks` but inline markup is processed.
+  * `_`_underbars_`_`:
+    User-specified arguments, variables, or user input; typically
+    displayed with <u>underline</u>.
+  * `<angle-quotes>`:
+    Same as _underbars_. This is not compatible with Markdown.
+
+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
+
+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.
+
+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 "`:`". The first line (minus
+the colon) 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.
+
+The definition list syntax is intentionally backward compatible
+with markdown(5)'s list syntax. This allows `ronn` documents to be
+piped through normal markdown processors with minor degradation
+in output formatting.
+
+## SEE ALSO
+
+ronn(1), markdown(5), manpages(5)

data/man/ronn.7

@@ -0,0 +1,195 @@
+.\" generated with Ronn/v0.3
+.\" http://github.com/rtomayko/ronn/
+.
+.TH "RONN" "7" "March 2010" "Ryan Tomayko" "Ronn Manual"
+.
+.SH "NAME"
+\fBronn\fR \-\- the opposite of roff
+.
+.SH "DESCRIPTION"
+Ronn is a humane text format and toolchain for creating UNIX man
+pages, and things that appear as man pages from a distance. Use it
+to build and install standard UNIX roff man pages or to generate
+nicely formatted HTML manual pages for the web.
+.
+.P
+The Ronn file format is based on Markdown. In fact, Ronn files are a
+compatible subset of Markdown syntax but have a more rigid structure and
+extend Markdown in some ways to provide features commonly found in man
+pages (e.g., definition lists). The ronn(5) manual page defines the
+format in more detail.
+.
+.SH "DOCUMENTATION"
+The \fB.ronn\fR files located under the \fBman/\fR directory show off a wide
+range of ronn capabilities and are the source of Ronn's own documentation.
+The source files and generated HTML / roff output files are available
+at:
+.
+.IP "\(bu" 4
+\fIronn(1)\fR \-
+build markdown based manual pages at the command line.
+.
+.br
+\fIsource file\fR, \fIroff output\fR
+.
+.IP "\(bu" 4
+\fIronn(5)\fR \-
+humane manual page authoring format syntax reference.
+.
+.br
+\fIsource file\fR, \fIroff output\fR
+.
+.IP "\(bu" 4
+\fImarkdown(5)\fR \-
+humane text markup syntax (taken from \fIMarkdown Syntax\fR,
+John Gruber)
+.
+.br
+\fIsource file\fR, \fIroff output\fR
+.
+.IP "" 0
+.
+.SH "INSTALL"
+Install with Rubygems:
+.
+.IP "" 4
+.
+.nf
+$ [sudo] gem install ronn
+$ ronn \-\-help
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Or, clone the git repository:
+.
+.IP "" 4
+.
+.nf
+$ git clone git://github.com/rtomayko/ronn.git
+$ PATH=ronn/bin:$PATH
+$ ronn \-\-help
+.
+.fi
+.
+.IP "" 0
+.
+.SH "BASIC USAGE"
+To generate a roff man page from the included\fI\fBmarkdown.5.ronn\fR\fR file and open it with man(1):
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b man/markdown.5.ronn
+building: man/markdown.5
+$ man man/markdown.5
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To generate a standalone HTML version:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b \-\-html man/markdown.5.ronn
+building: man/markdown.5.html
+$ open man/markdown.5.html
+.
+.fi
+.
+.IP "" 0
+.
+.P
+To build roff and HTML versions of all ronn files:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-b \-\-roff \-\-html man/*.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.P
+If you just want to view a ronn file as if it were a man page without
+building intermediate files:
+.
+.IP "" 4
+.
+.nf
+$ ronn \-m man/markdown.5.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The \fIronn(1)\fR manual page
+includes comprehensive documentation on \fBronn\fR command line options.
+.
+.SH "ABOUT"
+Some people think UNIX manual pages are a poor and outdated style of
+documentation. I disagree:
+.
+.IP "\(bu" 4
+Man pages follow a well defined structure that's immediately
+familiar and provides a useful starting point for developers
+documenting new tools, libraries, and formats.
+.
+.IP "\(bu" 4
+Man pages get to the point. Because they're written in an inverted
+style, with a SYNOPSIS section followed by additional detail,
+prose and references to other sources of information, man pages
+provide the best of both cheat sheet and reference style
+documentation.
+.
+.IP "\(bu" 4
+Man pages have extremely \-\- unbelievably \-\- limited text
+formatting capabilities. You get a couple of headings, lists, bold,
+underline and no more. This is a feature.
+.
+.IP "\(bu" 4
+Although two levels of section hierarchy are technically
+supported, most man pages use only a single level. Unwieldy
+document hierarchies complicate otherwise good documentation.
+Feynman covered all of physics \-\- heavenly bodies through QED \-\-
+with only two levels of document hierarchy (\fIThe Feynman Lectures
+on Physics\fR, 1970).
+.
+.IP "\(bu" 4
+Man pages have a simple referencing syntax; e.g., sh(1), fork(2),
+markdown(5). HTML versions can use this to generate links between
+pages.
+.
+.IP "\(bu" 4
+The classical terminal man page display is typographically well
+thought out. Big bold section headings, justified monospace text,
+nicely indented paragraphs, intelligently aligned definition
+lists, and an informational header and footer.
+.
+.IP "" 0
+.
+.P
+Unfortunately, trying to figure out how to create a man page is a
+fairly tedious process. The roff/man macro languages are highly
+extensible, fractured between multiple dialects, and include a bunch
+of device specific stuff that's entirely irrelevant to modern
+publishing tools.
+.
+.P
+Ronn aims to address many of the issues with man page creation while
+preserving the things that makes man pages a great form of
+documentation.
+.
+.SH "COPYING"
+Ronn is Copyright (C) 2009 \fIRyan Tomayko\fR
+See the file COPYING for information of licensing and distribution.
+.
+.SH "SEE ALSO"
+\fIronn(1)\fR, \fIronn(5)\fR, \fImarkdown(5)\fR

data/man/ronn.7.ronn

@@ -0,0 +1,135 @@
+ronn -- the opposite of roff
+===========================
+
+## DESCRIPTION
+
+Ronn is a humane text format and toolchain for creating UNIX man
+pages, and things that appear as man pages from a distance. Use it
+to build and install standard UNIX roff man pages or to generate
+nicely formatted HTML manual pages for the web.
+
+The Ronn file format is based on Markdown. In fact, Ronn files are a
+compatible subset of Markdown syntax but have a more rigid structure and
+extend Markdown in some ways to provide features commonly found in man
+pages (e.g., definition lists). The ronn(5) manual page defines the
+format in more detail.
+
+## DOCUMENTATION
+
+The `.ronn` files located under the `man/` directory show off a wide
+range of ronn capabilities and are the source of Ronn's own documentation.
+The source files and generated HTML / roff output files are available
+at:
+
+  * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html) -
+    build markdown based manual pages at the command line.  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1)
+
+  * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5.html) -
+    humane manual page authoring format syntax reference.  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5)
+
+  * [markdown(5)](http://rtomayko.github.com/ronn/markdown.5.html) -
+    humane text markup syntax (taken from
+    [Markdown Syntax](http://daringfireball.net/projects/markdown/syntax),
+    John Gruber)  
+    [source file](http://github.com/rtomayko/ronn/blob/master/man/markdown.5.ronn),
+    [roff output](http://github.com/rtomayko/ronn/blob/master/man/markdown.5)
+
+## INSTALL
+
+Install with Rubygems:
+
+    $ [sudo] gem install ronn
+    $ ronn --help
+
+Or, clone the git repository:
+
+    $ git clone git://github.com/rtomayko/ronn.git
+    $ PATH=ronn/bin:$PATH
+    $ ronn --help
+
+## BASIC USAGE
+
+To generate a roff man page from the included
+[`markdown.5.ronn`](man/markdown.5.ronn) file and open it with man(1):
+
+    $ ronn -b man/markdown.5.ronn
+    building: man/markdown.5
+    $ man man/markdown.5
+
+To generate a standalone HTML version:
+
+    $ ronn -b --html man/markdown.5.ronn
+    building: man/markdown.5.html
+    $ open man/markdown.5.html
+
+To build roff and HTML versions of all ronn files:
+
+    $ ronn -b --roff --html man/*.ronn
+
+If you just want to view a ronn file as if it were a man page without
+building intermediate files:
+
+    $ ronn -m man/markdown.5.ronn
+
+The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html) manual page
+includes comprehensive documentation on `ronn` command line options.
+
+## ABOUT
+
+Some people think UNIX manual pages are a poor and outdated style of
+documentation. I disagree:
+
+- Man pages follow a well defined structure that's immediately
+  familiar and provides a useful starting point for developers
+  documenting new tools, libraries, and formats.
+
+- Man pages get to the point. Because they're written in an inverted
+  style, with a SYNOPSIS section followed by additional detail,
+  prose and references to other sources of information, man pages
+  provide the best of both cheat sheet and reference style
+  documentation.
+
+- Man pages have extremely -- unbelievably -- limited text
+  formatting capabilities. You get a couple of headings, lists, bold,
+  underline and no more. This is a feature.
+
+- Although two levels of section hierarchy are technically
+  supported, most man pages use only a single level. Unwieldy
+  document hierarchies complicate otherwise good documentation.
+  Feynman covered all of physics -- heavenly bodies through QED --
+  with only two levels of document hierarchy (_The Feynman Lectures
+  on Physics_, 1970).
+
+- Man pages have a simple referencing syntax; e.g., sh(1), fork(2),
+  markdown(5). HTML versions can use this to generate links between
+  pages.
+
+- The classical terminal man page display is typographically well
+  thought out. Big bold section headings, justified monospace text,
+  nicely indented paragraphs, intelligently aligned definition
+  lists, and an informational header and footer.
+
+Unfortunately, trying to figure out how to create a man page is a
+fairly tedious process. The roff/man macro languages are highly
+extensible, fractured between multiple dialects, and include a bunch
+of device specific stuff that's entirely irrelevant to modern
+publishing tools.
+
+Ronn aims to address many of the issues with man page creation while
+preserving the things that makes man pages a great form of
+documentation.
+
+## COPYING
+
+Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
+See the file COPYING for information of licensing and distribution.
+
+## SEE ALSO
+
+[ronn(1)](http://rtomayko.github.com/ronn/ronn.1.html),
+[ronn(5)](http://rtomayko.github.com/ronn/ronn.5.html),
+[markdown(5)](http://rtomayko.github.com/ronn/markdown.5.html)