Outline Do manual pages matter? Background Man pages: a counter-argument Michael Kerrisk Man pages matter for kernel developers Problems maintaining man pages linux.conf.au, Sydney, 17 January 2007 How to help www.kernel.org/pub/linux/docs/manpages [email protected] The man-pages project Contents of man-pages • Project started 1993 •As at man-pages-2.44: – ~800 man pages (== ~2000 printed pages) • Documents Linux kernel-userland API… – 2: syscalls • and (GNU) C library API – 3: library functions (glibc) • Sections 2, 3, 4, 5, and 7 of manual pages –4: devices Proportion of source lines (and • Target audience: userland programmers… – 5: file formats number of source files) • and kernel developers – 7: overviews, etc man2 (224) man3 (465) man4 (25) man5 (31) man7 (61) Background Man pages: a counter-argument “Documentation is fantasy: you have Man pages matter for kernel developers to read the source code to know Problems maintaining man pages the truth.” How to help 1 Time! Reading the source doesn’t cut it •The kernel is big: • Reading the source gives the “right” answer – 2.6.19 kernel source (*.[chS]) is 7.3M lines • but… too slow (and hard, especially for • and constantly changing: userland programmers) – Typical Linux 2.6.x diff –u patch > 1M lines • We just don’t have the time… We need summaries of the code • Understanding of code must be mediated by natural language summaries • Discussions – oral + email Man pages do matter! – Take place during development – but… not so useful later • Documentation – most useful form of summary for later Why man pages matter for kernel developers Background • Publicity Man pages: a counter-argument • Identifying bugs Man pages matter for kernel developers • Better testing (reducing # of released bugs) Problems maintaining man pages • Better interface design How to help • Better interface consistency 2 Identifying bugs Testing • Software is an implementation of an intention • Problem: too many bugs in released • bug == intention – implementation interfaces • Without documentation, how do we know • Why? Insufficient testing before release whether implementation matches intention? • And how can we test? Documentation and Testing Testing – example 1 • Documentation can help reduce bugs inotify • Evidence: the process can work in reverse… • File change notification API • Appeared in kernel 2.6.13 • 2.6.16-rc timeframe, I wrote inotify(7) •Testing: IN_ONESHOT had never worked • Bug reported; fixed for 2.6.16 Testing – example 2 Testing: conclusions splice() • Documentation goes hand in hand with • transfer data between file descriptors without testing going through user space • Documentation broadens range of testers • Appeared in kernel 2.6.17 • Testers can determine if implementation == • Simple test programs easily caused hangs intention • Bug reported; fixed for 2.6.18 • Good, early documentation Æ more & earlier testing Æ fewer released bugs 3 Interface design When interface design goes wrong • It’s hard to design a good programming dnotify (kernel 2.4; file change notification) interfaces • Many problems in interface design • Getting design wrong is painful… • Problems led to replacement by inotify – Using interface is difficult, and bug-prone • But… is the problem the developer(s)? – Difficult/impossible to change design • Or the process? Interface design: man pages help Interface consistency • Writing a man page (or other doc) can help • The problem: some new interfaces are with interface design inconsistent with existing similar interfaces • Writing documentation leads to self-review by • Man pages can be used as a reference when implementer(s) designing new interfaces • Documentation broadens audience who can understand and critique design Interface consistency: right Interface consistency: wrong (1) mbind(MPOL_MF_MOVE_ALL) • Various memory-related syscalls specify a • NUMA memory binding interface start address + a length • Requires privilege (CAP_xxx) • Some APIs (e.g., mprotect(start, length, ...)): • Initial (-rc) implementation used –Require start to be multiple of page size CAP_SYS_ADMIN – Round length up to next page boundary •Readingcapabilities(7) showed that existing • Some other APIs (e.g., mlock(start, length)): related APIs used CAP_SYS_NICE – Round start down to page size – Round length up to next page boundary • Final implementation used CAP_SYS_NICE – mlock(4000, 6000) affects bytes 0..12287 4 Interface consistency: wrong (2) remap_file_pages(start, length, ...): Background • Why settle just for inconsistent… Man pages: a counter-argument – Round start down to page boundary Man pages matter for kernel developers – Round length down to page boundary(!) Problems maintaining man pages • … when you can also have bizarre: How to help – What address range is affected by remap_file_pages(4000, 6000, ...) ? Problems maintaining man-pages • Much to do; too few people Background • Many man pages yet to be written Man pages: a counter-argument • Many existing man pages are stale Man pages are useful for kernel developers • Kernel developers have much valuable Problems maintaining man pages knowledge, but are largely absent How to help • How to know if an interface has changed? • How to know if a man page is broken? How to help Helping: anyone • Just about anyone can help •Read HOWTOHELP in man-pages tarball • Kernel developers would benefit by helping – List of missing pages • How companies could help – How to obtain list of FIXMEs – Tips on how to help in the most helpful way • Latest tarball at: http://www.kernel.org/pub/linux/docs/manpages 5 Helping: kernel developers Helping: kernel developers • Adding/changing an interface?… • System call man pages belong in man-pages, • Write/update the manual page! not separate tarballs • Can’t bear messing with groff? • Many virtues in a consolidated set of man – Submit plain text! pages: • Please provide test programs… – Formatting consistency – Single known address for man pages patches – Distributors know where to find manual page – Consistent interfaces… Helping: kernel developers A proposal for kernel developers “This [part of the] interface shouldn’t be documented, • Create and enforce a policy that requires because userland shouldn’t be using it [it’s only intended interface changes to be accompanied by for use in libraries].” documentation and test programs • Library developers are in same position as everyone else •“no documentation” doesn’t always mean “don’t use this” • Best approach: document interface with warning about usage Before saying no… Helping: companies/organisations • Consider that good documentation can help • Fund a man-pages maintainer prevent: – Write/update pages – Poorly designed/inconsistent interfaces –Vet patches – Bugs in new and changed interfaces – Test new interfaces • Look at long list of FIXMEs and missing pages – Track standards work (POSIX.1-200x/SUSv4 and beyond) • There are kernel coding standards; why not documentation (and testing) standards? – Write/choose a style guide – Maintain a website 6 [email protected] Michael Kerrisk Thanks! www.kernel.org/pub/linux/docs/manpages 7.