Subject:
Re: [discuss] Linux documentation
From:
Michael Kerrisk ####@####.####
Date:
23 Sep 2007 09:18:37 +0000
Message-Id: <46F62F34.8050401@gmx.net>
Steven wrote:
> "Michael Kerrisk" ####@####.#### wrote:
>
>>> How are the html man pages going ? (have i missed some news ?) Hmmm... the idea
>>> is nice, but maybe not so worthwhile considering the poor state of Linux man
>>> pages in general.
>
>> Hmmm -- I wonder what you mean. Which man pages are in such a poor state?
>
> Gnu utilities are great, and imho, more important to Gnu/Linux that Linus
> generally admits. Anyway, I was probably shooting from the hip a little ;>
Quite ;-).
> I don't like info pages,
You are not alone.
> and some man pages are out of date, but my real
> gripe is with the lack of polish and integration Linux has compared to it's
> technical finesse.
>
> As regards individual man pages (which btw, there's some attractive pages here:
> http://www.linuxmanpages.com), i guess i can't finger too many complaints. I
> don't like the way the coreutils man pages are fairly light, and most of their
> doco is in info format. The Grub boot loader is the same - no man page but
> extensive info documentation. These two packages I personally use extensively.
> (Some file utilities here: http://filerenameutils.sf.net, running lots of
> operating systems and filesystems, and having hacked Grub also.)
>
> Imho info pages are quite unreadable; bad news for any documentation. They
> make little or no use of boldness, colour, underlines or spacing, and in
> typical Gnu user-friendliness have a totally non-standard navigation system.
> Verbose paragraphs follow each other with little or no itemization.
> Annoyingly, pages won't scroll by single lines but in hard-to-follow jerks.
> Info files *do* have links... and help to reduce duplication of content.
>
> I downloaded a few of Gnu's latest utilities to check them out. (I do run
> oldish operating systems, so perhaps seeing "2004" timestamps everywhere is
> just me ;>) Looking at the latest packages for binutils-2.18, coreutils-6.9,
> findutils-4.2.31, util-linux-ng-2.13 (which appears to be a Redhat/Fedora fork
> also used by Ubuntu), here's a few comments...
>
> ---------------
>
> Mount manual page (util-linux-ng-2.13):
>
> Between releases 4.? and 5.?, FreeBSD implemented a filesystem revision which is
> only readable with Linux kernels 2.6.XX (2.6.21?). In the latest kernel doco
> (in file "ufs.txt") they mention (about mount options):
>
>> ufstype=type_of_ufs
>> UFS is a file system widely used in different operating systems.
>> ....
>> ufs2 used in FreeBSD 5.x
>
> There's no mention of this in the latest mount man page. I also had a similar
> issue with a vista created dvd. Here i'm not sure ... but there may be a new
> dvd udf filesystem standard only usable with new kernels and utils. Anyway,
> there ~is~ extensive documentation with the latest kernel docs, in a file
> "udf.txt", that isn't included in the man page.
>
> And maybe i missed something, but doesn't a date on a document generally mean
> to be the last time it was updated. The date on the latest mount man page is
> 2004-12-16. Though comparing it with my Fedora 4 man page, it has obviously
> been updated.
Yes, some man page maintainers should be better at this. Even I am not
as good as I should be.
> There's nothing really notable about this gripe... It's just symptomatic of the
> poor integration of Gnu/Linux's documentation that i'd love to see addressed.
>
> ---------------
>
> The util-linux-ng-2.13 man pages are dated as old. (I examine them with a hack
> of mine named "lman" which i've attached)
>
>> lman mount/losetup.8: ..... 2003-07-01
>> lman disk-utils/mkswap.8: ..... 25 March 1999
>> lman fdisk/fdisk.8: ..... 11 June 1998
>
> It's pretty annoying just seeing those dates, even if they're not that of last
> revision as the following timestamps indicate.
Contact the maintainers and politely point this? Or even offer to send
a patch?
>> -rw-rw-r-- 1 steven 5404 Aug 27 13:00 disk-utils/mkswap.8
>> -rw-rw-r-- 1 steven 19309 Aug 27 13:00 disk-utils/mkswap.c
>> -rw-rw-r-- 1 steven 10082 Aug 13 10:39 fdisk/fdisk.8
>> -rw-rw-r-- 1 steven 68918 Aug 13 10:39 fdisk/fdisk.c
>
> Quick inspection of the other packages shows the man pages are dated ok.
> Binutils-2.18 appear upto date. Briefly looking at findutils they seem fine:
>
>> -rw-r--r-- 1 1001 10584 Mar 31 2006 xargs.1
>> -rw-r--r-- 1 1001 30274 Mar 2 2007 xargs.c
>> -rw-r--r-- 1 1001 users 46463 Apr 15 19:04 find.1
>> -rw-r--r-- 1 1001 users 55641 Apr 1 2006 find.c
>> -rw-r--r-- 1 1001 users 8055 May 30 19:09 locate.1
>> -rw-r--r-- 1 1001 users 34059 May 28 10:17 locate.c
>
> Interestingly, coreutils makes the most use of info files, and most of the man
> pages are stubs or incomplete. The other packages i examined seem to have more
> complete man pages along side info documentation. The coreutils-6.9 source
> also includes a large html file which looks to be generated from their info
> source... It's still totally unreadable though.
>
> Coreutils are in most respects the largest package. In size, binutils.tgz is
> larger, but going by the number of programs in the path, coreutils wins.
>
>> #rpm -ql coreutils | grep /bin/ | wc -l
>> 90
>> #rpm -ql binutils | grep /bin/ | wc -l
>> 14
>
> ---------
>
> Anyway, another pet hate i have with Gnu's software is the lack of a "-?"
> option. This was the standard unix command line option for help i used at uni.
It's not a bad convention, but far from standard.
> For some reason Gnu decided to use "--help" instead. It's not only longer, but
> also a quite ungainly key sequence on an qwerty keyboard. Every time i'm
> forced to type this option my brain murmurs: "Do you want help! Beg boy" (in a
> yankee drawl). Sure this is trivial... but it's *typical*. (And i ~have~ looked
> at patching coreutils to remedy this, but it doesn't look too straight forward.)
>
> A few other issues i have with Linux's poor documentation:
>
> * I don't think there's any included documentation for the C programming
> language. It's the cornerstone of all unices but afaik there's no C reference
> included. I've spent 10 years looking... Still, it might be there ;>
We also don't have included documentation about principles of atomic
physics, electronics, fundamentals of logic, chipset design, or x86
assembler. (To make the point clear: some things must be assumed.
Seems perfectly reasonable to me assume that you will learn C elsewhere.)
> * Lack of integration of doco about Bash builtins and the like named Gnu
> utilities. Example: the "pwd" man page makes no mention of bash or the bash
> builtin pwd, which is (probably) what you're getting when you type "pwd" from
> the command line.
No there are two "pwd"s -- /bin/pwd and the "pwd" built into the shell.
> (To see what pwd actually does you need to type "help pwd").
> This may seem trivial, but the awesome bash was i think the first program Linus
> ported , and is at the heart of Linux.
>
> * Kde's shitty doco. I love Kde and Konqueror, but just wish they'd find
> someone to fix their bugs, doco and tie down their launch menus before doing
> glamorous things like making new releases.
>
> ---------
>
> Anyway, I haven't searched my Fedora 4 man pages for out-of-date man pages, and
> currently don't have the resources at hand to check out a cutting-edge
> operating system. Sorry for being so verbose and indulgent ;>
Cheers,
Michael
