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           ls(1) -- list directory contents
68           ================================
69
70
71
72       Indicates that the manpage is named ls in manual section 1 ("user  com‐
73       mands").
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           ## HEADING TEXT
83
84
85
86       Dash underline syntax:
87
88
89           HEADING TEXT
90           ------------
91
92
93
94       Section headings should be all uppercase and  may  not  contain  inline
95       markup.
96

INLINE MARKUP

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

DEFINITION LISTS

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

LINKS

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