ronn.5.ronn in ronn-0.6.0

- old
+ new
@@ -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
+    =============================================
 
-    ## SECTION HEADING
+    ## SYNOPSIS
 
-    A normal paragraph. This can span multiple lines and is
-    terminated with two or more line endings -- just like
-    Markdown.
+    `name` [<optional>...] <flags>
 
-    ## INLINE MARKUP
+    ## DESCRIPTION
 
-    Inline markup is used for `code` and `user input` (displayed
-    in boldface), and also <variables> or _emphasis_.
+    A normal paragraph. This can span multiple lines and is terminated with two
+    or more line endings -- just like Markdown.
 
-    Manual page references like sh(1), markdown(5), roff(7), etc.
-    are displayed in boldface and hyperlinked in HTML output.
+    Inline markup for `code`, `user input`, and **strong** are displayed
+    boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics or
+    underline.
 
-    ## DEFINITION LISTS
+    Manual references like sh(1), markdown(7), roff(7), etc. are displayed in
+    boldface and hyperlinked in HTML output.
 
-    Definition lists are used to define options, arguments,
-    variables, and other type of terms:
+    Link to other sections like [STANDARDS][], [SEE ALSO][], or
+    [WITH A DIFFERENT LINK TEXT][#SEE-ALSO].
 
-      * `-a`, `--arg1`=[_OPTION_]:
+    Definition lists:
+
+      * `-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.
 
+Not all roff(7) typesetting features can be expressed using ronn syntax.
+
 ## 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:
+Manpages have a <name>, <section> number, and one-line <description>. Ronn files
+must start with a level one heading defining these attributes:
 
-    ronn(5) -- humane manual page authoring format
-    =============================================
+    ls(1) -- list directory contents
+    ================================
 
-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".
+Indicates that the manpage is named `ls` in manual section `1` ("user
+commands").
 
-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:
+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.
+Section headings should be all uppercase and may not contain 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:
+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.
+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.
 
-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:
 
-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)