[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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:
berknet        diskperf       kchanges.4.1   px             sdb            uchanges.4.1   ukchanges.4.0
ctour          gprof          kchanges.4.2   regen          sysperf        uchanges.4.2

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

00.contents   02.summary    04.implement  06.efl        08.ratfor     10.ingres
01.cacm       03.uprog      05.iosys      07.fp         09.lisp       Title

Ind.ia   Ind.ib   Ind.ic   REFS     tmac.sU

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

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.


 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: