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 ronn -E|--encoding encoding ...
15
17 Ronn converts textfiles to standard roff-formatted Unix manpages or
18 HTML. ronn-format(7) is based on markdown(7) but includes additional
19 rules and syntax geared toward authoring manuals.
20 In its default mode, ronn converts one or more input files to HTML or
22 roff output files. The --roff, --html, and --fragment options dictate
23 which output files are generated. Multiple format arguments may be
24 specified to generate multiple output files. Output files are named af‐
25 ter and written to the same directory as input files.
26 The --server and --man options change the output behavior from file
28 generation to serving dynamically generated HTML manpages or viewing
29 file as with man(1).
30 With no file arguments, ronn acts as simple filter. Ronn source text is
32 read from standard input and roff output is written to standard output.
33 Use the --html, --roff, and/or --fragment options to select the output
34 format.
35
37 The ronn command expects input to be valid ronn-format(7) text. Source
38 files are typically named name.section.ronn (e.g., example.1.ronn). The
39 name and section should match the name and section defined in the
40 file´s heading.
41 Source files must be in UTF-8 encoding, or the encoding specified by
43 the -E/--encoding option, regardless of the locale that ronn is running
44 under.
45 When building roff or HTML output files, destination filenames are de‐
47 termined by taking the basename of the input file and adding the appro‐
48 priate file extension (or removing the file extension in the case of
49 roff output). For example, executing ronn example.1.ronn generates ex‐
50 ample.1 with roff output and example.1.html with HTML output.
51
53 These options control whether output is written to file(s), standard
54 output, or directly to a man pager.
55 ○ -m, --man: Don´t generate files, display files as if man(1) were
57 invoked on the roff output file. This simulates default man behav‐
58 ior by piping the roff output through groff(1) and the paging pro‐
59 gram specified by the MANPAGER environment variable.
60 ○ -S, --server: Don´t generate files, start an HTTP server at
62 http://localhost:1207/ and serve dynamically generated HTML for the
63 set of input files. A file named example.2.ronn is served as /exam‐
64 ple.2.html. There´s also an index page at the root with links to
65 each file.
66 The server respects the --style and document attribute options
68 (--manual, --date, etc.). These same options can be varied at re‐
69 quest time by giving them as query parameters: ?man‐
70 ual=FOO&style=dark,toc
71 NOTE: The builtin server is designed to assist in the process of
73 writing and styling manuals. It is in no way recommended as a gen‐
74 eral purpose web server.
75 ○ --port=port When used with -S/--server, runs the server at the
77 specified port instead of the default port 1207.
78 ○ --pipe: Don´t generate files, write generated output to standard
80 output. This is the default behavior when ronn source text is piped
81 in on standard input and no file arguments are provided.
82 ○ -o=directory, --output-dir=directory: Write generated files to the
84 specified directory instead of the default location.
85 ○ -E=encoding, --encoding=<encoding: Specify the encoding that input
87 files are in. Default is UTF-8, regardless of user´s locale set‐
88 tings. Input sent to STDIN is always treated as UTF-8, regardless
89 of whether -E is passed.
90 Format options control the files ronn generates, or the output format
94 when the --pipe argument is specified. When no format options are
95 given, both --roff and --html are assumed.
96 -r, --roff
98 Generate roff output. This is the default behavior when no files
99 are given and ronn source text is read from standard input.
100 -5, --html
102 Generate output in HTML format.
103 -f, --fragment
105 Generate output in HTML format but only the document fragment,
106 not the header, title, or footer.
107 Document attributes displayed in the header and footer areas of gener‐
109 ated content are specified with these options. (These values may also
110 be set via the ENVIRONMENT.)
111 --manual=manual
113 The name of the manual this man page belongs to; manual is
114 prominently displayed top-center in the header area.
115 --organization=name
117 The name of the group, organization, or individual responsible
118 for publishing the document; name is displayed in the bot‐
119 tom-left footer area.
120 --date=date
122 The document´s published date; date must be formatted YYYY-MM-DD
123 and is displayed in the bottom-center footer area. The file
124 mtime is used when no date is given, or the current time when no
125 file is available.
126 HTML output can be customized through the use of CSS stylesheets:
128 --style=module[,module]...
130 The list of CSS stylesheets to apply to the document. Multiple
131 module arguments may be specified, but must be separated by com‐
132 mas or spaces.
133 When module is a simple word, search for files named module.css
135 in all directories listed in the RONN_STYLE environment vari‐
136 able, and then search internal styles.
137 When module includes a / character, use it as the full path to a
139 stylesheet file.
140 Internal styles are man (included by default), toc, and 80c. See
142 STYLES for descriptions of features added by each module.
143 Miscellaneous options:
145 -w, --warnings
147 Show troff warnings on standard error when performing roff con‐
148 version. Warnings are most often the result of a bug in ronn´s
149 HTML to roff conversion logic.
150 -W Disable troff warnings. Warnings are disabled by default. This
152 option can be used to revert the effect of a previous -w argu‐
153 ment.
154 -v, --version
156 Show ronn version and exit.
157
159 When generating HTML output, ronn hyperlinks manual references (like
160 grep(1), ls(1), markdown(7)) in source text based on reference name to
161 URL mappings defined in an index.txt file. Each line of the index file
162 describes a single reference link, with whitespace separating the ref‐
163 erence´s id from its location. Blank lines are allowed; lines beginning
164 with a # character are ignored:
165 # manuals included in this project:
168 whisky(1) whisky.1.ronn
169 tango(5) tango.5.ronn
170 # external manuals
172 grep(1) http://man.cx/grep(1)
173 ls(1) http://man.cx/ls(1)
174 # other URLs for use with markdown reference links
176 src http://github.com/
177 The location is an absolute or relative URL that usually points at an
181 HTML version of manpage. It´s possible to define references for things
182 that aren´t manpages.
183 All manuals in an individual directory share the references defined in
185 that directory´s index.txt file. Index references may be used explic‐
186 itly in Markdown reference style links using the syntax: [text][id],
187 where text is the link text and id is a reference name defined in the
188 index.
189
191 The --style option selects a list of CSS stylesheets to include in the
192 generated HTML. Styles are applied in the order defined, so each can
193 use the cascade to override previously defined styles.
194 Builtin Stylesheets
196 These styles are included with the distribution:
197 man Basic manpage styles: typography, definition lists, indentation.
199 This is always included regardless of --style argument. It is
200 however possible to replace the default man module with a custom
201 one by placing a man.css file on the RONN_STYLE path.
202 print Basic print stylesheet. The generated <style> tag includes a me‐
204 dia=print attribute.
205 toc Enables the Table of Contents navigation. The TOC markup is in‐
207 cluded in generated HTML by default but hidden with an inline
208 display:none style rule; the toc module turns it on and applies
209 basic TOC styles.
210 dark Light text on a dark background.
212 80c Changes the display width to mimic the display of a classic 80
214 character terminal. The default display width causes lines to
215 wrap at a gratuitous 100 characters.
216 Custom Stylesheets
218 Writing custom stylesheets is straight-forward. The following core se‐
219 lectors allow targeting all generated elements:
220 .mp The manual page container element. Present on full documents and
222 document fragments.
223 body#manpage
225 Signifies that the page was fully-generated by Ronn and contains
226 a single manual page (.mp element).
227 .man-decor
229 The three-item heading and footing elements both have this
230 class.
231 .man-head, .man-foot
233 The heading and footing, respectively.
234 .man-title
236 The main <h1> element. Hidden by default unless the manual has
237 no name or section attributes.
238 See the builtin style sources http://github.com/ap‐
240 janke/ronn-ng/tree/master/lib/ronn/template for examples.
241
243 Build roff and HTML output files and view the roff manpage using
244 man(1):
245 $ ronn some-great-program.1.ronn
248 roff: some-great-program.1
249 html: some-great-program.1.html
250 $ man ./some-great-program.1
251 Build only the roff manpage for all .ronn files in the current direc‐
255 tory:
256 $ ronn --roff *.ronn
259 roff: mv.1
260 roff: ls.1
261 roff: cd.1
262 roff: sh.1
263 Build only the HTML manpage for a few files and apply the dark and toc
267 stylesheets:
268 $ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
271 html: mv.1.html
272 html: ls.1.html
273 Generate roff output on standard output and write to file:
277 $ ronn <hello.1.ronn >hello.1
280 View a ronn file in the same way as man(1) without building a roff
284 file:
285 $ ronn --man hello.1.ronn
288 Serve HTML manpages at http://localhost:1207/ for all *.ronn files un‐
292 der a man/ directory:
293 $ ronn --server man/*.ronn
296 $ open http://localhost:1207/
297
301 RONN_MANUAL
302 A default manual name to be displayed in the top-center header
303 area. The --manual option takes precedence over this value.
304 RONN_ORGANIZATION
306 The default manual publishing group, organization, or individual
307 to be displayed in the bottom-left footer area. The --organiza‐
308 tion option takes precedence over this value.
309 RONN_DATE
311 The default manual date in YYYY-MM-DD format. Displayed in the
312 bottom-center footer area. The --date option takes precedence
313 over this value.
314 RONN_STYLE
316 A PATH-style list of directories to check for stylesheets given
317 to the --style option. Directories are separated by a :; blank
318 entries are ignored. Use . to include the current working direc‐
319 tory.
320 MANPAGER
322 The paging program used for man pages. This is typically set to
323 something like ´less -is´.
324 PAGER Used instead of MANPAGER when MANPAGER is not defined.
326
328 Ronn-NG is Copyright (C) 2009 Ryan Tomayko http://tomayko.com/about and
329 (C) 2018 Andrew Janke https://apjanke.net
330
332 groff(1), man(1), pandoc(1), manpages(5), markdown(7), roff(7),
333 ronn-format(7)
334Ronn-NG 0.9.1 January 2020 RONN(1)