ronn
- convert markdown files to manpages
ronn
[format...] file...
ronn
-m
|--man
file...
ronn
-S
|--server
file...
ronn
--pipe
file
ronn
< file
ronn
-E
|--encoding
encoding ...
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.
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.
Source files must be in UTF-8 encoding, or the encoding specified by the
-E
/--encoding
option, regardless of the locale that ronn
is running under.
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.
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.
--port
=port
When used with -S
/--server
, runs the server at the specified port instead
of the default port 1207.
--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.
-o
=directory, --output-dir
=directory:
Write generated files to the specified directory instead of the default
location.
-E
=encoding, --encoding
=<encoding:
Specify the encoding that input files are in. Default is UTF-8, regardless
of user's locale settings. Input sent to STDIN is always treated as UTF-8,
regardless of whether -E
is passed.
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
-5
, --html
-f
, --fragment
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
--organization
=name
--date
=date
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]...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
-W
-w
argument.-v
, --version
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 https://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.
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.
These styles are included with the distribution:
man
--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
<style>
tag includes a
media=print
attribute.toc
display:none
style
rule; the toc
module turns it on and applies basic TOC styles.dark
80c
Writing custom stylesheets is straight-forward. The following core selectors allow targeting all generated elements:
.mp
body#manpage
.mp
element)..man-decor
.man-head
, .man-foot
.man-title
<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 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/
RONN_MANUAL
--manual
option takes precedence over this value.RONN_ORGANIZATION
--organization
option takes
precedence over this value.RONN_DATE
YYYY-MM-DD
format. Displayed in the
bottom-center footer area. The --date
option takes precedence over this
value.RONN_STYLE
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
PAGER
MANPAGER
when MANPAGER
is not defined.See LICENSE.txt
groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7), ronn-format(7)