ronn(1)
NAME
ronn - convert markdown files to manpages
SYNOPSIS
ronn [format...] file... ronn -m|--man file... ronn -S|--server file... ronn --pipe file ronn < file
DESCRIPTION
Ronn converts textfiles to standard roff-formatted UNIX manpages or HTML. ronn-format(7) is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals. In its default mode, ronn converts one or more input files to HTML or roff output files. The --roff, --html, and --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. The --server and --man options change the output behavior from file generation to serving dynamically generated HTML manpages or viewing file as with man(1). 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 --html, --roff, and/or --fragment options to select the output format.
FILES
The 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 files 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 example, executing ronn example.1.ronn generates example.1 with roff output and example.1.html with HTML output.
OPTIONS
These options control whether output is written to file(s), standard
output, or directly to a man pager.
-m, --man
Dont 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 MANPAGER environment variable.
-S, --server
Dont 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. Theres also an index page at the root with
links to each file.
The server respects the --style and document attribute options
(--manual, --date, etc.). These same options can be varied at
request time by giving them as query parameters:
?manual=FOO&style=dark,toc
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.
--pipe Dont 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 --roff and --html are assumed.
-r, --roff
Generate roff output. This is the default behavior when no files
are given and ronn source text is read from standard input.
-5, --html
Generate output in HTML format.
-f, --fragment
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.)
--manual=manual
The name of the manual this man page belongs to; manual is
prominently displayed top-center in the header area.
--organization=name
The name of the group, organization, or individual responsible
for publishing the document; name is displayed in the
bottom-left footer area.
--date=date
The documents 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:
--style=module[,module]...
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.
Miscellaneous options:
-w, --warnings
Show troff warnings on standard error when performing roff
conversion. Warnings are most often the result of a bug in
ronns HTML to roff conversion logic.
-W Disable troff warnings. Warnings are disabled by default. This
option can be used to revert the effect of a previous -w
argument.
-v, --version
Show ronn version and exit.
LINK INDEXES
When generating HTML output, ronn hyperlinks manual references (like grep(1), ls(1), 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 references id from its location. Blank lines are allowed; lines beginning with a # character are ignored: # 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. Its possible to define references for things that arent manpages. All manuals in an individual directory share the references defined in that directorys index.txt file. Index references may be used explicitly in Markdown reference style links using the syntax: [text][id], where text is the link text and id is a reference name defined in the index.
STYLES
The --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.
Builtin Stylesheets
These styles are included with the distribution:
man 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 man.css file on the RONN_STYLE path.
print Basic print stylesheet. The generated <style> tag includes a
media=print attribute.
toc Enables the Table of Contents navigation. The TOC markup is
included in generated HTML by default but hidden with an inline
display:none style rule; the toc module turns it on and applies
basic TOC styles.
dark Light text on a dark background.
80c 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.
Custom Stylesheets
Writing custom stylesheets is straight-forward. The following core
selectors allow targeting all generated elements:
.mp The manual page container element. Present on full documents and
document fragments.
body#manpage
Signifies that the page was fully-generated by Ronn and contains
a single manual page (.mp element).
.man-decor
The three-item heading and footing elements both have this
class.
.man-head, .man-foot
The heading and footing, respectively.
.man-title
The main <h1> element. Hidden by default unless the manual has
no name or section attributes.
See the builtin style sources
http://github.com/rtomayko/ronn/tree/master/lib/ronn/template for
examples.
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 dark and toc stylesheets: $ 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 files under a man/ directory: $ ronn --server man/*.ronn $ open http://localhost:1207/
ENVIRONMENT
RONN_MANUAL
A default manual name to be displayed in the top-center header
area. The --manual option takes precedence over this value.
RONN_ORGANIZATION
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.
RONN_DATE
The default manual date in YYYY-MM-DD format. Displayed in the
bottom-center footer area. The --date option takes precedence
over this value.
RONN_STYLE
A 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.
MANPAGER
The paging program used for man pages. This is typically set to
something like less -is.
PAGER Used instead of MANPAGER when MANPAGER is not defined.
BUGS
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.
COPYRIGHT
Ronn is Copyright (C) 2009 Ryan Tomayko http://tomayko.com/about
SEE ALSO
ronn-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
