Man pages review

-as of Fri Apr 1 22:04:58 EST 2005-

This page is part of the Plan 9 Documentation Task Force

The plan is to review every man page (see list below) for errors and disagreements with current implementations of what they document. Quite often options have been added over time without updating the manual page. Also check if the information printed by usage() functions is accurate.

Getting the documentation accurate again is the primary goal. Do not produce large diffs for simple rewording (you might unnecessarily remove the original authors style).

Some scripts related to manual page checking can be found in /sys/lib/man. Checkman.awk is the most useful one (XXX should merge plan9ports version back into plan9). Make sure you have read man(6). Finally, you should check if there is a plan9port version of the manual page and keep them in sync (the plan9ports may be more up to date).

PROCEDURE:

  • Select a man page from the list.
  • Read it carefully looking for any writing errors, inconsistencies or serious ambiguities.
  • Review relevant source: for commands check at least that options are in the code and seem to do what is documented and that also the usage message is correct; for libraries check at least that function definitions match the man page.
  • Test: actually test that every option behaves as documented; for libraries write test cases and make sure they run properly.
  • If no errors or problems are found update the man page entry with "VERIFIED", date and your name.
  • If any errors are found, submit a fix as described below.
  • If you are unsure about something (eg., if implementation and documentation don't agree and it's not clear which is right), email 9fans about it and add to the entry: "CLARIFY", the subject of your email in parenthesis, date and name.

SUBMITING MAN PAGE FIXES

(Probably we should document clearly how to write test cases for libraries and maybe commands and file systems so we can build a set of test cases that can be run easily, a testing framework for that will probably be needed, and a place to store it, probably in sources)

SECTION 1: COMMANDS

SECTION 2: SYSTEM AND LIBRARY CALLS

SECTION 3: DEVICES

SECTION 4: FILE SERVERS

SECTION 5: PLAN 9 FILE PROTOCOL, 9P

SECTION 6: FILE FORMATS, MISC

SECTION 7: DATABASES

SECTION 8: SYSTEM ADMINISTRATION

This is the snipet used to generate the list of man pages: 

for ( i in ?) {
	echo
	echo SECTION $i
	echo
	cd $i 
	ls|grep -v INDEX| sed -e 's/$/('^$i^')/' -e 's/^/ *	/'
	cd ..
}

Current Page - Last modified Fri Apr 1 22:04:58 EST 2005
Powered by Plan 9 About this Wiki