ronn-format(7)

1RONN-FORMAT(7)                    Ronn Manual                   RONN-FORMAT(7)
2
3
4

NAME

6       ronn-format - manual authoring format based on Markdown
7

SYNOPSIS

9       name(1) -- short, single-sentence description
10       =============================================
11
12       ## SYNOPSIS
13
14       `name` [<optional>...] <flags>
15
16       ## DESCRIPTION
17
18       A normal paragraph. This can span multiple lines and is terminated with two
19       or more line endings -- just like Markdown.
20
21       Inline markup for `code`, `user input`, and **strong** are displayed
22       boldface; <variable>, _emphasis_, *emphasis*, are displayed in italics
23       (HTML) or underline (roff).
24
25       Manual references like sh(1), markdown(7), roff(7), etc. are hyperlinked in
26       HTML output.
27
28       Link to sections like [STANDARDS][], [SEE ALSO][], or [WITH A DIFFERENT LINK
29       TEXT][#SEE-ALSO].
30
31       Definition lists:
32
33         * `-a`, `--argument`=[<value>]:
34           One or more paragraphs describing the argument.
35
36         * You can put whatever you *want* here, really:
37           Nesting and paragraph spacing are respected.
38
39       Frequently used sections:
40
41       ## OPTIONS
42       ## SYNTAX
43       ## ENVIRONMENT
44       ## RETURN VALUES
45       ## STANDARDS
46       ## SECURITY CONSIDERATIONS
47       ## BUGS
48       ## HISTORY
49       ## AUTHOR
50       ## COPYRIGHT
51       ## SEE ALSO
52

DESCRIPTION

54       The  ronn(1)  command  converts  text in a simple markup to UNIX manual
55       pages. The syntax includes all Markdown formatting features, plus  con‐
56       ventions  for expressing the structure and various notations present in
57       standard UNIX manpages.
58
59       Not all roff(7) typesetting features can be expressed using  ronn  syn‐
60       tax.
61

MANPAGE TITLE

63       Manpages  have  a name, section, and a one-line description. Files must
64       start with a level one heading defining these attributes:
65
66
67
68           ls(1) -- list directory contents
69           ================================
70
71
72
73       Indicates that the manpage is named ls in manual section 1 (
74

SECTION HEADINGS

76       Man section headings are expressed with markdown  level  two  headings.
77       There are two syntaxes for level two headings.
78
79       Hash prefix syntax:
80
81
82
83           ## HEADING TEXT
84
85
86
87       Dash underline syntax:
88
89
90
91           HEADING TEXT
92           ------------
93
94
95
96       Section  headings  should  be  all uppercase and may not contain inline
97       markup.
98

INLINE MARKUP

100       Manpages have a limited set of text  formatting  capabilities.  There´s
101       basically  boldface and italics (often displayed using underline). Ronn
102       uses the following bits of markdown(7) to accomplish this:
103
104       `backticks` (markdown compatible)
105              Code, flags, commands, and noun-like things; typically displayed
106              in  in boldface. All text included within backticks is displayed
107              literally; other inline markup is not  processed.  HTML  output:
108              <code>.
109
110       **double-stars** (markdown compatible)
111              Also  displayed  in boldface. Unlike backticks, inline markup is
112              processed. HTML output: <strong>.
113
114       <anglequotes> (non-compatible markdown extension)
115              User-specified arguments, variables, or  user  input.  Typically
116              displayed with underline in roff output. HTML output: <var/>.
117
118       _underbars_ (markdown compatible)
119              Emphasis.  May be used for literal option values. Typically dis‐
120              played with underline in roff output. HTML output: <em>.
121
122       Here is grep(1)´s DESCRIPTION section represented in ronn:
123
124
125
126           `Grep` searches the named input <FILE> (or standard input if
127           no files are named, or the file name `-` is given) for lines
128           containing a match to the given <PATTERN>. By default, `grep`
129           prints the matching lines.
130
131
132

DEFINITION LISTS

134       The definition list syntax is compatible with markdown´s unordered list
135       syntax but requires that the first line of each list item be terminated
136       with a colon
137
138       An example definition list, taken from BSD test(1)´s  DESCRIPTION  sec‐
139       tion:
140
141
142
143            The following primaries are used to construct expressions:
144
145              * `-b` <file>:
146                True if <file> exists and is a block special file.
147
148              * `-c` <file>:
149                True if _file_ exists and is a character special file.
150
151              * `-d` <file>:
152                True if file exists and is a directory.
153
154
155

LINKS

157       All markdown(7) linking features are supported.
158
159       Markdown reference-style links can be used to link to specific sections
160       by name:
161
162
163
164           ## SECTION 1
165
166           See the following section.
167
168           ## SECTION 2
169
170           See [SECTION 1][] or [to put it another way][SECTION 1].
171
172
173
174       The anchor name would be #SECTION-1 and #SECTION-2. All non-word  char‐
175       acters are removed and spaces are replaced by dashes.
176