ronn 0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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)