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

DESCRIPTION

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
20       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
26       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
30       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

FILES

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
41       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

OPTIONS

48       These  options  control  whether output is written to file(s), standard
49       output, or directly to a man pager.
50
51       -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
57       -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
64              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
69              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
73       --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
77       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
81       -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
85       -5, --html
86              Generate output in HTML format.
87
88       -f, --fragment
89              Generate  output  in HTML format but only the document fragment,
90              not the header, title, or footer.
91
92       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
96       --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
100       --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
105       --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
111       HTML output can be customized through the use of CSS stylesheets:
112
113       --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
118              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
122              When module includes a / character, use it as the full path to a
123              stylesheet file.
124
125              Internal styles are man (included by default), toc, and 80c. See
126              STYLES for descriptions of features added by each module.
127
128       Miscellaneous options:
129
130       -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
135       -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
139       -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
150
151
152           # manuals included in this project:
153           whisky(1)    whisky.1.ronn
154           tango(5)     tango.5.ronn
155
156           # external manuals
157           grep(1)      http://man.cx/grep(1)
158           ls(1)        http://man.cx/ls(1)
159
160           # other URLs for use with markdown reference links
161           src          http://github.com/
162
163
164
165       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
169       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

STYLES

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
180   Builtin Stylesheets
181       These styles are included with the distribution:
182
183       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
188       print  Basic print stylesheet. The generated  <style>  tag  includes  a
189              media=print attribute.
190
191       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
196       dark   Light text on a dark background.
197
198       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
202   Custom Stylesheets
203       Writing custom stylesheets  is  straight-forward.  The  following  core
204       selectors allow targeting all generated elements:
205
206       .mp    The manual page container element. Present on full documents and
207              document fragments.
208
209       body#manpage
210              Signifies that the page was fully-generated by Ronn and contains
211              a single manual page (.mp element).
212
213       .man-decor
214              The  three-item  heading  and  footing  elements  both have this
215              class.
216
217       .man-head, .man-foot
218              The heading and footing, respectively.
219
220       .man-title
221              The main <h1> element. Hidden by default unless the  manual  has
222              no name or section attributes.
223
224       See the builtin style sources http://github.com/rtomayko/ronn/tree/mas
225       ter/lib/ronn/template for examples.
226

EXAMPLES

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

ENVIRONMENT

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
296       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
301       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
306       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
312       MANPAGER
313              The  paging program used for man pages. This is typically set to
314              something like ´less -is´.
315
316       PAGER  Used instead of MANPAGER when MANPAGER is not defined.
317

BUGS

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

SEE ALSO

327       ronn-format(7), manpages(5), man(1), roff(7), groff(1), markdown(7)
328
329
330
331Ronn 0.7.0                         June 2010                           RONN(1)
Impressum