blob: 393d7810e348aef826102e13295b6af5918daec2 [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>
TODO list for the Linux man-pages project
</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> |
<a href="./patches.html">patches</a> |
<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>TODO list for the Linux <em>man-pages</em> project</h1>
<p>
There are many things that might or should be done in the future
for <em>man-pages</em>.
This page describes a few of them.
Help with, or opinions about, these ideas is welcome.
</p>
<ul>
<li>
<a href="#POSIX.1_2008_pages">Publish the next
revision of the POSIX.1 pages</a>
</li>
<li>
<a href="#migrate_to_kernel_source">Migrate <em>man-pages</em>
into the kernel source tree (?)</a>
</li>
<li>
<a href="#new_markup">Design and adopt a new mark-up language (?)</a>
</li>
<li>
<a href="#global_ffix">Global formatting fixes</a>
</li>
<li>
<a href="#style_guide">Devise or adopt a style guide</a>
</li>
</ul>
<hr>
<a name="POSIX.1_2008_pages"></a>
<h2>Publish the next revision of the POSIX.1 pages</h2>
<p>
<em>man-pages</em> currently provides (as a separate package) pages from the
POSIX.1 standard, in Sections
0p (<em>Header Files</em>),
1p (<em>Commands</em>), and
3p (<em>Functions</em>).
These pages are derived from the 2001 version of POSIX.1.
</p>
<p>
A revision of POSIX.1 appeared in 2008.
We should ask once more for permission to
redistribute the new version of the pages.
</p>
<p>
A few formatting fixes will need to repeated for the new version of the pages,
including at least the following:
</p>
<ul>
<li>
Convert the POSIX.1 text to man-pages mark-up.
</li>
<li>
Add 0p/1p/3p to the TH line.
</li>
<li>
Add the PROLOG to the pages.
</li>
<li>
Clean up any white space issues that may be present.
</li>
</ul>
<p>
Status: completed in January 2014 (publication of
the POSIX.1-2013 pages).
</p>
<hr>
<a name="migrate_to_kernel_source"></a>
<h2>Migrate <em>man-pages</em> into the kernel source tree (?)</h2>
<p>
This idea has been floated by a few people.
There are some advantages:
</p>
<ul>
<li>
It might encourage kernel developers to work on
man pages by placing them in the same location as the kernel source code.
<br>
<br>
</li>
<li>
Kernel source code patches changing the behavior of kernel-userland
interfaces could include patches to the corresponding
man page text, and thus documentation patches could flow up the
maintainer chain in the usual fashion.
</li>
</ul>
<p>
There are also some disadvantages:
</p>
<ul>
<li>
The split between system calls and library functions is not
clear cut from the point of view of the userland programmer.
Sometimes, glibc wrappers do some extra work before invoking
the underlying system call.
Currently, the section 2 pages document the behavior of the
glibc wrapper, which may be different from the underlying system call,
and attempt (i.e., it's the goal, but not all pages do this well)
to include NOTES that describe differences in the
underlying system call.
(For example, see the "C library/kernel ABI differences" in the
<a href="https://man7.org/linux/man-pages//man2/select.2.html#NOTES">NOTES
section of <em>select(2)</em></a>.)
In addition, the man pages for system calls document
other user space details, such as header file requirements,
feature test macro requirements for glibc,
thread-safety (under the ATTRIBUTES section),
<br>
<br>
</li>
One way to address this would be to truly separate the system call and
glibc wrapper information into two separate pages, one in Section 2,
the other in Section 3.
But this would require one of the following approaches,
each of which has its problems:
<br>
<br>
</li>
<ul>
<li>
Document the pure system call in a Section 2 page, and then document
the differences provided by the glibc wrapper in a corresponding
Section 3 page.
The problem is that this would require userland programmers
(the main audience of the pages)
to look at two separate pages to get the information they require.
<br>
<br>
</li>
<li>
Document the pure system call in a Section 2 page, and
then document the complete behavior of the glibc wrapper
in Section 3, repeating material from the
Section 2 page as appropriate.
The problem here is redundancy: any changes in the Section
2 page would need to be carried through to the Section 3 page;
inevitably, inconsistencies will arise.
<blockquote>
<em>Note:</em> I am doubtful that the problem noted in
the above point could be resolved
via some "include" mechanism that includes relevant
pieces from the Section 2 page into the Section 3 page.
I think that would make the man page source files more difficult
to work with, and would likely be error-prone in practice
(because the producers of the "include" mark-up (man2) would
be separate from the consumers of that mark-up (man3)).
</blockquote>
</li>
</ul>
And of course it's worth noting that implementing either of
the above approaches would be a significant piece of work.
<br>
<br>
<li>
Many pages in Section 3 and in Sections 5 and 7 relate
purely to glibc.
If those pages are not to be migrated into the kernel source tree
(it makes little sense to do that), then
they should be split out into a separate package.
This raises several issues:
<br>
<br>
<ul>
<li>
Where should the "glibc" pages be hosted?
Apparently not with glibc, which favors <em>info</em>
pages (and it's worth noting that the <em>man-pages</em>
project often does a better job of documenting
the glibc interfaces).
<br>
<br>
</li>
<li>
Splitting the manual pages into two separate packages is
a significant piece of work. It's not always obvious which
package a particular page would belong to. Many pages
contain content that would relate to both packages.
(Do we split those pages into separate pages in the
two packages?
That's a big task.)
<br>
<br>
</li>
<li>
From a maintenance point of view,
maintaining two separate (but at times quite closely related)
man page packages would be a little less comfortable
than a single unified package.
</li>
</ul>
</li>
</ul>
<p>
And there are some other points, which, while not exactly disadvantages,
should be kept in mind when considering any change away from
the approach currently employed in <em>man-pages</em>:
</p>
<ul>
<li>
<em>man-pages</em> maintains historical information on interfaces.
That is, each man page documents not just the the latest kernel
(or glibc) implementation, but also changes in the interface over time.
Such information is of course important for userland programmers.
<br>
<br>
</li>
<li>
Sometimes, a man page relates to multiple underlying system calls.
For example, there have over time been many system calls that
correspond to the
<a href="https://man7.org/linux/man-pages/man2/stat.2.html">stat(2)</a>
manual page.
Other examples are the Section 2 pages for the sockets API and
the System V IPC APIs;
for both of those APIs, there are several Section 2 pages,
but (on most architectures), only one multiplexed system call
(respectively
<a href="https://man7.org/linux/man-pages/man2/ipc.2.html">ipc(2)</a>
and
<a href="https://man7.org/linux/man-pages/man2/socketcall.2.html">socketcall(2)</a>).
</li>
</ul>
<p>
Status:
</p>
<ul>
<li>
In my opinion, the disadvantages outweigh the advantages.
Furthermore, making the necessary changes would entail significant
time (which I don't have), and it's unproven whether the claimed
benefits would be borne out in practice (the state of
much of the material in the kernel
<span class="pathname">Documentation</span> directory
does not give grounds for optimism).
But I'm open to hearing further ideas,
and don't discount the possibility of doing
something about this in the future.
<br>
<br>
</li>
<li>
Here's an alternative idea.
Employ a couple of patch tags in the style of
"<span class="const">Signed-off-by:</span>".
One of these could be (say)
"<span class="const">ABI-changes-noted-by:</span>", indicating
that someone has noted that this patch changes the API/ABI.
The other would be (say)
"<span class="const">ABI-changes-doc-acked-by:</span>",
an indication from the appropriate documentation maintainer
that the ABI changes have been documented in
<em>man-pages</em> (or elsewhere if appropriate);
details of the actual documentation could be included elsewhere
in the patch's log message.
</li>
</ul>
<hr>
<a name="new_markup"></a>
<h2>Design and adopt a new mark-up language (?)</h2>
<p>
Currently, the pages in <em>man-pages</em> are created with
<em>groff</em>,
using one of two macro packages:
<em>man</em>, or the BSD derived <em>mdoc</em>.
(The vast majority of pages in
<em>man-pages</em>
employ the <em>man</em> macro package.)
Neither macro package is optimal, since they
don't encode sufficient semantic detail about the elements of a page.
(This is especially true of the <em>man</em> macro package.)
</p>
<p>
What is perhaps required is a new mark-up language (probably some form
of docbook) that:
</p>
<ul>
<li>
is unintrusive: the raw page source should remain very readable
</li>
<li>
applies mark-up by function, not by effect
</li>
<li>
can be easily processed to generate the present <em>nroff</em> from it
</li>
<li>
can be easily processed to generate HTML from it
</li>
<li>
is simple to learn and use
</li>
</ul>
<p>
And of course, the existing pages would need to be converted to
the new format.
</p>
<p>
Status: too big a job to seriously entertain at the moment.
(Since the kernel documentation's moce to Sphinx,
that tool is the obvious choice to consider for this task.)
</p>
<hr>
<a name="global_ffix"></a>
<h2>Global formatting fixes</h2>
<p>
There are various global formatting fixes that should be made
(or at least considered):
</p>
<ul>
<li>
Blank lines in natural language text in the page sources
should be replaced by .PP or .IP directives.
This produces better PostScript and PDF output,
since blank lines generate a large vertical space.
(The problem can be seen by using
<span class="func">gs(1)</span> to view the
PostScript output produced by
<span class="const">man -Tps</a>.)
</li>
<li>
Consider using the .EX/.EE macros around
code samples and shell scripts,
to have code rendered in a fixed-width font
for PostScript/PDF output.
</li>
</ul>
<hr>
<a name="style_guide"></a>
<h2>Devise or adopt a style guide</h2>
<p>
Because the pages in
<em>man-pages</em>
have been produced by many authors, there was much inconsistency
in spelling, layout, terminology, and so on.
During the course of the 2.xx and 3.xx releases there has been quite a lot
of work done to achieve greater consistency
(see for example the "Global changes" in releases
<a href="changelog.html#release_2.07">2.07</a>,
<a href="changelog.html#release_2.10">2.10</a>,
<a href="changelog.html#release_2.13">2.13</a>,
<a href="changelog.html#release_2.21">2.21</a>,
<a href="changelog.html#release_2.38">2.38</a>,
<a href="changelog.html#release_2.44">2.44</a>,
<a href="changelog.html#release_2.46">2.46</a>,
<a href="changelog.html#release_2.47">2.47</a>,
<a href="changelog.html#release_2.48">2.48</a>,
<a href="changelog.html#release_2.51">2.51</a>,
<a href="changelog.html#release_2.52">2.52</a>,
<a href="changelog.html#release_2.53">2.53</a>,
<a href="changelog.html#release_2.54">2.54</a>,
<a href="changelog.html#release_2.56">2.56</a>,
<a href="changelog.html#release_2.59">2.59</a>,
<a href="changelog.html#release_2.60">2.60</a>,
<a href="changelog.html#release_2.61">2.61</a>,
<a href="changelog.html#release_2.62">2.62</a>,
<a href="changelog.html#release_2.64">2.64</a>,
<a href="changelog.html#release_2.65">2.65</a>,
<a href="changelog.html#release_2.67">2.67</a>,
<a href="changelog.html#release_2.69">2.69</a>,
<a href="changelog.html#release_2.70">2.70</a>,
<a href="changelog.html#release_2.71">2.71</a>,
<a href="changelog.html#release_2.72">2.72</a>,
<a href="changelog.html#release_2.74">2.74</a>,
<a href="changelog.html#release_2.75">2.75</a>,
<a href="changelog.html#release_2.80">2.80</a>,
<a href="changelog.html#release_3.00">3.00</a>,
<a href="changelog.html#release_3.01">3.01</a>,
<a href="changelog.html#release_3.04">3.04</a>,
<a href="changelog.html#release_3.12">3.12</a>,
<a href="changelog.html#release_3.19">3.19</a>,
<a href="changelog.html#release_3.20">3.20</a>,
<a href="changelog.html#release_3.24">3.24</a>,
<a href="changelog.html#release_3.27">3.27</a>,
<a href="changelog.html#release_3.29">3.29</a>,
<a href="changelog.html#release_3.30">3.30</a>,
<a href="changelog.html#release_3.35">3.35</a>,
<a href="changelog.html#release_3.42">3.42</a>,
<a href="changelog.html#release_3.43">3.43</a>,
<a href="changelog.html#release_3.44">3.44</a>,
<a href="changelog.html#release_3.48">3.48</a>,
<a href="changelog.html#release_3.49">3.49</a>,
<a href="changelog.html#release_3.56">3.56</a>,
<a href="changelog.html#release_3.59">3.59</a>,
and
<a href="changelog.html#release_4.05">4.05</a>),
but there is still more work to be done.
To guide that work, as well as authors of future pages,
<em>man-pages</em> should have (i.e., probably adopt)
a style guide.
</p>
<p>
Status:
The open question is: what existing style guide is suitable?
(In the meantime,
<span class=manpage><a href="https://man7.org/linux/man-pages/man7/man-pages.7.html">man-pages(7)</a></span>
provides guidance on some points.)
</p>
<!--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>