ronn 0.4

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,220 @@
1
+ .\" generated with Ronn/v0.3
2
+ .\" http://github.com/rtomayko/ronn/
3
+ .
4
+ .TH "RONN" "1" "March 2010" "Ryan Tomayko" "Ronn Manual"
5
+ .
6
+ .SH "NAME"
7
+ \fBronn\fR \-\- build markdown\-based man pages
8
+ .
9
+ .SH "SYNOPSIS"
10
+ \fBronn\fR [ \fIOPTIONS\fR ] \fIFILE\fR ...
11
+ .
12
+ .br
13
+ \fBronn\fR \-\-build \fIFILE\fR ...
14
+ .
15
+ .br
16
+ \fBronn\fR \-\-install \fIFILE\fR ...
17
+ .
18
+ .br
19
+ \fBronn\fR \-\-man \fIFILE\fR
20
+ .
21
+ .SH "DESCRIPTION"
22
+ Ronn is a humane text format and toolchain for authoring man pages, and
23
+ things that appear as man pages from a distance. Use it to build and
24
+ install standard UNIX / roff(7) formatted man pages and to generate
25
+ nicely formatted HTML manual pages.
26
+ .
27
+ .P
28
+ The \fBronn\fR command converts one or more named input \fIFILE\fRs (or standard
29
+ input when no files are named or the file name \fB\-\fR is given) from humane
30
+ man page markup to one or more destination output formats. If no output
31
+ format is selected explicitly, \fBronn\fR writes output in roff format.
32
+ .
33
+ .SH "FILES"
34
+ The \fBronn\fR command expects input to be formatted as ronn(5) text. Source
35
+ files are typically named '\fINAME\fR.\fISECTION\fR.ronn' (e.g., \fBhello.1.ronn\fR).
36
+ The \fINAME\fR and \fISECTION\fR should match the name and section defined in \fIFILE\fR's heading.
37
+ .
38
+ .P
39
+ When building roff and/or HTML output files with the \fB\-\-build\fR argument,
40
+ destination filenames are determined by taking the basename of the input \fIFILE\fR and adding the appropriate file extension (or removing the file
41
+ extension in the case of roff output).
42
+ .
43
+ .P
44
+ For example, the command \fBronn \-b \-\-html \-\-roff hello.1.ronn\fR generates a \fBhello.1\fR file with roff output and a \fBhello.1.html\fR file with HTML
45
+ output.
46
+ .
47
+ .SH "OPTIONS"
48
+ \fBronn\fR's default mode of operation is to read a single document from
49
+ standard input and to write the result to standard output. The following
50
+ arguments change this behavior:
51
+ .
52
+ .TP
53
+ \fB\-b\fR, \fB\-\-build\fR
54
+ Write output directly to files instead of standard output. When the\fB\-\-roff\fR option is provided, writes roff output to \fIfile\fR.\fIsection\fR.
55
+ When the \fB\-\-html\fR option is provided, writes output to
56
+ '\fIfile\fR.\fIsection\fR.html'.
57
+ .
58
+ .TP
59
+ \fB\-i\fR, \fB\-\-install\fR
60
+ Install the roff formatted man page to the local system such that it
61
+ can be displayed by man(1). The \fBMANHOME\fR environment variable is
62
+ used to determine the prefix where man pages should be installed
63
+ when defined.
64
+ .
65
+ .IP
66
+ If \fBMANHOME\fR is not defined, \fBronn\fR installs man pages to \fI/usr/local/man\fR.
67
+ .
68
+ .TP
69
+ \fB\-m\fR, \fB\-\-man\fR
70
+ Display \fIFILE\fRs as if man(1) were invoked on the roff output file.
71
+ This simulates default man behavior by piping the roff output
72
+ through groff(1) and the paging program specified by the \fBMANPAGER\fR
73
+ environment variable.
74
+ .
75
+ .P
76
+ These options control the format used in generated output:
77
+ .
78
+ .TP
79
+ \fB\-r\fR, \fB\-\-roff\fR
80
+ Generate roff output. This is the default behavior when no other
81
+ format argument is provided.
82
+ .
83
+ .TP
84
+ \fB\-5\fR, \fB\-\-html\fR
85
+ Generate output in HTML format.
86
+ .
87
+ .TP
88
+ \fB\-f\fR, \fB\-\-fragment\fR
89
+ Generate output in HTML format but only the document fragment, not
90
+ the header, title, or footer.
91
+ .
92
+ .P
93
+ All document attributes displayed in the header and footer areas of
94
+ generated content can be specified with these options:
95
+ .
96
+ .TP
97
+ \fB\-\-manual\fR=\fIMANUAL\fR
98
+ The name of the manual this man page belongs to; \fIMANUAL\fR is
99
+ prominently displayed top\-center in the header area.
100
+ .
101
+ .TP
102
+ \fB\-\-organization\fR=\fINAME\fR
103
+ The name of the group, organization, or individual responsible for
104
+ publishing the document; \fINAME\fR is displayed in the bottom\-left
105
+ footer area.
106
+ .
107
+ .TP
108
+ \fB\-\-date\fR=\fIDATE\fR
109
+ The document's published date; \fIDATE\fR must be formatted \fBYYYY\-MM\-DD\fR
110
+ and is displayed in the bottom\-center footer area. The \fIFILE\fR mtime
111
+ is used when no \fIDATE\fR is given, or the current time when no \fIFILE\fR
112
+ is available.
113
+ .
114
+ .SH "EXAMPLES"
115
+ Generate \fBroff(7)\fR output on stdout:
116
+ .
117
+ .IP "" 4
118
+ .
119
+ .nf
120
+ $ ronn < hello.1.ronn
121
+ .
122
+ .fi
123
+ .
124
+ .IP "" 0
125
+ .
126
+ .P
127
+ Build a roff file based on the input filename:
128
+ .
129
+ .IP "" 4
130
+ .
131
+ .nf
132
+ $ ronn \-b hello.1.ronn
133
+ building: hello.1
134
+ $ man hello.1
135
+ .
136
+ .fi
137
+ .
138
+ .IP "" 0
139
+ .
140
+ .P
141
+ Build and open a standalone HTML file based on the input filename:
142
+ .
143
+ .IP "" 4
144
+ .
145
+ .nf
146
+ $ ronn \-b \-\-html test.1.ronn
147
+ $ open test.1.html
148
+ .
149
+ .fi
150
+ .
151
+ .IP "" 0
152
+ .
153
+ .P
154
+ Build roff and HTML versions of all \fB.ronn\fR files in the current
155
+ directory:
156
+ .
157
+ .IP "" 4
158
+ .
159
+ .nf
160
+ $ ronn \-b \-\-roff \-\-html *.ronn
161
+ building: hello.1
162
+ building: hello.1.html
163
+ building: world.1
164
+ building: world.1.html
165
+ .
166
+ .fi
167
+ .
168
+ .IP "" 0
169
+ .
170
+ .P
171
+ View a ronn file in the same way as man(1) without building a roff file:
172
+ .
173
+ .IP "" 4
174
+ .
175
+ .nf
176
+ $ ronn \-m hello.1.ronn
177
+ .
178
+ .fi
179
+ .
180
+ .IP "" 0
181
+ .
182
+ .P
183
+ Install the roff man page for a ronn file:
184
+ .
185
+ .IP "" 4
186
+ .
187
+ .nf
188
+ $ ronn \-i hello.1.ronn
189
+ .
190
+ .fi
191
+ .
192
+ .IP "" 0
193
+ .
194
+ .SH "ENVIRONMENT"
195
+ .
196
+ .TP
197
+ \fBMANHOME\fR
198
+ Location where roff formatted man pages are installed. Relevant
199
+ only when the \fB\-\-install\fR argument is provided. \fIPATH\fR is to the
200
+ base of a man file hierarchy. e.g., \fB/usr/local/share/man\fR, \fB/home/rtomayko/man\fR.
201
+ .
202
+ .TP
203
+ \fBMANPAGER\fR
204
+ The paging program used for man pages. This is typically set to
205
+ something like 'less \-is'.
206
+ .
207
+ .TP
208
+ \fBPAGER\fR
209
+ Used instead of \fBMANPAGER\fR when \fBMANPAGER\fR is not defined.
210
+ .
211
+ .SH "BUGS"
212
+ Ronn is written in Ruby and depends on hpricot and rdiscount, extension
213
+ libraries that are non\-trivial to install on some systems. A more portable
214
+ version of this program would be welcome.
215
+ .
216
+ .SH "COPYRIGHT"
217
+ Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
218
+ .
219
+ .SH "SEE ALSO"
220
+ ronn(5), markdown(5), manpages(5), man(1), roff(7), groff(1)
@@ -0,0 +1,158 @@
1
+ ronn(1) -- build markdown-based man pages
2
+ ========================================
3
+
4
+ ## SYNOPSIS
5
+
6
+ `ronn` [ <OPTIONS> ] <FILE> ...
7
+ `ronn` --build <FILE> ...
8
+ `ronn` --install <FILE> ...
9
+ `ronn` --man <FILE>
10
+
11
+ ## DESCRIPTION
12
+
13
+ Ronn is a humane text format and toolchain for authoring man pages, and
14
+ things that appear as man pages from a distance. Use it to build and
15
+ install standard UNIX / roff(7) formatted man pages and to generate
16
+ nicely formatted HTML manual pages.
17
+
18
+ The `ronn` command converts one or more named input <FILE>s (or standard
19
+ input when no files are named or the file name `-` is given) from humane
20
+ man page markup to one or more destination output formats. If no output
21
+ format is selected explicitly, `ronn` writes output in roff format.
22
+
23
+ ## FILES
24
+
25
+ The `ronn` command expects input to be formatted as ronn(5) text. Source
26
+ files are typically named '<NAME>.<SECTION>.ronn' (e.g., `hello.1.ronn`).
27
+ The <NAME> and <SECTION> should match the name and section defined in
28
+ <FILE>'s heading.
29
+
30
+ When building roff and/or HTML output files with the `--build` argument,
31
+ destination filenames are determined by taking the basename of the input
32
+ <FILE> and adding the appropriate file extension (or removing the file
33
+ extension in the case of roff output).
34
+
35
+ For example, the command `ronn -b --html --roff hello.1.ronn` generates a
36
+ `hello.1` file with roff output and a `hello.1.html` file with HTML
37
+ output.
38
+
39
+ ## OPTIONS
40
+
41
+ `ronn`'s default mode of operation is to read a single document from
42
+ standard input and to write the result to standard output. The following
43
+ arguments change this behavior:
44
+
45
+ * `-b`, `--build`:
46
+ Write output directly to files instead of standard output. When the
47
+ `--roff` option is provided, writes roff output to <file>.<section>.
48
+ When the `--html` option is provided, writes output to
49
+ '<file>.<section>.html'.
50
+
51
+ * `-i`, `--install`:
52
+ Install the roff formatted man page to the local system such that it
53
+ can be displayed by man(1). The `MANHOME` environment variable is
54
+ used to determine the prefix where man pages should be installed
55
+ when defined.
56
+
57
+ If `MANHOME` is not defined, `ronn` installs man pages to
58
+ _/usr/local/man_.
59
+
60
+ * `-m`, `--man`:
61
+ Display <FILE>s as if man(1) were invoked on the roff output file.
62
+ This simulates default man behavior by piping the roff output
63
+ through groff(1) and the paging program specified by the `MANPAGER`
64
+ environment variable.
65
+
66
+ These options control the format used in generated output:
67
+
68
+ * `-r`, `--roff`:
69
+ Generate roff output. This is the default behavior when no other
70
+ format argument is provided.
71
+
72
+ * `-5`, `--html`:
73
+ Generate output in HTML format.
74
+
75
+ * `-f`, `--fragment`:
76
+ Generate output in HTML format but only the document fragment, not
77
+ the header, title, or footer.
78
+
79
+ All document attributes displayed in the header and footer areas of
80
+ generated content can be specified with these options:
81
+
82
+ * `--manual`=<MANUAL>:
83
+ The name of the manual this man page belongs to; <MANUAL> is
84
+ prominently displayed top-center in the header area.
85
+
86
+ * `--organization`=<NAME>:
87
+ The name of the group, organization, or individual responsible for
88
+ publishing the document; <NAME> is displayed in the bottom-left
89
+ footer area.
90
+
91
+ * `--date`=<DATE>:
92
+ The document's published date; <DATE> must be formatted `YYYY-MM-DD`
93
+ and is displayed in the bottom-center footer area. The <FILE> mtime
94
+ is used when no <DATE> is given, or the current time when no <FILE>
95
+ is available.
96
+
97
+ ## EXAMPLES
98
+
99
+ Generate `roff(7)` output on stdout:
100
+
101
+ $ ronn < hello.1.ronn
102
+
103
+ Build a roff file based on the input filename:
104
+
105
+ $ ronn -b hello.1.ronn
106
+ building: hello.1
107
+ $ man hello.1
108
+
109
+ Build and open a standalone HTML file based on the input filename:
110
+
111
+ $ ronn -b --html test.1.ronn
112
+ $ open test.1.html
113
+
114
+ Build roff and HTML versions of all `.ronn` files in the current
115
+ directory:
116
+
117
+ $ ronn -b --roff --html *.ronn
118
+ building: hello.1
119
+ building: hello.1.html
120
+ building: world.1
121
+ building: world.1.html
122
+
123
+ View a ronn file in the same way as man(1) without building a roff file:
124
+
125
+ $ ronn -m hello.1.ronn
126
+
127
+ Install the roff man page for a ronn file:
128
+
129
+ $ ronn -i hello.1.ronn
130
+
131
+ ## ENVIRONMENT
132
+
133
+ * `MANHOME`:
134
+ Location where roff formatted man pages are installed. Relevant
135
+ only when the `--install` argument is provided. <PATH> is to the
136
+ base of a man file hierarchy. e.g., `/usr/local/share/man`,
137
+ `/home/rtomayko/man`.
138
+
139
+ * `MANPAGER`:
140
+ The paging program used for man pages. This is typically set to
141
+ something like 'less -is'.
142
+
143
+ * `PAGER`:
144
+ Used instead of `MANPAGER` when `MANPAGER` is not defined.
145
+
146
+ ## BUGS
147
+
148
+ Ronn is written in Ruby and depends on hpricot and rdiscount, extension
149
+ libraries that are non-trivial to install on some systems. A more portable
150
+ version of this program would be welcome.
151
+
152
+ ## COPYRIGHT
153
+
154
+ Ronn is Copyright (C) 2009 Ryan Tomayko <tomayko.com/about>
155
+
156
+ ## SEE ALSO
157
+
158
+ ronn(5), markdown(5), manpages(5), man(1), roff(7), groff(1)
@@ -0,0 +1,190 @@
1
+ .\" generated with Ronn/v0.3
2
+ .\" http://github.com/rtomayko/ronn/
3
+ .
4
+ .TH "RONN" "5" "March 2010" "Ryan Tomayko" "Ronn Manual"
5
+ .
6
+ .SH "NAME"
7
+ \fBronn\fR \-\- humane manual page authoring format
8
+ .
9
+ .SH "SYNOPSIS"
10
+ .
11
+ .nf
12
+ name(1) \-\- one sentence description
13
+ ===================================
14
+ ## SECTION HEADING
15
+ A normal paragraph. This can span multiple lines and is
16
+ terminated with two or more line endings \-\- just like
17
+ Markdown.
18
+ ## INLINE MARKUP
19
+ Inline markup is used for `code` and `user input` (displayed
20
+ in boldface), and also <variables> or _emphasis_.
21
+ Manual page references like sh(1), markdown(5), roff(7), etc.
22
+ are displayed in boldface and hyperlinked in HTML output.
23
+ ## DEFINITION LISTS
24
+ Definition lists are used to define options, arguments,
25
+ variables, and other type of terms:
26
+ * `\-a`, `\-\-arg1`=[_OPTION_]:
27
+ One or more paragraphs describing the argument.
28
+ * `\-b`, `\-\-arg2`:
29
+ Any number of these may be specified and may
30
+ be nested.
31
+ .
32
+ .fi
33
+ .
34
+ .SH "DESCRIPTION"
35
+ Ronn files are simple ascii texts that document things in the
36
+ style of UNIX man pages but with a syntax and feature\-set less
37
+ insane than that of roff(7). Ronn files are piped through ronn(1)
38
+ to build and install traditional roff(7) man pages or to generate
39
+ hyperlinked HTML documentation.
40
+ .
41
+ .P
42
+ All ronn formatted files must conform to a simple subset of
43
+ markdown(5), a humane text markup designed for writing on the
44
+ web. It is neither possible nor desirable to express many of
45
+ roff(7)'s complex typesetting features in ronn.
46
+ .
47
+ .SH "MANPAGE TITLE"
48
+ All man pages have a \fIname\fR, belong to a \fIsection\fR, and have a
49
+ single sentence \fItagline\fR (useless but witty, preferably). Ronn
50
+ files must begin with a first\-level heading that includes all of
51
+ this information. For example, this very man page begins:
52
+ .
53
+ .IP "" 4
54
+ .
55
+ .nf
56
+ ronn(5) \-\- humane manual page authoring format
57
+ =============================================
58
+ .
59
+ .fi
60
+ .
61
+ .IP "" 0
62
+ .
63
+ .P
64
+ Here, we're saying that the man page documents a thing named\fBronn\fR in manual section \fB5\fR (the "file formats" section; see
65
+ manpages(5) for full section list) and that's quickly described
66
+ as a "humane manual page authoring format".
67
+ .
68
+ .P
69
+ These bits of information are used to fill in the document
70
+ header, to create the \fBNAME\fR section, and also to establish
71
+ output filenames when processed with ronn(1).
72
+ .
73
+ .SH "SECTION HEADINGS"
74
+ Man section headings are expressed with markdown level two
75
+ headings. markdown(5) provides two syntaxes for level two
76
+ headings. A hash prefix syntax:
77
+ .
78
+ .IP "" 4
79
+ .
80
+ .nf
81
+ ## HEADING TEXT
82
+ .
83
+ .fi
84
+ .
85
+ .IP "" 0
86
+ .
87
+ .P
88
+ Or, a dash underline syntax:
89
+ .
90
+ .IP "" 4
91
+ .
92
+ .nf
93
+ HEADING TEXT
94
+ \-\-\-\-\-\-\-\-\-\-\-\-
95
+ .
96
+ .fi
97
+ .
98
+ .IP "" 0
99
+ .
100
+ .P
101
+ Section headings should be in all uppercase and may not contain
102
+ other inline markup.
103
+ .
104
+ .P
105
+ Most manual pages include at least one of the \fBSYNOPSIS\fR, \fBDESCRIPTION\fR, and/or \fBOPTIONS\fR sections. Additional sections
106
+ commonly included are \fBSYNTAX\fR, \fBENVIRONMENT\fR, \fBHISTORY\fR, \fBRETURN
107
+ VALUES\fR, \fBBUGS\fR, \fBSECURITY CONSIDERATIONS\fR, \fBSTANDARDS\fR / \fBCONFORMING TO\fR, \fBAUTHOR\fR, and \fBCOPYRIGHT\fR. Finally, most man
108
+ pages end with a \fBSEE ALSO\fR section that references other manual
109
+ pages and external documents.
110
+ .
111
+ .SH "INLINE MARKUP"
112
+ Man pages have a limited set of text formatting capabilities at
113
+ their disposal. There's basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR). Ronn uses
114
+ the following bits of markdown(5) to accomplish this:
115
+ .
116
+ .TP
117
+ \fB`backticks`\fR
118
+ Code, flags, commands, and noun\-like things; typically
119
+ displayed in in \fBboldface\fR. Note that all text included
120
+ within \fBbackticks\fR is displayed literally; other inline markup
121
+ is not processed.
122
+ .
123
+ .TP
124
+ \fB**double\-stars**\fR
125
+ Like \fBbackticks\fR but inline markup is processed.
126
+ .
127
+ .TP
128
+ \fB_\fR\fIunderbars\fR\fB_\fR
129
+ User\-specified arguments, variables, or user input; typically
130
+ displayed with \fIunderline\fR.
131
+ .
132
+ .TP
133
+ \fB<angle\-quotes>\fR
134
+ Same as \fIunderbars\fR. This is not compatible with Markdown.
135
+ .
136
+ .P
137
+ Here is grep(1)'s DESCRIPTION section represented in \fBronn\fR:
138
+ .
139
+ .IP "" 4
140
+ .
141
+ .nf
142
+ `Grep` searches the named input _FILE_ (or standard input if
143
+ no files are named, or the file name `\-` is given) for lines
144
+ containing a match to the given _PATTERN_. By default, `grep`
145
+ prints the matching lines.
146
+ .
147
+ .fi
148
+ .
149
+ .IP "" 0
150
+ .
151
+ .SH "DEFINITION LISTS"
152
+ Because definition lists are so often used in manual pages to
153
+ describe arguments, options, and variables, the basic markdown(5)
154
+ list syntax has been extended to support a definition list
155
+ syntax.
156
+ .
157
+ .P
158
+ Definition list syntax is exactly the same as markdown(5)'s
159
+ unordered list syntax but requires that the first line of each
160
+ list item be terminated with a colon "\fB:\fR". The first line (minus
161
+ the colon) is the \fIterm\fR; subsequent lines may be comprised of
162
+ multiple paragraphs, code blocks, standard lists, and nested
163
+ definition lists.
164
+ .
165
+ .P
166
+ An example definition list, taken from BSD test(1)'s\fBDESCRIPTION\fR section:
167
+ .
168
+ .IP "" 4
169
+ .
170
+ .nf
171
+ The following primaries are used to construct expressions:
172
+ * `\-b` _file_:
173
+ True if _file_ exists and is a block special file.
174
+ * `\-c` _file_:
175
+ True if _file_ exists and is a character special file.
176
+ * `\-d` _file_:
177
+ True if file exists and is a directory.
178
+ .
179
+ .fi
180
+ .
181
+ .IP "" 0
182
+ .
183
+ .P
184
+ The definition list syntax is intentionally backward compatible
185
+ with markdown(5)'s list syntax. This allows \fBronn\fR documents to be
186
+ piped through normal markdown processors with minor degradation
187
+ in output formatting.
188
+ .
189
+ .SH "SEE ALSO"
190
+ ronn(1), markdown(5), manpages(5)