ron 0.3 → 0.4

data/man/ron.5.ron

@@ -1,154 +0,0 @@
-ron(5) -- humane manual page authoring format
-=============================================
-
-## SYNOPSIS
-
-A basic manual page in Ron:
-
-    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
-
-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.
-
-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.
-
-## MANPAGE TITLE
-
-All man pages have a <name>, belong to a <section>, and have a
-single sentence <tagline> (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:
-
-    ron(5) -- humane manual page authoring format
-    =============================================
-
-Here, we're saying that the man page documents a thing named
-`ron` 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 ron(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>). Ron 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 `ron`:
-
-    `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 `ron` documents to be
-piped through normal markdown processors with minor degradation
-in output formatting.
-
-## SEE ALSO
-
-ron(1), markdown(5), manpages(5)

data/man/ron.7

@@ -1,201 +0,0 @@
-.\" generated with Ron/v0.2
-.\" http://github.com/rtomayko/ron/
-.
-.TH "RON" "7" "December 2009" "Ryan Tomayko" "Ron Manual"
-.
-.SH "NAME"
-\fBron\fR \-\- the opposite of roff
-.
-.SH "DESCRIPTION"
-Ron 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 Ron file format is based on Markdown. In fact, Ron 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 ron(5) manual page defines the
-format in more detail.
-.
-.SH "DOCUMENTATION"
-The \fB.ron\fR files located under the \fBman/\fR directory show off a wide
-range of ron capabilities and are the source of Ron's own documentation.
-The source files and generated HTML / roff output files are available
-at:
-.
-.IP "\(bu" 4
-\fIron(1)\fR \-
-build markdown based manual pages at the command line.
-.
-.br
-\fIsource file\fR, \fIroff output\fR
-.
-.IP "\(bu" 4
-\fIron(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 ron
-$ ron \-\-help 
-.
-.fi
-.
-.IP "" 0
-.
-.P
-Or, clone the git repository:
-.
-.IP "" 4
-.
-.nf
-
-$ git clone git://github.com/rtomayko/ron.git
-$ PATH=ron/bin:$PATH
-$ ron \-\-help 
-.
-.fi
-.
-.IP "" 0
-.
-.SH "BASIC USAGE"
-To generate a roff man page from the included\fI\fBmarkdown.5.ron\fR\fR file and open it with man(1):
-.
-.IP "" 4
-.
-.nf
-
-$ ron \-b man/markdown.5.ron
-building: man/markdown.5
-$ man man/markdown.5 
-.
-.fi
-.
-.IP "" 0
-.
-.P
-To generate a standalone HTML version:
-.
-.IP "" 4
-.
-.nf
-
-$ ron \-b \-\-html man/markdown.5.ron
-building: man/markdown.5.html
-$ open man/markdown.5.html 
-.
-.fi
-.
-.IP "" 0
-.
-.P
-To build roff and HTML versions of all ron files:
-.
-.IP "" 4
-.
-.nf
-
-$ ron \-b \-\-roff \-\-html man/*.ron 
-.
-.fi
-.
-.IP "" 0
-.
-.P
-If you just want to view a ron file as if it were a man page without
-building intermediate files:
-.
-.IP "" 4
-.
-.nf
-
-$ ron \-m man/markdown.5.ron 
-.
-.fi
-.
-.IP "" 0
-.
-.P
-The \fIron(1)\fR manual page
-includes comprehensive documentation on \fBron\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
-Ron 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"
-Ron is Copyright (C) 2009 \fIRyan Tomayko\fR
-See the file COPYING for information of licensing and distribution.
-.
-.SH "SEE ALSO"
-ron(1), ron(5), markdown(5)

data/man/ron.7.ron

@@ -1,133 +0,0 @@
-ron -- the opposite of roff
-===========================
-
-## DESCRIPTION
-
-Ron 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 Ron file format is based on Markdown. In fact, Ron 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 ron(5) manual page defines the
-format in more detail.
-
-## DOCUMENTATION
-
-The `.ron` files located under the `man/` directory show off a wide
-range of ron capabilities and are the source of Ron's own documentation.
-The source files and generated HTML / roff output files are available
-at:
-
-  * [ron(1)](http://rtomayko.github.com/ron/ron.1.html) -
-    build markdown based manual pages at the command line.  
-    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.1.ron),
-    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.1)
-
-  * [ron(5)](http://rtomayko.github.com/ron/ron.5.html) -
-    humane manual page authoring format syntax reference.  
-    [source file](http://github.com/rtomayko/ron/blob/master/man/ron.5.ron),
-    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
-
-  * [markdown(5)](http://rtomayko.github.com/ron/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/ron/blob/master/man/ron.5.ron),
-    [roff output](http://github.com/rtomayko/ron/blob/master/man/ron.5)
-
-## INSTALL
-
-Install with Rubygems:
-
-    $ [sudo] gem install ron
-    $ ron --help
-
-Or, clone the git repository:
-
-    $ git clone git://github.com/rtomayko/ron.git
-    $ PATH=ron/bin:$PATH
-    $ ron --help
-
-## BASIC USAGE
-
-To generate a roff man page from the included
-[`markdown.5.ron`](man/markdown.5.ron) file and open it with man(1):
-
-    $ ron -b man/markdown.5.ron
-    building: man/markdown.5
-    $ man man/markdown.5
-
-To generate a standalone HTML version:
-
-    $ ron -b --html man/markdown.5.ron
-    building: man/markdown.5.html
-    $ open man/markdown.5.html
-
-To build roff and HTML versions of all ron files:
-
-    $ ron -b --roff --html man/*.ron
-
-If you just want to view a ron file as if it were a man page without
-building intermediate files:
-
-    $ ron -m man/markdown.5.ron
-
-The [ron(1)](http://rtomayko.github.com/ron/ron.1.html) manual page
-includes comprehensive documentation on `ron` 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.
-
-Ron 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
-
-Ron is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)
-See the file COPYING for information of licensing and distribution.
-
-## SEE ALSO
-
-ron(1), ron(5), markdown(5)