1RONN(1)                           Ronn Manual                          RONN(1)
2
3
4

NAME

6       ronn - convert markdown files to manpages
7

SYNOPSIS

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

DESCRIPTION

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
21       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
27       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
31       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

FILES

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
42       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
46       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

OPTIONS

53       These  options  control  whether output is written to file(s), standard
54       output, or directly to a man pager.
55
56-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
61-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
67           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
72           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
76--port=port When used with -S/--server,  runs  the  server  at  the
77           specified port instead of the default port 1207.
78
79--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
83-o=directory,  --output-dir=directory: Write generated files to the
84           specified directory instead of the default location.
85
86-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
91
92
93       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
97       -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
101       -5, --html
102              Generate output in HTML format.
103
104       -f, --fragment
105              Generate output in HTML format but only the  document  fragment,
106              not the header, title, or footer.
107
108       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
112       --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
116       --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
121       --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
127       HTML output can be customized through the use of CSS stylesheets:
128
129       --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
134              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
138              When module includes a / character, use it as the full path to a
139              stylesheet file.
140
141              Internal styles are man (included by default), toc, and 80c. See
142              STYLES for descriptions of features added by each module.
143
144       Miscellaneous options:
145
146       -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
151       -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
155       -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
166
167           # manuals included in this project:
168           whisky(1)    whisky.1.ronn
169           tango(5)     tango.5.ronn
170
171           # external manuals
172           grep(1)      http://man.cx/grep(1)
173           ls(1)        http://man.cx/ls(1)
174
175           # other URLs for use with markdown reference links
176           src          http://github.com/
177
178
179
180       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
184       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

STYLES

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
195   Builtin Stylesheets
196       These styles are included with the distribution:
197
198       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
203       print  Basic print stylesheet. The generated <style> tag includes a me‐
204              dia=print attribute.
205
206       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
211       dark   Light text on a dark background.
212
213       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
217   Custom Stylesheets
218       Writing  custom stylesheets is straight-forward. The following core se‐
219       lectors allow targeting all generated elements:
220
221       .mp    The manual page container element. Present on full documents and
222              document fragments.
223
224       body#manpage
225              Signifies that the page was fully-generated by Ronn and contains
226              a single manual page (.mp element).
227
228       .man-decor
229              The three-item heading  and  footing  elements  both  have  this
230              class.
231
232       .man-head, .man-foot
233              The heading and footing, respectively.
234
235       .man-title
236              The  main  <h1> element. Hidden by default unless the manual has
237              no name or section attributes.
238
239       See     the     builtin     style     sources     http://github.com/ap
240       janke/ronn-ng/tree/master/lib/ronn/template for examples.
241

EXAMPLES

243       Build  roff  and  HTML  output  files  and  view the roff manpage using
244       man(1):
245
246
247           $ 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
252
253
254       Build only the roff manpage for all .ronn files in the  current  direc‐
255       tory:
256
257
258           $ ronn --roff *.ronn
259           roff: mv.1
260           roff: ls.1
261           roff: cd.1
262           roff: sh.1
263
264
265
266       Build  only the HTML manpage for a few files and apply the dark and toc
267       stylesheets:
268
269
270           $ ronn --html --style=dark,toc mv.1.ronn ls.1.ronn
271           html: mv.1.html
272           html: ls.1.html
273
274
275
276       Generate roff output on standard output and write to file:
277
278
279           $ ronn <hello.1.ronn >hello.1
280
281
282
283       View a ronn file in the same way as  man(1)  without  building  a  roff
284       file:
285
286
287           $ ronn --man hello.1.ronn
288
289
290
291       Serve  HTML manpages at http://localhost:1207/ for all *.ronn files un‐
292       der a man/ directory:
293
294
295           $ ronn --server man/*.ronn
296           $ open http://localhost:1207/
297
298
299

ENVIRONMENT

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
305       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
310       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
315       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
321       MANPAGER
322              The paging program used for man pages. This is typically set  to
323              something like ´less -is´.
324
325       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

SEE ALSO

332       groff(1),  man(1),  pandoc(1),   manpages(5),   markdown(7),   roff(7),
333       ronn-format(7)
334
335
336
337Ronn-NG 0.9.1                    January 2020                          RONN(1)
Impressum