blob: 52e68c30faa410bccebb8a80f9cc797182308cf7 [file] [log] [blame]
<!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>: &nbsp;
<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>
&nbsp; || &nbsp;
<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">mtk.manpages@gmail.com</span> in "To:".
(Please do <strong>not</strong> CC my
<span class="email">@man7.org</span> email address.)
</li>
<li>
Put <span class="email">linux-man@vger.kernel.org</span> into "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>
</ul>
<p>
<strong>The above is the minimum needed to ensure that
there's some chance I'll see the patch.</strong>
(If you did that, and I do not respond, then ping the mail thread,
"replying to all".
Unfortunately, I get more mail than I can sometimes deal with,
and things do get lost.)
</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>,
I use 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>
<li>
<strong>spfix</strong>: Spelling fix.
</li>
<li>
<strong>wsfix</strong>: White-space fix.
</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 my life easier:
<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>
In the body of the mail message,
<strong>identify the
<em>man-pages</em>
version</strong> against which the patch applies.
<br>
<br>
</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).
My 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>