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
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"https://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<link rel=stylesheet type="text/css" href="style.css" title="style">
<title>
Patches for man-pages
</title>
</head>
<body>
<!--BEGIN-LINKS-->
<form method="get" action="https://www.google.com/search">
<table border=0 cellpadding=0 cellspacing=0 width="100%">
<tr>
<td align="left">
<font size="-1">
Linux <em>man-pages</em>:
<a href="./index.html">home</a> |
<a href="./contributing.html">contributing</a> |
<a href="./reporting_bugs.html">bugs</a> |
patches |
<a href="./download.html">download</a>
||
<a href="https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git">git</a> |
<a href="https://man7.org/linux/man-pages/index.html">online pages</a></font>
</td>
<td align="right">
<input type="text" name="q" size=10 maxlength=255 value="">
<input type="hidden" name="sitesearch" value="man7.org/linux/man-pages">
<input type="submit" name="sa" value="Search online pages">
</td>
</tr>
</table>
</form>
<!--END-LINKS-->
<h1>Patches for <em>man-pages</em></h1>
<p>
If you know how to fix a problem in a manual page (if not, look
<a href="reporting_bugs.html">here</a>), then send a patch,
and <strong>make sure that you</strong>:
</p>
<ul>
<li>
Put <span class="email">linux-man@vger.kernel.org</span>
into "To:" or "CC:"
(<a href="linux-man-ml.html"><em>no HTML mail please</em></a>),
</li>
<li>
Include the string "[patch]" in the subject line
</li>
<li>
Include either or both comaintainers
(Alejandro Colomar <span class="email"><alx.manpages@gmail.com></span>
and
Michael Kerrisk <span class="email"><mtk.manpages@gmail.com></span>)
in "To:" or "CC:".
(Please do <strong>not</strong> CC mtk's
<span class="email">@man7.org</span> email address.)
</li>
</ul>
<p>
<strong>The above is the minimum needed so that someone
might respond to your patch.</strong>
(If you did that, and someone does not respond within a few days,
then ping the mail thread, "replying to all".)
</p>
<p>
<strong>To make your patch even more useful</strong>,
please note the following points:
</p>
<ul>
<li>
<strong>Make sure that the mail has a suitable <em>Subject</em>
line</strong>
(i.e., one that mentions the name(s) of the page(s) being patched).
<!--
Don't put the
<em>man-pages</em>
version in the subject line (it should
already be in the body, and cluttering the subject line with a version
number does not help me when filing messages...).
-->
A suitable subject line might be something like:
<pre>
[patch] shmop.2: Add "(void *)" cast to RETURN VALUE </pre>
</li>
<li>
For <strong>nontrivial patches</strong>:
<br>
<br>
</li>
<ul>
<li>
<strong>Describe how you obtained the information in your patch</strong>:
was it by reading (or
writing) the relevant kernel or (g)libc source code; by writing a
test program (send it with the patch, if you want, and if it is clear and
simple to use); from a standards document;
from other documentation; from a mailing list or online forum
(please provide a URL if possible)?
<br>
<br>
</li>
<li>
Where relevant, include source code comments that
<strong>cite commit hashes</strong> for relevant kernel or glibc changes:
<pre>
.\" commit <40-character-git-hash></pre>
Doing so can be useful to help verify details of the patch,
or for later historical reference.
<br>
<br>
</li>
<li>
<strong>Please attempt to find and CC relevant developers.</strong>
If your patch documents a substantial feature or change, and you
know which developers added the feature or made the change
that your patch documents, please CC them on the patch;
with luck they may review and fix your patch.
If you don't know who the developers are, you may be
able to discover that information from mailing list archives
or from Git logs or logs in other version control systems.
Obviously, if you are the developer of the feature being documented
in a <em>man-pages</em> patch, please identify yourself as such.
<br>
<br>
</li>
<li>
<strong>Please consider CCing relevant mailing lists</strong>.
If your patch documents a substantial feature or change, please
consider CCing relevant mailing lists on your patch.
With luck, subscribers on the mailing list might review your patch.
Relevant mailing lists may include:
<br>
<br>
<ul>
<li>
<span class="email">linux-kernel@vger.kernel.org</span> for patches to system call pages
</li>
<li>
<span class="email">netdev@vger.kernel.org</span> for patches to pages relating to networking and sockets
</li>
</ul>
<br>
The GNU C library developers
don't consider
<em>man-pages</em> to
be any sort of official documentation for the library.
However, if you have a new page for Section 3 or a substantial addition
to one of those pages, you might consider CCing
<span class="email">libc-alpha@sourceware.org</span>;
there are some friendly folk there who may review or comment.
<br>
<br>
</li>
</ul>
<li>
For <strong>trivial patches</strong>,
the project uses a number of keywords that are processed by
scripts that automatically build the release changelogs.
Please employ the following in the patch subject line,
where appropriate:
<br />
<br />
<ul>
<li>
<strong>ffix</strong>: Formatting fix.
</li>
<li>
<strong>wfix</strong>: Minor wording fix.
</li>
<li>
<strong>tfix</strong>: Typo fix.
</li>
<li>
<strong>srcfix</strong>: Change to manual page source that
doesn't affect formatted output.
</li>
</ul>
<br />
Obviously, there's some overlap between the above cases;
just choose the one that you think fits best.
Using this scheme, a patch's subject line might look like:
<pre>
[patch] tcp.7: tfix</pre>
</li>
<li>
<strong>Some general tips</strong> on how to make life easier
for the maintainers:
<br>
<br>
</li>
<ul>
<li>
<strong>Send logically separate patches</strong> (e.g., for unrelated pages,
or for logically separate issues in the same page)
as separate mails.
<br>
<br>
</li>
<li>
<strong>Patches that contain correctly formatted
<em>groff</em> are preferred</strong>.
The basics of
<em>groff</em>
are pretty simple, and you can probably learn as much as you need
by just looking at the source of the page to be patched;
for more information, take a look at the
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/groff_man.7.html">groff_man(7)</a></span>,
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/groff_man_style.7.html">groff_man_style(7)</a></span>,
and
<span class="man-page"><a href="https://man7.org/linux/man-pages/man7/man-pages.7.html">man-pages(7)</a></span>
manual pages.
If you are uncertain of
<em>groff</em>,
then send a patch that uses some plain text.
<br>
<br>
</li>
<li>
<strong>Make patches against the latest version of the manual page</strong>.
For information on downloading the latest tarball, or pulling from the
<em>man-pages</em>
<a href="https://git-scm.com/">Git</a> repository, see the
<a href="download.html">download</a> page.
<blockquote>
If the manual page that you want to patch is not in the tarball or
Git repository,
that's because it comes from a package other than <em>man-pages</em>;
in that case, you should look
<a href="man_pages_other.html">here</a>.
</blockquote>
</li>
<li>
<strong>Send patches in
<span class="cmd">diff -u</span>
format</strong>; inline inside the mail message
is usually best.
If you're worried about your mailer breaking the patch,
then send it both inline and as an attachment.
Since the
<em>man-pages</em>
project
uses Git, you may find it useful to employ
<span class="cmd">git-send-email</span>
or
<span class="cmd">git-format-patch</span>.
<br>
<br>
</li>
</ul>
<!--
<li>
If editing a page, and you find one or two white spaces at the end
of an existing line, <strong>don't</strong> bother removing them.
The reason is that in a
<span class="cmd">diff -u</span>
patch this will make it look like there is a
change when in fact nothing has changed.
In most cases, these extra white spaces do no harm,
so just leave them be.
</li>
-->
<li>
Some <strong>things that you don't need to do</strong>:
<br>
<br>
</li>
<ul>
<li>
Don't try to patch the COLOPHON section of a page in
one of the release tarballs. That text is autogenerated
as part of the release process.
<br>
<br>
</li>
<li>
You don't need to update the page timestamp (".TH" line);
the project release scripts do that automatically.
</li>
</ul>
</ul>
<!--BEGIN-STATCOUNTER-->
<!-- SITETRACKING.linux_man-pages -->
<!-- Start of StatCounter Code -->
<script type="text/javascript">
var sc_project=5618989;
var sc_invisible=1;
var sc_partition=60;
var sc_click_stat=1;
var sc_security="4f8507d7";
</script>
<script type="text/javascript"
src="https://www.statcounter.com/counter/counter.js"></script><noscript><div
class="statcounter"><a title="customisable counter"
href="https://www.statcounter.com/free_hit_counter.html"
target="_blank"><img class="statcounter"
src="https://c.statcounter.com/5618989/0/4f8507d7/1/" alt="customisable
counter" ></a></div></noscript>
<!-- End of StatCounter Code -->
<!--END-STATCOUNTER-->
</body>
</html>
|
