discuss: Thread: Linux documentation

Dan Scott wrote:
> As someone who has spent some time on the PHP documentation team -
> maintaining the user notes (weeding out incorrect or complete spam
> notes) takes a massive amount of effort. Be prepared to invest a great
> deal of time weeding out the useless notes to try and ensure that only
> the useful notes remain, if you decide to go this route. I believe the
> PostgreSQL folks have had a similar experience. The idea is great, in
> an ideal world; in practice, it's very demanding.

Thanks for the data point(s).  Over the last couple of years a few 
people have suggested to me that I create a wiki for man-pages.  I have 
resisted out of concern over that very issue (plus there are many other 
things that so far have taken a higher priority for man-pages).

Cheers,

Michael

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

On Sat, Sep 15, 2007 at 12:14:56AM -0700, Steven wrote:
> Re html man page documentation (i think), ####@####.#### wrote:

> Would LDP posters be interested in a petition/campaign to GNU to
> ditch info pages and consolidate man pages as their definitive
> reference ? This will give everyone else a cornerstone to make up
> their own hyper linked and more attractive documentation, without
> the need for fancy ad-hoc wikis that say "Oh yeah, there's a new dvd
> udf filesystem standard that only works with kernel 2.6.NN.  The
> mount manpage doesn't know anything about it". I realize hassling
> GNU mightn't achieve much, and personally I'm not much of a diplomat
> myself ;> but who knows. One day RMS may start listening to other
> people, or, more likely, some one else will gain effective control
> of GNU's utilities. And maybe if we make a noise there will be
> plenty of other voices.

The problem is that info has hyperlinks while man pages don't (at
least not one's you click on unless it's in html format).  Another
problem with man-pages is the groff format source.  I would suggest that
linux-doc could be improved so that manpages could be written in
linux-doc and then converted to html, groff, etc.  Linuxdoc already
converts to groff as an intermediate step in converting to plain text.
It also converts to info pages using sgml2info.  Does docbook also
convert to info?  What would be needed would be a converter from info
to linux-doc.

But the problem of integration of Linux documentation is much more
than this and was discussed with hundreds of postings to
####@####.####  (ode = open documentation environment; oswg =
open source writers group).  But it seems that the archives of this
discussion have been destroyed and the domain name is up for sale.
However, they never reached any consensus of what's needed.  I think
someone was going to summarize the various proposal but never did.
But not much has been lost.  I'm worried that ldp.org may be up for
sale too if someone doesn't obtain it from Poet who presumably still
owns it.

			David Lawyer

> I would suggest that
> linux-doc could be improved so that manpages could be written in
> linux-doc and then converted to html, groff, etc. 

Laugh. It'd be nice.

> I'm worried that ldp.org may be up for
> sale too if someone doesn't obtain it from Poet who presumably still
> owns it.

Do you mean tldp.org ? I haven't followed the domain name saga too much, but ldp.org
seems a little ... unaffiliated, already.

Is ####@####.#### archived anywhere ?

S.A.



       
____________________________________________________________________________________
Boardwalk for $500? In 2007? Ha! Play Monopoly Here and Now (it's updated for today's economy) at Yahoo! Games.
http://get.games.yahoo.com/proddesc?gamekey=monopolyherenow  

David Lawyer writes:

> least not one's you click on unless it's in html format).  Another
> problem with man-pages is the groff format source.  I would suggest that
> linux-doc could be improved so that manpages could be written in
> linux-doc and then converted to html, groff, etc.  Linuxdoc already
> converts to groff as an intermediate step in converting to plain text.
> It also converts to info pages using sgml2info.  Does docbook also
> convert to info?

Converting manpages to Docbook will not automatically give you hyperlinks. 
Links in Docbook XML are limited to internal links to other parts of the 
document. If you assemble a set of manpages into a single Docbook XML 
document, you can have manpages inside the set linking to each other. But if 
each manpage is a standalone document, it won't be able to link to anything 
else. Not unless you apply a custom stylesheet after converting the document 
to HTML. This is not hard, but now you're getting away from an ordinary 
Docbook XML document, and introduce your own hacks on top of it.