/
ronn-format.7
201 lines (176 loc) · 4.92 KB
/
ronn-format.7
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
.\" generated with Ronn/v0.7.0
.\" http://github.com/rtomayko/ronn/tree/0.7.0
.
.TH "RONN\-FORMAT" "7" "June 2010" "Ronn 0.7.0" "Ronn Manual"
.
.SH "NAME"
\fBronn\-format\fR \- manual authoring format based on Markdown
.
.SH "SYNOPSIS"
.
.nf
name(1) \-\- short, single\-sentence description
=============================================
## SYNOPSIS
`name` [<optional>\.\.\.] <flags>
## DESCRIPTION
A normal paragraph\. This can span multiple lines and is terminated with two
or more line endings \-\- just like Markdown\.
Inline markup for `code`, `user input`, and **strong** are displayed
boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
(HTML) or underline (roff)\.
Manual references like sh(1), markdown(7), roff(7), etc\. are hyperlinked in
HTML output\.
Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
TEXT][#SEE\-ALSO]\.
Definition lists:
* `\-a`, `\-\-argument`=[<value>]:
One or more paragraphs describing the argument\.
* You can put whatever you *want* here, really:
Nesting and paragraph spacing are respected\.
Frequently used sections:
## OPTIONS
## SYNTAX
## ENVIRONMENT
## RETURN VALUES
## STANDARDS
## SECURITY CONSIDERATIONS
## BUGS
## HISTORY
## AUTHOR
## COPYRIGHT
## SEE ALSO
.
.fi
.
.SH "DESCRIPTION"
The ronn(1) command converts text in a simple markup to UNIX manual pages\. The syntax includes all Markdown formatting features, plus conventions for expressing the structure and various notations present in standard UNIX manpages\.
.
.P
Not all roff(7) typesetting features can be expressed using ronn syntax\.
.
.SH "MANPAGE TITLE"
Manpages have a \fIname\fR, \fIsection\fR, and a one\-line \fIdescription\fR\. Files must start with a level one heading defining these attributes:
.
.IP "" 4
.
.nf
ls(1) \-\- list directory contents
================================
.
.fi
.
.IP "" 0
.
.P
Indicates that the manpage is named \fBls\fR in manual section \fB1\fR (\"user commands\")\.
.
.SH "SECTION HEADINGS"
Man section headings are expressed with markdown level two headings\. There are two syntaxes for level two headings\.
.
.P
Hash prefix syntax:
.
.IP "" 4
.
.nf
## HEADING TEXT
.
.fi
.
.IP "" 0
.
.P
Dash underline syntax:
.
.IP "" 4
.
.nf
HEADING TEXT
\-\-\-\-\-\-\-\-\-\-\-\-
.
.fi
.
.IP "" 0
.
.P
Section headings should be all uppercase and may not contain inline markup\.
.
.SH "INLINE MARKUP"
Manpages have a limited set of text formatting capabilities\. There\'s basically \fBboldface\fR and \fIitalics\fR (often displayed using \fIunderline\fR)\. Ronn uses the following bits of markdown(7) to accomplish this:
.
.TP
\fB`backticks`\fR (markdown compatible)
Code, flags, commands, and noun\-like things; typically displayed in in \fBboldface\fR\. All text included within \fBbackticks\fR is displayed literally; other inline markup is not processed\. HTML output: \fB<code>\fR\.
.
.TP
\fB**double\-stars**\fR (markdown compatible)
Also displayed in boldface\. Unlike backticks, inline markup is processed\. HTML output: \fB<strong>\fR\.
.
.TP
\fB<anglequotes>\fR (non\-compatible markdown extension)
User\-specified arguments, variables, or user input\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<var/>\fR\.
.
.TP
\fB_\fR\fIunderbars\fR\fB_\fR (markdown compatible)
Emphasis\. May be used for literal option values\. Typically displayed with \fIunderline\fR in roff output\. HTML output: \fB<em>\fR\.
.
.P
Here is grep(1)\'s DESCRIPTION section represented in \fBronn\fR:
.
.IP "" 4
.
.nf
`Grep` searches the named input <FILE> (or standard input if
no files are named, or the file name `\-` is given) for lines
containing a match to the given <PATTERN>\. By default, `grep`
prints the matching lines\.
.
.fi
.
.IP "" 0
.
.SH "DEFINITION LISTS"
The definition list syntax is compatible with markdown\'s unordered list syntax but requires that the first line of each list item be terminated with a colon \"\fB:\fR\" character\. The contents of the first line is the \fIterm\fR; subsequent lines may be comprised of multiple paragraphs, code blocks, standard lists, and nested definition lists\.
.
.P
An example definition list, taken from BSD test(1)\'s \fIDESCRIPTION\fR section:
.
.IP "" 4
.
.nf
The following primaries are used to construct expressions:
* `\-b` <file>:
True if <file> exists and is a block special file\.
* `\-c` <file>:
True if _file_ exists and is a character special file\.
* `\-d` <file>:
True if file exists and is a directory\.
.
.fi
.
.IP "" 0
.
.SH "LINKS"
All markdown(7) linking features are supported\.
.
.P
Markdown reference\-style links can be used to link to specific sections by name:
.
.IP "" 4
.
.nf
## SECTION 1
See the following section\.
## SECTION 2
See [SECTION 1][] or [to put it another way][SECTION 1]\.
.
.fi
.
.IP "" 0
.
.P
The anchor name would be \fB#SECTION\-1\fR and \fB#SECTION\-2\fR\. All non\-word characters are removed and spaces are replaced by dashes\.
.
.SH "SEE ALSO"
ronn(1), markdown(7), roff(7)