RE: annoyances digest, Vol 1 #80 - 22 msgs

> Date: Wed, 17 Sep 2003 10:39:09 -0500
> From: "Steven White" <[email protected]>
> To: <[email protected]>
> Subject: [Annoyances] Where IS the FM?
> Reply-To: [email protected]
>
> Here is a submission idea for your Linux annoyances.
>
> I do not have a lot of GNU/Linux experience, so perhaps the answer to
> this is obvious.  I would be eager to read the FM if I could FIND the
> FM.  I have found some documentation; the KDE desktop has a link for KDE
> documentation. But for other packages I have had to struggle, sometimes
> without success, to learn about them.
>

It is not "obvious" or trivial.  A lot of confusion can sprout from trying to FTFM (Find The Fine Manual).  In Linux/Unix, a lot of the text/console based applications and servers have entries in the Linux/Unix manual.  To get help with them simply type:

man <program name here>

To learn how to use "man," for instance, you would type (at the console):

man man

You can find a ton of stuff on most of these types of programs and servers.  For example information on using a console-based ssh client can be found by typing 

man ssh

and information on using the SSH server can be found by typing 

man sshd

All find and good, but THEN you have to know the command to be able to find the manual for it.  Not so great if want help doing something but you don't know what commands and utilities are needed to do it.

That is where "apropos" comes in.  It allows you to search the manual pages for keywords and then gives you the names of the commands whose manual contain those keywords.  It is not full featured and like any search feature generally gives more sh*t than pearls.  But it is a start.

Another trick that can be helpful for console/text commands is appending "-h" or "--help" to the command line after the command.  For the vast majority of commands, these flags will give a brief description and/or syntax usage information.

All this is mostly no good for some servers and most graphical programs.  The KDE help system will help with KDE specific apps, but it doesn't handle GNOME based apps.  Talk about annoying.  

A lot of developers store their documentation in a directory like /usr/share/doc.  Go there and use the directory names to find the application you are looking for.  Most of the documents therein are either in text or HTML.

>
> I think that developers and/or distributors for GNU/Linux should follow
> some standards for packaging documentation and there should be a link on
> the desktop for ALL documentation.  It should be as easy as possible to
> find the manuals. 

Of course, this doesn't address your problem and I totally agree that it stinks.  For many MANY years, I bought SuSE distributions because, (a) they came with hard copy instructions and useful reference books (in English... from a German company no less) and (b) the created a web-based personal help system that indexed (using htdig) the contents of the manual pages and all other disparate documentation.  If you needed help, you launched the help center which allowed you to type in any search term and be brought to a ranked list of possible FM's to peruse.

Genius.  Solving the problem of Linux documentation without having to tackle unifying everything (something that developers might or might not follow).

It worked very well.  More distributions should do this.

> Steven White
> City of Bloomington
> 2215 W Old Shakopee Rd
> Bloomington MN 55431-3096
> USA
> 952-563-4882 (voice)
> 952-563-4672 (fax)
> [email protected]

Jim Jones

*All opinions are my own and not those of anyone else or any other organization.  No one else would want them.*