ronn - convert markdown files to manpages
ronn [format...] file...
ronn < file
In its default mode,
ronn converts one or more input files to HTML or roff
output files. The
--fragment options dictate which
output files are generated. Multiple format arguments may be specified to
generate multiple output files. Output files are named after and written to the
same directory as input files.
--man options change the output behavior from file
generation to serving dynamically generated HTML manpages or viewing file as
With no file arguments,
ronn acts as simple filter. Ronn source text is read
from standard input and roff output is written to standard output. Use the
--fragment options to select the output format.
ronn command expects input to be valid ronn-format(7) text. Source files
are typically named name.section.ronn (e.g.,
example.1.ronn). The name
and section should match the name and section defined in the file's heading.
When building roff or HTML output files, destination filenames are determined by
taking the basename of the input file and adding the appropriate file
extension (or removing the file extension in the case of roff output). For
ronn example.1.ronn generates
example.1 with roff output
example.1.html with HTML output.
These options control whether output is written to file(s), standard output, or directly to a man pager.
Don't generate files, display files as if man(1) were invoked on the roff
output file. This simulates default man behavior by piping the roff output
through groff(1) and the paging program specified by the
Don't generate files, start an HTTP server at http://localhost:1207/ and serve dynamically generated HTML for the set of input files. A file named example.2.ronn is served as /example.2.html. There's also an index page at the root with links to each file.
The server respects the
--style and document attribute options
--date, etc.). These same options can be varied at request
time by giving them as query parameters:
NOTE: The builtin server is designed to assist in the process of writing and styling manuals. It is in no way recommended as a general purpose web server.
Don't generate files, write generated output to standard output. This is the default behavior when ronn source text is piped in on standard input and no file arguments are provided.
Format options control the files
ronn generates, or the output format when the
--pipe argument is specified. When no format options are given, both
--html are assumed.
Generate roff output. This is the default behavior when no files are given and ronn source text is read from standard input.
Generate output in HTML format.
Generate output in HTML format but only the document fragment, not the header, title, or footer.
Document attributes displayed in the header and footer areas of generated content are specified with these options. (These values may also be set via the ENVIRONMENT.)
The name of the manual this man page belongs to; manual is prominently displayed top-center in the header area.
The name of the group, organization, or individual responsible for publishing the document; name is displayed in the bottom-left footer area.
The document's published date; date must be formatted
YYYY-MM-DD and is
displayed in the bottom-center footer area. The file mtime is used when no
date is given, or the current time when no file is available.
HTML output can be customized through the use of CSS stylesheets:
The list of CSS stylesheets to apply to the document. Multiple module arguments may be specified, but must be separated by commas or spaces.
When module is a simple word, search for files named module
.css in all
directories listed in the
RONN_STYLE environment variable,
and then search internal styles.
When module includes a / character, use it as the full path to a stylesheet file.
Internal styles are man (included by default), toc, and 80c. See STYLES for descriptions of features added by each module.
Show troff warnings on standard error when performing roff conversion. Warnings are most often the result of a bug in ronn's HTML to roff conversion logic.
Disable troff warnings. Warnings are disabled by default. This option can be
used to revert the effect of a previous
Show ronn version and exit.
When generating HTML output,
ronn hyperlinks manual references (like
markdown(7)) in source text based on reference name to URL
mappings defined in an
index.txt file. Each line of the index file describes a
single reference link, with whitespace separating the reference's id from its
location. Blank lines are allowed; lines beginning with a
# character are
# manuals included in this project: whisky(1) whisky.1.ronn tango(5) tango.5.ronn # external manuals grep(1) http://man.cx/grep(1) ls(1) http://man.cx/ls(1) # other URLs for use with markdown reference links src http://github.com/
The location is an absolute or relative URL that usually points at an HTML version of manpage. It's possible to define references for things that aren't manpages.
All manuals in an individual directory share the references defined in that
index.txt file. Index references may be used explicitly in
Markdown reference style links using the syntax:
text is the link text and id is a reference name defined in the index.
--style option selects a list of CSS stylesheets to include in the
generated HTML. Styles are applied in the order defined, so each can use the
cascade to override previously defined styles.
These styles are included with the distribution:
Basic manpage styles: typography, definition lists, indentation. This is
always included regardless of
--style argument. It is however possible to
replace the default
man module with a custom one by placing a
file on the
Basic print stylesheet. The generated
<style> tag includes a
Enables the Table of Contents navigation. The TOC markup is included in
generated HTML by default but hidden with an inline
toc module turns it on and applies basic TOC styles.
Light text on a dark background.
Changes the display width to mimic the display of a classic 80 character terminal. The default display width causes lines to wrap at a gratuitous 100 characters.
Writing custom stylesheets is straight-forward. The following core selectors allow targeting all generated elements:
The manual page container element. Present on full documents and document fragments.
Signifies that the page was fully-generated by Ronn and contains a single
manual page (
The three-item heading and footing elements both have this class.
The heading and footing, respectively.
<h1> element. Hidden by default unless the manual has no name
or section attributes.
See the builtin style sources for examples.
Build roff and HTML output files and view the roff manpage using man(1):
$ ronn some-great-program.1.ronn roff: some-great-program.1 html: some-great-program.1.html $ man ./some-great-program.1
Build only the roff manpage for all
.ronn files in the current directory:
$ ronn --roff *.ronn roff: mv.1 roff: ls.1 roff: cd.1 roff: sh.1
Build only the HTML manpage for a few files and apply the
$ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn html: mv.1.html html: ls.1.html
Generate roff output on standard output and write to file:
$ ronn <hello.1.ronn >hello.1
View a ronn file in the same way as man(1) without building a roff file:
$ ronn --man hello.1.ronn
Serve HTML manpages at http://localhost:1207/ for all
$ ronn --server man/*.ronn $ open http://localhost:1207/
A default manual name to be displayed in the top-center header area.
--manual option takes precedence over this value.
The default manual publishing group, organization, or individual to be
displayed in the bottom-left footer area. The
--organization option takes
precedence over this value.
The default manual date in
YYYY-MM-DD format. Displayed in the
bottom-center footer area. The
--date option takes precedence over this
PATH-style list of directories to check for stylesheets given to the
--style option. Directories are separated by a :; blank entries are
ignored. Use . to include the current working directory.
The paging program used for man pages. This is typically set to something like 'less -is'.
Used instead of
MANPAGER is not defined.
Ronn is written in Ruby and depends on hpricot and rdiscount, extension libraries that are non-trivial to install on some systems. A more portable version of this program would be welcome.
Ronn is Copyright (C) 2009 Ryan Tomayko http://tomayko.com/about