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 .. #! } #