mirror of https://github.com/mkerrisk/man-pages
Doc describing how to help with with man page maintenance.
This commit is contained in:
Michael Kerrisk
parent
500d7ebccb
commit
ebe423512e
|
|
@ -0,0 +1,333 @@
|
|||
The following notes are written for people who want to help with
|
||||
maintaining manual pages in the man-pages package.
|
||||
|
||||
|
||||
THINGS YOU CAN DO TO HELP
|
||||
=========================
|
||||
|
||||
You can help in the following ways:
|
||||
|
||||
-- sending in bug reports about problems in existing pages;
|
||||
(An alternative is to report the bug in one of the
|
||||
distribution-specific Bugzilla facilities, if that facility
|
||||
provides a mechanism to automatically forward bug reports
|
||||
to me. Currently, I am registered to receive man-page bug
|
||||
reports from the Debian bugzilla, but if other distributions
|
||||
provide a similar facility I may get myself registered for
|
||||
those; let me know.)
|
||||
|
||||
-- writing patches that improve existing pages (see below);
|
||||
|
||||
-- writing new pages (see below for a list of currently missing pages);
|
||||
|
||||
-- grepping for the string FIXME in existing pages and writing a
|
||||
suitable patch (see below); and
|
||||
|
||||
-- suggesting improvements to this document.
|
||||
|
||||
|
||||
HOW TO CONTRIBUTE PATCHES
|
||||
=========================
|
||||
|
||||
Patches should be sent to Michael Kerrisk, mtk-manpages@gmx.net.
|
||||
When you submit a patch, please note the following:
|
||||
|
||||
-- Submit a patch against the current version of the page. The current
|
||||
version of the man-pages package can be downloaded from
|
||||
|
||||
ftp://ftp.win.tue.nl/pub/linux-local/manpages
|
||||
|
||||
or:
|
||||
|
||||
ftp://ftp.kernel.org/pub/linux/docs/manpages
|
||||
or mirrors: ftp://ftp.XX.kernel.org/pub/linux/docs/manpages
|
||||
|
||||
-- Let me know how you obtained the information: was it by reading (or
|
||||
writing) the relevant kernel or (g)libc source code; by writing a test
|
||||
program (send it to me, if you want, and if it is clear and simple
|
||||
to use); from other documentation; from a mailing list or Usenet
|
||||
thread (please provide a URL if possible).
|
||||
|
||||
-- Send patches in "diff -u" format, inline inside the mail message
|
||||
is usually best; if it is a very long patch then send it both inline
|
||||
and as an attachment.
|
||||
|
||||
-- Send logically separate patches (e.g., for unrelated pages) as
|
||||
separate mails.
|
||||
|
||||
|
||||
MANUAL PAGES IN OTHER PACKAGES
|
||||
==============================
|
||||
|
||||
Not all Linux manual pages are part of the man-pages set. In particular,
|
||||
most Section 1 and 8 pages come as part of some other package.
|
||||
The easiest way to determine which pages are part of the man-pages package
|
||||
is to download the latest tarball, and see if the page is present.
|
||||
|
||||
If you want to submit a patch for a manual page that comes from another
|
||||
source, then you need to work out where the manual page comes from
|
||||
(i.e., which package) and who the maintainer of that manual page is.
|
||||
|
||||
On an RPM-based distribution, you can do the following to find out
|
||||
which package owns a particular file. For example, suppose we want
|
||||
to find out who maintains the fstab(5) manual page:
|
||||
|
||||
$ man -w fstab
|
||||
/usr/share/man/man5/fstab.5.gz
|
||||
$ rpm -qf /usr/share/man/man5/fstab.5.gz
|
||||
util-linux-2.12q-7.2
|
||||
|
||||
If we then look in the MAINTAINERS file in the util-linux
|
||||
package, we see:
|
||||
|
||||
Maintainer: Adrian Bunk <bunk@stusta.de>
|
||||
|
||||
Maintainer of getopt: Frodo Looijaard <frodol@dds.nl>
|
||||
Maintainer of simpleinit: Richard Gooch <rgooch@atnf.csiro.au>
|
||||
|
||||
(FIXME: add instructions for doing the equivalent of the above on
|
||||
non-RPM-based distributions.)
|
||||
|
||||
|
||||
REPAIRING PAGES MARKED "FIXME"
|
||||
==============================
|
||||
|
||||
Grepping the source of the manual pages will show various places where
|
||||
pages are marked with the string FIXME. This usually indicates that
|
||||
someone has noticed that some information on the page is incorrect
|
||||
or incomplete, but has not had the time/knowledge to fix problem.
|
||||
(Sometimes a FIXME relates to a kernel or glibc bug report that is
|
||||
awaiting resolution, and it may be sufficient to check if the bug
|
||||
has been resolved and then provide a suitable write-up on the page.)
|
||||
|
||||
If you know how to fix the problem, then please send a patch.
|
||||
However, note that many of the FIXME markings are associated with
|
||||
problems that are quite difficult: you need to ensure that you are
|
||||
knowledgeable on the relevant point(s), or you need to be willing to
|
||||
invest the time to become knowledgeable (by reading kernel or
|
||||
[g]libc source files and/or writing suitable ttes programs).
|
||||
|
||||
|
||||
MISSING MANUAL PAGES
|
||||
====================
|
||||
|
||||
Below is a list of pages that I would like to see in the man-pages set.
|
||||
If you are thinking of writing one or more of these pages, then:
|
||||
|
||||
-- It might be wise to let me know in advance, just in case someone
|
||||
else has started working on the page, or a related page. I may
|
||||
also be able point you at useful sources of information for
|
||||
the manual page.
|
||||
|
||||
-- You need to have a reasonably high degree of understanding of the
|
||||
topic, or be prepared to invest the time (e.g., reading source code,
|
||||
writing test programs) to gain that understanding.
|
||||
|
||||
-- Follow the existing formatting conventions for manual pages.
|
||||
Some information about formatting is provided in the "man(7)"
|
||||
manual page. As an example of how these conventions are employed,
|
||||
have a look at the "fcntl(2)" manual page and read its source file
|
||||
(man2/fcntl.2).
|
||||
|
||||
-- The page must be submitted under some sort of license that permits
|
||||
the page to be freely redistributed and modified. Include that license
|
||||
in the source code of the manual page. Possible licenses include the
|
||||
GPL, the BSD license, or a range of other licenses, some of which can
|
||||
be seen in existing manual pages.
|
||||
|
||||
-- You may find it useful to check the information in your page
|
||||
against the specifications in SUSv3/POSIX.1-2001
|
||||
(http://www.opengroup.org/onlinepubs/009695399/toc.htm) or against
|
||||
manual pages on other implementations, but do not not violate the
|
||||
copyright on those publications by copying text from them.
|
||||
|
||||
-- The GNU C library documents many of the functions that it provides
|
||||
using info(1). If you are thinking of writing a manual page for
|
||||
a function that is already documented in info(1) format, then
|
||||
ideally this page needs to present new or different information from
|
||||
that provided by the info(1) page (for example, historical
|
||||
information about how the function has changed across various glibc
|
||||
versions, or variations in operation across C libraries; such
|
||||
information is often not present in info pages). (An alternative to
|
||||
consider is submitting a patch to the maintainers of the glibc
|
||||
documentation, if that is more appropriate.)
|
||||
|
||||
|
||||
System Calls
|
||||
------------
|
||||
|
||||
add_key(2)
|
||||
keyctl(2)
|
||||
request_key(2)
|
||||
|
||||
inotify_add_watch(2)
|
||||
inotify_init(2)
|
||||
inotify_rm_watch(2)
|
||||
|
||||
delete_module(2)
|
||||
init_module(2)
|
||||
create_module(2) (Present up to and including kernel 2.4, absent in 2.6)
|
||||
query_module(2) (Present up to and including kernel 2.4, absent in 2.6)
|
||||
|
||||
|
||||
ioprio_get(2) (new in kernel 2.6.13)
|
||||
ioprio_set(2) (new in kernel 2.6.13)
|
||||
|
||||
mq_getsetattr(2)
|
||||
mq_notify(2)
|
||||
mq_open(2)
|
||||
mq_receive() / mq_timedreceive(2)
|
||||
mq_send() / mq_timedsend(2)
|
||||
mq_unlink(2)
|
||||
|
||||
Manual pages might also be useful for the following system calls:
|
||||
|
||||
get_kernel_syms(2) (Present up to and including kernel 2.4, absent in 2.6)
|
||||
restart_syscall(2) (new in 2.6)
|
||||
set_zone_reclaim(2) (new in kernel 2.6.13)
|
||||
sys_kexec_load(2) (new in kernel 2.6.13)
|
||||
|
||||
|
||||
/sys file system
|
||||
----------------
|
||||
|
||||
There is no man page for the /sys file system: there probably should
|
||||
be a sys.5 page similar to proc.5. The kernel source file
|
||||
Documentation/filesystems/sysfs.txt provides a starting point for
|
||||
this page.
|
||||
|
||||
|
||||
Library Functions
|
||||
-----------------
|
||||
|
||||
(See a further list of missing pages in the "undocument(3)" manual page.)
|
||||
|
||||
adjtime(3)
|
||||
readdir_r(3) (probably as additional text in readdir.3)
|
||||
sigstack(3)
|
||||
sigwait(3)
|
||||
|
||||
The POSIX semaphores API: sem_close(3), sem_destroy(3),
|
||||
sem_getvalue(3), sem_init(3), sem_open(3), sem_post(3),
|
||||
sem_timedwait(3), sem_trywait(3), sem_unlink(3)
|
||||
|
||||
And last, but far from least, the POSIX threads API. Note that there is
|
||||
an existing, outdated set of pages supplied with glibc that document the
|
||||
old LinuxThreads implementation. (These pages are written under a
|
||||
license that allows re-use, so some material that they contain could
|
||||
be used in new pages.) What is required is a set of pages that document
|
||||
the complete API, describing details where LinuxThreads and NPTL diverge
|
||||
from the standard. The existing pthreads(7) manual page, which gives an
|
||||
overview of Pthreads implementations on Linux, is designed as a base
|
||||
document for these manual pages. The list of required manual pages is
|
||||
long, those marked with more asterisks are probably the most desirable
|
||||
to get done first:
|
||||
|
||||
pthread_atfork() *
|
||||
pthread_attr_destroy()
|
||||
pthread_attr_getaffinity_np()
|
||||
pthread_attr_getdetachstate()
|
||||
pthread_attr_getguardsize()
|
||||
pthread_attr_getinheritsched()
|
||||
pthread_attr_getschedparam()
|
||||
pthread_attr_getschedpolicy()
|
||||
pthread_attr_getscope()
|
||||
pthread_attr_getstack()
|
||||
pthread_attr_getstackaddr()
|
||||
pthread_attr_getstacksize()
|
||||
pthread_attr_init()
|
||||
pthread_attr_setaffinity_np()
|
||||
pthread_attr_setdetachstate()
|
||||
pthread_attr_setguardsize()
|
||||
pthread_attr_setinheritsched()
|
||||
pthread_attr_setschedparam()
|
||||
pthread_attr_setschedpolicy()
|
||||
pthread_attr_setscope()
|
||||
pthread_attr_setstack()
|
||||
pthread_attr_setstackaddr()
|
||||
pthread_attr_setstacksize()
|
||||
pthread_barrierattr_destroy()
|
||||
pthread_barrierattr_getpshared()
|
||||
pthread_barrierattr_init()
|
||||
pthread_barrierattr_setpshared()
|
||||
pthread_barrier_destroy()
|
||||
pthread_barrier_init()
|
||||
pthread_barrier_wait()
|
||||
pthread_cancel() **
|
||||
pthread_cleanup_pop() **
|
||||
pthread_cleanup_pop_restore_np()
|
||||
pthread_cleanup_push() **
|
||||
pthread_cleanup_push_defer_np()
|
||||
pthread_condattr_destroy()
|
||||
pthread_condattr_getclock()
|
||||
pthread_condattr_getpshared()
|
||||
pthread_condattr_init()
|
||||
pthread_condattr_setclock()
|
||||
pthread_condattr_setpshared()
|
||||
pthread_cond_broadcast() **
|
||||
pthread_cond_destroy() **
|
||||
pthread_cond_init() **
|
||||
pthread_cond_signal() **
|
||||
pthread_cond_timedwait() **
|
||||
pthread_cond_wait() **
|
||||
pthread_create() ***
|
||||
pthread_detach() ***
|
||||
pthread_equal() ***
|
||||
pthread_exit() ***
|
||||
pthread_getaffinity_np()
|
||||
pthread_getattr_np()
|
||||
pthread_getconcurrency()
|
||||
pthread_getcpuclockid()
|
||||
pthread_getschedparam()
|
||||
pthread_getspecific() **
|
||||
pthread_join() ***
|
||||
pthread_key_create() **
|
||||
pthread_key_delete() **
|
||||
pthread_kill() *
|
||||
pthread_kill_other_threads_np()
|
||||
pthread_mutexattr_destroy()
|
||||
pthread_mutexattr_getpshared()
|
||||
pthread_mutexattr_gettype()
|
||||
pthread_mutexattr_init()
|
||||
pthread_mutexattr_setpshared()
|
||||
pthread_mutexattr_settype()
|
||||
pthread_mutex_destroy() **
|
||||
pthread_mutex_init() **
|
||||
pthread_mutex_lock() **
|
||||
pthread_mutex_timedlock() **
|
||||
pthread_mutex_trylock() **
|
||||
pthread_mutex_unlock() **
|
||||
pthread_once() **
|
||||
pthread_rwlockattr_destroy()
|
||||
pthread_rwlockattr_getkind_np()
|
||||
pthread_rwlockattr_getpshared()
|
||||
pthread_rwlockattr_init()
|
||||
pthread_rwlockattr_setkind_np()
|
||||
pthread_rwlockattr_setpshared()
|
||||
pthread_rwlock_destroy()
|
||||
pthread_rwlock_init()
|
||||
pthread_rwlock_rdlock()
|
||||
pthread_rwlock_timedrdlock()
|
||||
pthread_rwlock_timedwrlock()
|
||||
pthread_rwlock_tryrdlock()
|
||||
pthread_rwlock_trywrlock()
|
||||
pthread_rwlock_unlock()
|
||||
pthread_rwlock_wrlock()
|
||||
pthread_self() **
|
||||
pthread_setaffinity_np()
|
||||
pthread_setcancelstate()
|
||||
pthread_setcanceltype()
|
||||
pthread_setconcurrency()
|
||||
pthread_setschedparam()
|
||||
pthread_setspecific() **
|
||||
pthread_sigmask() *
|
||||
pthread_spin_destroy()
|
||||
pthread_spin_init()
|
||||
pthread_spin_lock()
|
||||
pthread_spin_trylock()
|
||||
pthread_spin_unlock()
|
||||
pthread_testcancel() **
|
||||
pthread_timedjoin_np()
|
||||
pthread_tryjoin_np()
|
||||
pthread_yield() *
|
||||
pthread_yield_np()
|
||||
Loading…
Reference in New Issue