Man pages review
D1112411098
Auriel (82.182.149.46)
#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
#
# *	Make the neccesary changes
# *	Check that they look properly with man(1), also check with man -P
#	(to see it in page(1))
# *	use Russ's dist/checkman.awk from [plan9port] against the updated
#	man page
# *	See if plan9ports have the same manual page and keep them in sync.
# *	submit the change using patch(1) and a name for the form:
#	doc-man-N-NAME-NOTE, where N is the section, NAME the man page name
#	and NOTE something descriptive about the change.
# *	update the corresponding list entry with: "PATCH(patch-name)"
#	followed by date and your name.
# *	Once the patch has been accepted, update the entry to VERIFIED
# *	If the patch is rejected and you have to submit a new version,
#	use the same name with an extra -N in the name denoting the
#	"version" of the patch.
#
#(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
#
# *	0intro(1)
# *	2a(1)
# *	2c(1)
# *	2l(1)
# *	acid(1)
# *	acme(1)
# *	ap(1)
# *	ar(1)
# *	ascii(1)
# *	awk(1)
# *	basename(1)
# *	bc(1)
# *	bind(1)
# *	bitsyload(1)
# *	bundle(1)
# *	cal(1)
# *	calendar(1)
# *	cat(1)
# *	cb(1)
# *	chgrp(1)
# *	chmod(1)
# *	cleanname(1)
# *	cmp(1)
# *	colors(1)
# *	comm(1)
# *	con(1)
# *	cp(1)
# *	cpp(1)
# *	cpu(1)
# *	crop(1)
# *	date(1)
# *	db(1)
# *	dc(1)
# *	dd(1)
# *	delkey(1)
# *	deroff(1)
# *	diff(1)
# *	doc2txt(1)
# *	doctype(1)
# *	du(1)
# *	echo(1)
# *	ed(1)
# *	emacs(1)
# *	eqn(1)
# *	expect(1)
# *	faces(1)
# *	factor(1)
# *	file(1)
# *	filter(1)
# *	fmt(1)
# *	fortune(1)
# *	freq(1)
# *	games(1)
# *	grap(1)
# *	graph(1)
# *	grep(1)
# *	gs(1)
# *	gview(1)
# *	gzip(1)
# *	hget(1)
# *	history(1)
# *	hoc(1)
# *	idiff(1)
# *	join(1)
# *	jpg(1)
# *	kbmap(1)
# *	kill(1)
# *	ktrace(1)
# *	leak(1)
# *	lens(1)
# *	lex(1)
# *	look(1)
# *	lp(1)
# *	ls(1)
# *	mail(1)
# *	man(1)
# *	marshal(1)
# *	mc(1)
# *	mk(1)
# *	mkdir(1)
# *	mlmgr(1)
# *	ms2html(1)
# *	nedmail(1)
# *	netstat(1)
# *	news(1)
# *	nm(1)
# *	ns(1)
# *	p(1)
# *	page(1)
# *	passwd(1)
# *	patch(1)
# *	pcc(1)
# *	pic(1)
# *	pipefile(1)
# *	plot(1)
# *	plumb(1)
# *	pr(1)
# *	prof(1)
# *	proof(1)
# *	ps(1)
# *	ps2pdf(1)
# *	pwd(1)
# *	rc(1)
# *	replica(1)
# *	resample(1)
# *	rio(1)
# *	rm(1)
# *	rwd(1)
# *	sam(1)
# *	secstore(1)
# *	sed(1)
# *	seq(1)
# *	size(1)
# *	sleep(1)
# *	sort(1)
# *	spell(1)
# *	spin(1)
# *	split(1)
# *	src(1)
# *	ssh(1)
# *	stop(1)
# *	strings(1)
# *	strip(1)
# *	sum(1)
# *	syscall(1)
# *	tail(1)
# *	tar(1)
# *	tbl(1)
# *	tcs(1)
# *	tee(1)
# *	tel(1)
# *	test(1)
# *	thesaurus(1)
# *	time(1)
# *	touch(1)
# *	tr(1)
# *	trace(1)
# *	troff(1)
# *	troff2html(1)
# *	tweak(1)
# *	uniq(1)
# *	units(1)
# *	uptime(1)
# *	vac(1)
# *	vi(1)
# *	vnc(1)
# *	vt(1)
# *	wc(1)
# *	who(1)
# *	xd(1)
# *	yacc(1)
# *	yesterday(1)
#
#SECTION 2: SYSTEM AND LIBRARY CALLS
#
# *	0intro(2)
# *	9p(2)
# *	9pcmdbuf(2)
# *	9pfid(2)
# *	9pfile(2)
# *	abort(2)
# *	abs(2)
# *	access(2)
# *	addpt(2)
# *	aes(2)
# *	allocimage(2)
# *	arg(2)
# *	arith3(2)
# *	assert(2)
# *	atof(2)
# *	auth(2)
# *	authsrv(2)
# *	bin(2)
# *	bind(2)
# *	bio(2)
# *	blowfish(2)
# *	brk(2)
# *	cachechars(2)
# *	chdir(2)
# *	cleanname(2)
# *	color(2)
# *	complete(2)
# *	control(2)
# *	cputime(2)
# *	ctime(2)
# *	ctype(2)
# *	debugger(2)
# *	des(2)
# *	dial(2)
# *	dirread(2)
# *	disk(2)
# *	draw(2)
# *	dsa(2)
# *	dup(2)
# *	elgamal(2)
# *	encode(2)
# *	encrypt(2)
# *	errstr(2)
# *	event(2)
# *	exec(2)
# *	exits(2)
# *	exp(2)
# *	fauth(2)
# *	fcall(2)
# *	fd2path(2)
# *	fgetc(2)
# *	flate(2)
# *	floor(2)
# *	fmtinstall(2)
# *	fopen(2)
# *	fork(2)
# *	fprintf(2)
# *	frame(2)
# *	frexp(2)
# *	fscanf(2)
# *	fversion(2)
# *	genrandom(2)
# *	getcallerpc(2)
# *	getenv(2)
# *	getfcr(2)
# *	getfields(2)
# *	getpid(2)
# *	getuser(2)
# *	getwd(2)
# *	graphics(2)
# *	html(2)
# *	httpd(2)
# *	hypot(2)
# *	intmap(2)
# *	ioproc(2)
# *	iounit(2)
# *	ip(2)
# *	isalpharune(2)
# *	keyboard(2)
# *	lock(2)
# *	mach(2)
# *	malloc(2)
# *	matrix(2)
# *	memdraw(2)
# *	memlayer(2)
# *	memory(2)
# *	mktemp(2)
# *	mouse(2)
# *	mp(2)
# *	muldiv(2)
# *	nan(2)
# *	ndb(2)
# *	notify(2)
# *	object(2)
# *	open(2)
# *	perror(2)
# *	pipe(2)
# *	plumb(2)
# *	pool(2)
# *	postnote(2)
# *	prime(2)
# *	print(2)
# *	privalloc(2)
# *	proto(2)
# *	pushssl(2)
# *	pushtls(2)
# *	qball(2)
# *	qsort(2)
# *	quaternion(2)
# *	quote(2)
# *	rand(2)
# *	rc4(2)
# *	read(2)
# *	readcolmap(2)
# *	readv(2)
# *	regexp(2)
# *	remove(2)
# *	rendezvous(2)
# *	rsa(2)
# *	rune(2)
# *	runestrcat(2)
# *	scribble(2)
# *	scsi(2)
# *	sechash(2)
# *	seek(2)
# *	segattach(2)
# *	segbrk(2)
# *	segflush(2)
# *	setjmp(2)
# *	sin(2)
# *	sinh(2)
# *	sleep(2)
# *	stat(2)
# *	strcat(2)
# *	string(2)
# *	stringsize(2)
# *	subfont(2)
# *	symbol(2)
# *	thread(2)
# *	time(2)
# *	tmpfile(2)
# *	wait(2)
# *	window(2)
#
#SECTION 3: DEVICES
#
# *	0intro(3)
# *	apm(3)
# *	arch(3)
# *	audio(3)
# *	cap(3)
# *	cons(3)
# *	draw(3)
# *	dup(3)
# *	env(3)
# *	ether(3)
# *	floppy(3)
# *	fs(3)
# *	i82365(3)
# *	ip(3)
# *	kbmap(3)
# *	kprof(3)
# *	loopback(3)
# *	lpt(3)
# *	mnt(3)
# *	mouse(3)
# *	pipe(3)
# *	pnp(3)
# *	proc(3)
# *	root(3)
# *	rtc(3)
# *	sd(3)
# *	segment(3)
# *	srv(3)
# *	ssl(3)
# *	tls(3)
# *	uart(3)
# *	usb(3)
# *	vga(3)
#
#SECTION 4: FILE SERVERS
#
# *	0intro(4)
# *	acme(4)
# *	archfs(4)
# *	cdfs(4)
# *	cfs(4)
# *	consolefs(4)
# *	dossrv(4)
# *	execnet(4)
# *	exportfs(4)
# *	ext2srv(4)
# *	factotum(4)
# *	fossil(4)
# *	fs(4)
# *	ftpfs(4)
# *	import(4)
# *	iostats(4)
# *	keyfs(4)
# *	kfs(4)
# *	lnfs(4)
# *	mntgen(4)
# *	namespace(4)
# *	nfs(4)
# *	nntpfs(4)
# *	paqfs(4)
# *	plumber(4)
# *	ramfs(4)
# *	ratfs(4)
# *	rdbfs(4)
# *	rio(4)
# *	sacfs(4)
# *	snap(4)
# *	srv(4)
# *	tapefs(4)
# *	telco(4)
# *	u9fs(4)
# *	upasfs(4)
# *	usb(4) - documented options for usbmouse, usbaudio still to go
# *	usbd(4)
# *	vacfs(4)
# *	webcookies(4)
# *	webfs(4)
# *	wikifs(4)
#
#SECTION 5: PLAN 9 FILE PROTOCOL, 9P
#
# *	0intro(5)
# *	attach(5)
# *	clunk(5)
# *	error(5)
# *	flush(5)
# *	open(5)
# *	read(5)
# *	remove(5)
# *	stat(5)
# *	version(5)
# *	walk(5)
#
#SECTION 6: FILE FORMATS, MISC
#
# *	0intro(6)
# *	a.out(6)
# *	ar(6)
# *	authsrv(6)
# *	color(6)
# *	face(6)
# *	font(6)
# *	image(6)
# *	keyboard(6)
# *	keys.who(6)
# *	man(6)
# *	map(6)
# *	mpictures(6)
# *	ms(6)
# *	namespace(6)
# *	ndb(6)
# *	plot(6)
# *	plumb(6)
# *	regexp(6)
# *	rewrite(6)
# *	smtpd(6)
# *	snap(6)
# *	thumbprint(6)
# *	users(6)
# *	utf(6)
# *	venti.conf(6)
# *	vgadb(6)
#
#SECTION 7: DATABASES
#
# *	0intro(7)
# *	astro(7)
# *	dict(7)
# *	juke(7)
# *	map(7)
# *	playlistfs(7)
# *	scat(7)
#
#SECTION 8: SYSTEM ADMINISTRATION
#
# *	0intro(8)
# *	9load(8)
# *	9pcon(8)
# *	aan(8)
# *	aliasmail(8)
# *	apm(8)
# *	auth(8)
# *	boot(8)
# *	booting(8)
# *	checkarenas(8)
# *	cpurc(8)
# *	cron(8)
# *	dhcpd(8)
# *	drawterm(8)
# *	fossilcons(8)
# *	fs(8)
# *	fsconfig(8)
# *	httpd(8)
# *	init(8)
# *	ipconfig(8)
# *	ipserv(8)
# *	kfscmd(8)
# *	listen(8)
# *	lp(8)
# *	mk9660(8)
# *	mkfs(8)
# *	mkpaqfs(8)
# *	mksacfs(8)
# *	mouse(8)
# *	na(8)
# *	ndb(8)
# *	nfsserver(8)
# *	pcmcia(8)
# *	pem(8)
# *	ping(8)
# *	plan9.ini(8)
# *	pop3(8)
# *	ppp(8)
# *	prep(8)
# *	qer(8)
# *	reboot(8)
# *	replica(8)
# *	rsa(8)
# *	scanmail(8)
# *	scuzz(8)
# *	secstore(8)
# *	securenet(8)
# *	send(8)
# *	smtp(8)
# *	snoopy(8)
# *	stats(8)
# *	stub(8)
# *	swap(8)
# *	timesync(8)
# *	tlssrv(8)
# *	trampoline(8)
# *	udpecho(8)
# *	update(8)
# *	venti(8)
# *	ventiaux(8)
# *	vga(8)
# *	newuser(8) changed to mention fossil instead of fs(8)
#	-mjl/31-03-2005
#
#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 ..
#! }
#