RONN-FORMAT(7)							    Ronn Manual 						    RONN-FORMAT(7)

NAME

       ronn-format - manual authoring format based on Markdown

SYNOPSIS

       name(1) -- short, single-sentence description
       =============================================

       ## SYNOPSIS

       `name` [<optional>...] <flags>

       ## DESCRIPTION

       A normal paragraph. This can span multiple lines and is terminated with two
       or more line endings -- just like Markdown.

       Inline markup for `code`, `user input`, and **strong** are displayed
       boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
       (HTML) or underline (roff).

       Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
       HTML output.

       Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
       TEXT][#SEE-ALSO].

       Definition lists:

	 * `-a`, `--argument`=[<value>]:
	   One or more paragraphs describing the argument.

	 * You can put whatever you *want* here, really:
	   Nesting and paragraph spacing are respected.

       Frequently used sections:

       ## OPTIONS
       ## SYNTAX
       ## ENVIRONMENT
       ## RETURN VALUES
       ## STANDARDS
       ## SECURITY CONSIDERATIONS
       ## BUGS
       ## HISTORY
       ## AUTHOR
       ## COPYRIGHT
       ## SEE ALSO

DESCRIPTION

       The  ronn(1) command converts text in a simple markup to UNIX manual pages. The syntax includes all Markdown formatting features, plus con-
       ventions for expressing the structure and various notations present in standard UNIX manpages.

       Not all roff(7) typesetting features can be expressed using ronn syntax.

MANPAGE TITLE

       Manpages have a name, section, and a one-line description. Files must start with a level one heading defining these attributes:

	   ls(1) -- list directory contents
	   ================================

       Indicates that the manpage is named ls in manual section 1 (

SECTION HEADINGS

       Man section headings are expressed with markdown level two headings. There are two syntaxes for level two headings.

       Hash prefix syntax:

	   ## HEADING TEXT

       Dash underline syntax:

	   HEADING TEXT
	   ------------

       Section headings should be all uppercase and may not contain inline markup.

INLINE MARKUP

       Manpages have a limited set of text formatting capabilities. There's basically boldface and italics (often displayed using underline). Ronn
       uses the following bits of markdown(7) to accomplish this:

       `backticks` (markdown compatible)
	      Code,  flags,  commands,	and  noun-like things; typically displayed in in boldface. All text included within backticks is displayed
	      literally; other inline markup is not processed. HTML output: <code>.

       **double-stars** (markdown compatible)
	      Also displayed in boldface. Unlike backticks, inline markup is processed. HTML output: <strong>.

       <anglequotes> (non-compatible markdown extension)
	      User-specified arguments, variables, or user input. Typically displayed with underline in roff output. HTML output: <var/>.

       _underbars_ (markdown compatible)
	      Emphasis. May be used for literal option values. Typically displayed with underline in roff output. HTML output: <em>.

       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

       The definition list syntax is compatible with markdown's unordered list syntax but requires that the first line of each list item be termi-
       nated with a colon

       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.

LINKS

       All markdown(7) linking features are supported.

       Markdown reference-style links can be used to link to specific sections by name:

	   ## 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(7), roff(7)

Ronn 0.7.0							     June 2010							    RONN-FORMAT(7)