Subject:
Re: [discuss] Linux documentation
From:
Steven ####@####.####
Date:
23 Sep 2007 01:12:09 +0000
Message-Id: <258298.63988.qm@web53205.mail.re2.yahoo.com>
"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 ;>
I don't like info pages, 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.
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.
> -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.
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 ;>
* 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. (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 ;>
- Steven.
____________________________________________________________________________________
Be a better Globetrotter. Get better travel answers from someone who knows. Yahoo! Answers - Check it out.
http://answers.yahoo.com/dir/?link=list&sid=396545469
