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
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
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
- 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 MANPAGER environment variable.
- -S, --server
- 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 ( --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
- 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
--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 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:
- --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 ronn´s
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 reference´s
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. It´s possible to define references for things
that aren´t manpages.
All manuals in an individual directory share the references defined in that
directory´s
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)