Re: man pages
>From teg@redhat.com Sun Jul 22 22:23:12 2001
>> A man page is the default dodumentation. Any other documentation is optional.
>> Any program must have a man page that will describe all functions and all
>> options.
>This approach is not suffient. While you can describe "ls" properly in
>a manpage, it's not a valid option for bigger applications: emacs,
>oracle, postgresql, kylix, sim city 3k etc.
OK, you are right, there are a few execptions. But in any case, the man page
should be present and describe all options, all used environent vars, all
used files and give an overview about what the program does.
I just wanted to be a bit agressive to sharpen the view...
For those who did not listen to a talk of Steve Bourne about man pages,
here is the reason why there are man pages for all UNIX programs.
In former days, when all offocial binaries have been in /bin and /usr/bin was
carrying the programs of nice users who tought that they were of general interest,
Steve Bourne wrote a cron srcipt that each night checked for new or modified
binaries in /usr/bin. If there was no man page or the man page was not as new
as the binary, the binary was removed.
Now let us see what is in the additional UNIX documentation books:
/*--------------------------------------------------------------------------*/
doc/misc:
berknet diskperf kchanges.4.1 px sdb uchanges.4.1 ukchanges.4.0
ctour gprof kchanges.4.2 regen sysperf uchanges.4.2
doc/ps1:
00.contents 03.f77io 06.sysman 09.lint 12.make 15.yacc 18.curses
01.Clang 04.pascal 07.ipctut 10.adb 13.rcs 16.lex Title
02.f77 05.as 08.ipc 11.dbx 14.sccs 17.m4
doc/ps2:
00.contents 02.summary 04.implement 06.efl 08.ratfor 10.ingres
01.cacm 03.uprog 05.iosys 07.fp 09.lisp Title
doc/run:
Ind.ia Ind.ib Ind.ic REFS tmac.sU
doc/smm:
00.contents 04.quotas 09.uucpimpl 13.kchanges 17.security 21.uucpnet
01.setup 06.lpd 10.newsop 14.fastfs 18.password 22.timed
02.config 07.sendmailop 11.named 15.net 19.porttour Title
03.kdebug 08.timedop 12.uchanges 16.sendmail 20.termdesc
doc/usd:
00.contents 04.csh 08.mh 12.edtut 16.ex 20.msmacros 24.troff 28.tbl 32.diction
01.begin 05.dc 09.newsread 13.edadv 17.jove 21.msdiffs 25.trofftut 29.refer 33.rogue
02.learn 06.bc 10.etiq 14.edit 18.sed 22.memacros 26.eqn 30.invert 34.trek
03.shell 07.Mail 11.notes 15.vi 19.awk 23.meref 27.eqnguide 31.bib Title
/*--------------------------------------------------------------------------*/
>A manpage should cover arguments for the program - covering the entire
>behaviour is way beyond the scope of a manpage.
But the fact that ~ 25% of the programs in a Linux distribution has no man page
at all it not good.
>> Programs that don't have one or where it is incomplete should not be a part
>> of the base distribution.
>Not a valid option for complex apps.
Let's make an example:
The fact that diff, cmp, tar have no man page at all is not acceptable.
Jörg
EMail:joerg@schily.isdn.cs.tu-berlin.de (home) Jörg Schilling D-13353 Berlin
js@cs.tu-berlin.de (uni) If you don't have iso-8859-1
schilling@fokus.gmd.de (work) chars I am J"org Schilling
URL: http://www.fokus.gmd.de/usr/schilling ftp://ftp.fokus.gmd.de/pub/unix
Reply to: