ronn 0.5 → 0.6.0

data/man/ronn.5.ronn

@@ -1,152 +1,157 @@
-ronn(5) -- humane manual page authoring format
-==============================================
+ronn(5) -- markdown-based text format for authoring manpages
+============================================================
 
 ## SYNOPSIS
 
-    name(1) -- one sentence description
-    ===================================
+    name(1) -- short, single-sentence description
+    =============================================
+
+    ## SYNOPSIS
 
-    ## SECTION HEADING
+    `name` [<optional>...] <flags>
 
-    A normal paragraph. This can span multiple lines and is
-    terminated with two or more line endings -- just like
-    Markdown.
+    ## DESCRIPTION
 
-    ## INLINE MARKUP
+    A normal paragraph. This can span multiple lines and is terminated with two
+    or more line endings -- just like Markdown.
 
-    Inline markup is used for `code` and `user input` (displayed
-    in boldface), and also <variables> or _emphasis_.
+    Inline markup for `code`, `user input`, and **strong** are displayed
+    boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics or
+    underline.
 
-    Manual page references like sh(1), markdown(5), roff(7), etc.
-    are displayed in boldface and hyperlinked in HTML output.
+    Manual references like sh(1), markdown(7), roff(7), etc. are displayed in
+    boldface and hyperlinked in HTML output.
 
-    ## DEFINITION LISTS
+    Link to other sections like [STANDARDS][], [SEE ALSO][], or
+    [WITH A DIFFERENT LINK TEXT][#SEE-ALSO].
 
-    Definition lists are used to define options, arguments,
-    variables, and other type of terms:
+    Definition lists:
 
-      * `-a`, `--arg1`=[_OPTION_]:
+      * `-a`, `--argument`=[<value>]:
         One or more paragraphs describing the argument.
-      * `-b`, `--arg2`:
-        Any number of these may be specified and may
-        be nested.
+      * You can put whatever you *want* here, really:
+        Nesting and paragraph spacing are respected.
+
+    Markdown ordered and unordered lists too.
+
+    Frequently used sections:
+
+    ## OPTIONS
+    ## SYNTAX
+    ## ENVIRONMENT
+    ## RETURN VALUES
+    ## STANDARDS
+    ## SECURITY CONSIDERATIONS
+    ## BUGS
+    ## HISTORY
+    ## AUTHOR
+    ## COPYRIGHT
+    ## SEE ALSO
 
 ## 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.
+Ronn is a source format for authoring UNIX manpages. The syntax includes all
+Markdown formatting features, plus conventions for expressing the structure and
+various notations present in standard UNIX manpages.
 
-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.
+Ronn files can be converted to traditional roff-formatted manpages or to HTML
+using the ronn(1) command.
 
-## MANPAGE TITLE
+Not all roff(7) typesetting features can be expressed using ronn syntax.
 
-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:
+## MANPAGE TITLE
 
-    ronn(5) -- humane manual page authoring format
-    =============================================
+Manpages have a <name>, <section> number, and one-line <description>. Ronn files
+must start with a level one heading defining these attributes:
 
-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".
+    ls(1) -- list directory contents
+    ================================
 
-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).
+Indicates that the manpage is named `ls` in manual section `1` ("user
+commands").
 
 ## 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:
+Man section headings are expressed with markdown level two headings. There
+are two syntaxes for level two headings.
+
+Hash prefix syntax:
 
     ## HEADING TEXT
 
-Or, a dash underline syntax:
+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.
+Section headings should be all uppercase and may not contain inline markup.
 
 ## 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:
+Manpages have a limited set of text formatting capabilities. There's basically
+<b>boldface</b> and <i>italics</i> (often displayed using <u>underline</u>).
+Ronn uses the following bits of markdown(7) 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.
+    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>.
+    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
+    `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`
+    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.
+The definition list syntax is exactly the same as markdown's unordered list
+syntax but requires that the first line of each list item be terminated with a
+colon "`:`" character. The contents of the first line (without 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:
+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.
+       * `-b` <file>:
+         True if <file> exists and is a block special file.
 
-       * `-c` _file_:
+       * `-c` <file>:
          True if _file_ exists and is a character special file.
 
-       * `-d` _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.
+The definition list syntax is intentionally backward compatible with
+markdown(7)'s list syntax. This allows `ronn` documents to be piped through
+normal markdown processors with minor degradation in output formatting.
+
+## LINKS
+
+Ronn supports all markdown(7) linking features. Additionally, section headings
+can be linked using reference-style links:
+
+    ## SECTION 1
+
+    See the following section.
+
+    ## SECTION 2
+
+    See [SECTION 1][] or [to put it another way][SECTION 1].
+
+The anchor name would be `#SECTION-1` and `#SECTION-2`. All non-word characters
+are removed and spaces are replaced by dashes.
 
 ## SEE ALSO
 
-ronn(1), markdown(5), manpages(5)
+ronn(1), markdown(7), roff(7)

data/man/ronn.7

@@ -1,51 +1,31 @@
-.\" generated with Ronn/v0.4.2
+.\" generated with Ronn/v0.6.0
 .\" http://github.com/rtomayko/ronn/
 .
-.TH "RONN" "7" "March 2010" "Ryan Tomayko" "Ronn Manual"
+.TH "RONN" "7" "June 2010" "0.6.0" "Ronn 0.6.0"
 .
 .SH "NAME"
-\fBronn\fR \-\- the opposite of roff
+\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.
+Ronn is a text format and toolchain for creating UNIX manpages\. It converts markdown to standard UNIX roff manpages and formatted HTML manuals 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.
+The source format includes all of Markdown but has a more rigid structure and includes extensions that provide features commonly found in manpages (definition lists, link notation, etc\.)\. The ronn(5) manual page defines the format in 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:
+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.
+ronn(1) \fIhttp://rtomayko\.github\.com/ronn/ronn\.1\fR \- convert markdown files to manpages\.
 .
 .br
-\fIsource file\fR, \fIroff output\fR
+source file \fIhttp://github\.com/rtomayko/ronn/blob/master/man/ronn\.1\.ronn\fR, roff output \fIhttp://github\.com/rtomayko/ronn/blob/master/man/ronn\.1\fR
 .
 .IP "\(bu" 4
-\fIronn(5)\fR \-
-humane manual page authoring format syntax reference.
+ronn(5) \fIhttp://rtomayko\.github\.com/ronn/ronn\.5\fR \- markdown\-based text format for authoring manpages
 .
 .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
+source file \fIhttp://github\.com/rtomayko/ronn/blob/master/man/ronn\.5\.ronn\fR, roff output \fIhttp://github\.com/rtomayko/ronn/blob/master/man/ronn\.5\fR
 .
 .IP "" 0
 .
@@ -70,7 +50,7 @@ Or, clone the git repository:
 .
 .nf
 
-$ git clone git://github.com/rtomayko/ronn.git
+$ git clone git://github\.com/rtomayko/ronn\.git
 $ PATH=ronn/bin:$PATH
 $ ronn \-\-help
 .
@@ -79,124 +59,110 @@ $ ronn \-\-help
 .IP "" 0
 .
 .SH "BASIC USAGE"
-To generate a roff man page from the included \fBmarkdown.5.ronn\fR file and
-open it with man(1):
+Build roff and HTML output files for one or more input files:
 .
 .IP "" 4
 .
 .nf
 
-$ ronn \-b man/markdown.5.ronn
-building: man/markdown.5
-$ man man/markdown.5
+$ ronn man/ronn\.5\.ronn
+roff: man/ronn\.5
+html: man/ronn\.5\.html
 .
 .fi
 .
 .IP "" 0
 .
 .P
-To generate a standalone HTML version:
+View a roff manpage with man(1):
 .
 .IP "" 4
 .
 .nf
 
-$ ronn \-b \-\-html man/markdown.5.ronn
-building: man/markdown.5.html
-$ open man/markdown.5.html
+$ man man/ronn\.5
 .
 .fi
 .
 .IP "" 0
 .
 .P
-To build roff and HTML versions of all ronn files:
+Generate only a standalone HTML version of one or more files:
 .
 .IP "" 4
 .
 .nf
 
-$ ronn \-b \-\-roff \-\-html man/*.ronn
+$ ronn \-\-html man/markdown\.5\.ronn
+html: man/markdown\.5\.html
 .
 .fi
 .
 .IP "" 0
 .
 .P
-If you just want to view a ronn file as if it were a man page without
-building intermediate files:
+Build roff versions of all ronn files in a directory:
 .
 .IP "" 4
 .
 .nf
 
-$ ronn \-m man/markdown.5.ronn
+$ ronn \-\-roff man/*\.ronn
 .
 .fi
 .
 .IP "" 0
 .
 .P
-The \fIronn(1)\fR manual page
-includes comprehensive documentation on \fBronn\fR command line options.
+View a ronn file as if it were a manpage without building intermediate files:
+.
+.IP "" 4
+.
+.nf
+
+$ ronn \-\-man man/markdown\.5\.ronn
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The ronn(1) \fIhttp://rtomayko\.github\.com/ronn/ronn\.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:
+Some people say 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.
+Man pages follow a well defined structure that\'s immediately familiar\. This provides developers with a useful starting point when 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.
+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.
+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).
+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.
+Man pages have a simple referencing syntax; e\.g\., sh(1), fork(2), markdown(7)\. 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.
+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.
+Unfortunately, figuring out how to create a manpage 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 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.
+Ronn aims to address many of the issues with manpage creation while preserving the things that makes manpages 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.
+Ronn is Copyright (C) 2009 Ryan Tomayko \fIhttp://tomayko\.com/about\fR
+.
+.br
+ See the file COPYING for information of licensing and distribution\.
 .
 .SH "SEE ALSO"
-\fIronn(1)\fR, \fIronn(5)\fR, \fImarkdown(5)\fR
+ronn(1) \fIhttp://rtomayko\.github\.com/ronn/ronn\.1\fR, ronn(5) \fIhttp://rtomayko\.github\.com/ronn/ronn\.5\fR, markdown(5)