From ebe423512e657c6a42d4fa8d0a786d9179ca173b Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 30 Nov 2005 13:33:58 +0000 Subject: [PATCH] Doc describing how to help with with man page maintenance. --- HOWTOHELP | 333 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 333 insertions(+) create mode 100644 HOWTOHELP diff --git a/HOWTOHELP b/HOWTOHELP new file mode 100644 index 000000000..e21159792 --- /dev/null +++ b/HOWTOHELP @@ -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 + + Maintainer of getopt: Frodo Looijaard + Maintainer of simpleinit: Richard Gooch + +(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()