1RONN(1) Ronn Manual RONN(1)
2
6 ronn - convert markdown files to manpages
7
9 ronn [format...] file...
10 ronn -m|--man file...
11 ronn -S|--server file...
12 ronn --pipe file
13 ronn < file
14
16 Ronn converts textfiles to standard roff-formatted UNIX manpages or
17 HTML. ronn-format(7) is based on markdown(7) but includes additional
18 rules and syntax geared toward authoring manuals.
19 In its default mode, ronn converts one or more input files to HTML or
21 roff output files. The --roff, --html, and --fragment options dictate
22 which output files are generated. Multiple format arguments may be
23 specified to generate multiple output files. Output files are named
24 after and written to the same directory as input files.
25 The --server and --man options change the output behavior from file
27 generation to serving dynamically generated HTML manpages or viewing
28 file as with man(1).
29 With no file arguments, ronn acts as simple filter. Ronn source text is
31 read from standard input and roff output is written to standard output.
32 Use the --html, --roff, and/or --fragment options to select the output
33 format.
34
36 The ronn command expects input to be valid ronn-format(7) text. Source
37 files are typically named name.section.ronn (e.g., example.1.ronn). The
38 name and section should match the name and section defined in the
39 file´s heading.
40 When building roff or HTML output files, destination filenames are
42 determined by taking the basename of the input file and adding the
43 appropriate file extension (or removing the file extension in the case
44 of roff output). For example, executing ronn example.1.ronn generates
45 example.1 with roff output and example.1.html with HTML output.
46
48 These options control whether output is written to file(s), standard
49 output, or directly to a man pager.
50 -m, --man
52 Don´t generate files, display files as if man(1) were invoked on
53 the roff output file. This simulates default man behavior by
54 piping the roff output through groff(1) and the paging program
55 specified by the MANPAGER environment variable.
56 -S, --server
58 Don´t generate files, start an HTTP server at http://local‐
59 host:1207/ and serve dynamically generated HTML for the set of
60 input files. A file named example.2.ronn is served as /exam‐
61 ple.2.html. There´s also an index page at the root with links to
62 each file.
63 The server respects the --style and document attribute options
65 (--manual, --date, etc.). These same options can be varied at
66 request time by giving them as query parameters: ?man‐
67 ual=FOO&style=dark,toc
68 NOTE: The builtin server is designed to assist in the process of
70 writing and styling manuals. It is in no way recommended as a
71 general purpose web server.
72 --pipe Don´t generate files, write generated output to standard output.
74 This is the default behavior when ronn source text is piped in
75 on standard input and no file arguments are provided.
76 Format options control the files ronn generates, or the output format
78 when the --pipe argument is specified. When no format options are
79 given, both --roff and --html are assumed.
80 -r, --roff
82 Generate roff output. This is the default behavior when no files
83 are given and ronn source text is read from standard input.
84 -5, --html
86 Generate output in HTML format.
87 -f, --fragment
89 Generate output in HTML format but only the document fragment,
90 not the header, title, or footer.
91 Document attributes displayed in the header and footer areas of gener‐
93 ated content are specified with these options. (These values may also
94 be set via the ENVIRONMENT.)
95 --manual=manual
97 The name of the manual this man page belongs to; manual is
98 prominently displayed top-center in the header area.
99 --organization=name
101 The name of the group, organization, or individual responsible
102 for publishing the document; name is displayed in the bot‐
103 tom-left footer area.
104 --date=date
106 The document´s published date; date must be formatted YYYY-MM-DD
107 and is displayed in the bottom-center footer area. The file
108 mtime is used when no date is given, or the current time when no
109 file is available.
110 HTML output can be customized through the use of CSS stylesheets:
112 --style=module[,module]...
114 The list of CSS stylesheets to apply to the document. Multiple
115 module arguments may be specified, but must be separated by com‐
116 mas or spaces.
117 When module is a simple word, search for files named module.css
119 in all directories listed in the RONN_STYLE environment vari‐
120 able, and then search internal styles.
121 When module includes a / character, use it as the full path to a
123 stylesheet file.
124 Internal styles are man (included by default), toc, and 80c. See
126 STYLES for descriptions of features added by each module.
127 Miscellaneous options:
129 -w, --warnings
131 Show troff warnings on standard error when performing roff con‐
132 version. Warnings are most often the result of a bug in ronn´s
133 HTML to roff conversion logic.
134 -W Disable troff warnings. Warnings are disabled by default. This
136 option can be used to revert the effect of a previous -w argu‐
137 ment.
138 -v, --version
140 Show ronn version and exit.
141
143 When generating HTML output, ronn hyperlinks manual references (like
144 grep(1), ls(1), markdown(7)) in source text based on reference name to
145 URL mappings defined in an index.txt file. Each line of the index file
146 describes a single reference link, with whitespace separating the ref‐
147 erence´s id from its location. Blank lines are allowed; lines beginning
148 with a # character are ignored:
149 # manuals included in this project:
153 whisky(1) whisky.1.ronn
154 tango(5) tango.5.ronn
155 # external manuals
157 grep(1) http://man.cx/grep(1)
158 ls(1) http://man.cx/ls(1)
159 # other URLs for use with markdown reference links
161 src http://github.com/
162 The location is an absolute or relative URL that usually points at an
166 HTML version of manpage. It´s possible to define references for things
167 that aren´t manpages.
168 All manuals in an individual directory share the references defined in
170 that directory´s index.txt file. Index references may be used explic‐
171 itly in Markdown reference style links using the syntax: [text][id],
172 where text is the link text and id is a reference name defined in the
173 index.
174
176 The --style option selects a list of CSS stylesheets to include in the
177 generated HTML. Styles are applied in the order defined, so each can
178 use the cascade to override previously defined styles.
179 Builtin Stylesheets
181 These styles are included with the distribution:
182 man Basic manpage styles: typography, definition lists, indentation.
184 This is always included regardless of --style argument. It is
185 however possible to replace the default man module with a custom
186 one by placing a man.css file on the RONN_STYLE path.
187 print Basic print stylesheet. The generated <style> tag includes a
189 media=print attribute.
190 toc Enables the Table of Contents navigation. The TOC markup is
192 included in generated HTML by default but hidden with an inline
193 display:none style rule; the toc module turns it on and applies
194 basic TOC styles.
195 dark Light text on a dark background.
197 80c Changes the display width to mimic the display of a classic 80
199 character terminal. The default display width causes lines to
200 wrap at a gratuitous 100 characters.
201 Custom Stylesheets
203 Writing custom stylesheets is straight-forward. The following core
204 selectors allow targeting all generated elements:
205 .mp The manual page container element. Present on full documents and
207 document fragments.
208 body#manpage
210 Signifies that the page was fully-generated by Ronn and contains
211 a single manual page (.mp element).
212 .man-decor
214 The three-item heading and footing elements both have this
215 class.
216 .man-head, .man-foot
218 The heading and footing, respectively.
219 .man-title
221 The main <h1> element. Hidden by default unless the manual has
222 no name or section attributes.
223 See the builtin style sources http://github.com/rtomayko/ronn/tree/mas‐
225 ter/lib/ronn/template for examples.
226
228 Build roff and HTML output files and view the roff manpage using
229 man(1):
230 $ ronn some-great-program.1.ronn
234 roff: some-great-program.1
235 html: some-great-program.1.html
236 $ man ./some-great-program.1
237 Build only the roff manpage for all .ronn files in the current direc‐
241 tory:
242 $ ronn --roff *.ronn
246 roff: mv.1
247 roff: ls.1
248 roff: cd.1
249 roff: sh.1
250 Build only the HTML manpage for a few files and apply the dark and toc
254 stylesheets:
255 $ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
259 html: mv.1.html
260 html: ls.1.html
261 Generate roff output on standard output and write to file:
265 $ ronn <hello.1.ronn >hello.1
269 View a ronn file in the same way as man(1) without building a roff
273 file:
274 $ ronn --man hello.1.ronn
278 Serve HTML manpages at http://localhost:1207/ for all *.ronn files
282 under a man/ directory:
283 $ ronn --server man/*.ronn
287 $ open http://localhost:1207/
288
292 RONN_MANUAL
293 A default manual name to be displayed in the top-center header
294 area. The --manual option takes precedence over this value.
295 RONN_ORGANIZATION
297 The default manual publishing group, organization, or individual
298 to be displayed in the bottom-left footer area. The --organiza‐
299 tion option takes precedence over this value.
300 RONN_DATE
302 The default manual date in YYYY-MM-DD format. Displayed in the
303 bottom-center footer area. The --date option takes precedence
304 over this value.
305 RONN_STYLE
307 A PATH-style list of directories to check for stylesheets given
308 to the --style option. Directories are separated by a :; blank
309 entries are ignored. Use . to include the current working direc‐
310 tory.
311 MANPAGER
313 The paging program used for man pages. This is typically set to
314 something like ´less -is´.
315 PAGER Used instead of MANPAGER when MANPAGER is not defined.
317
319 Ronn is written in Ruby and depends on hpricot and rdiscount, extension
320 libraries that are non-trivial to install on some systems. A more por‐
321 table version of this program would be welcome.
322
324 Ronn is Copyright (C) 2009 Ryan Tomayko http://tomayko.com/about
325
327 ronn-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
328Ronn 0.7.0 June 2010 RONN(1)