Grex Systems Conference

View Responses

Grex Systems Item 35: The Unix Document Preparation item
Entered by cross on Sun Sep 17 00:12:51 UTC 2006:

This is the Unix document preparation item.  Ever wondered how man pages are
written, or how to use troff to produce a nicely formated paper?  Or how to
use TeX, LaTeX, or Docbook?  Ask here.

11 responses total.

#1 of 11 by other on Mon Sep 18 20:07:06 2006:

Here's a UNIX documentation question.  Why is there no short guide to
every executable's primary function distributed with most variants in an
easily locatable place?  By short guide, I mean a one line description
of the basic purpose of each of the tons of commands/utilities included
in a distro, combined in a single document.

#2 of 11 by twenex on Mon Sep 18 20:38:09 2006:

Because a one line description of <foo> can be obtained by entering the
command "whatis <foo>". A one line description of all manpages whose
associated commands relate to <foo> can be obtained with "man -k <foo>", or
its popular synonym, "apropos <foo>"

#3 of 11 by twenex on Mon Sep 18 21:05:24 2006:

The commands work by searching the "NAME" field of manpages, which also
contain a one line description.

#4 of 11 by cross on Tue Sep 19 03:36:04 2006:

(It would be nice to have an index; the whatis database on some systems is
a flat file and can serve this purpose.  Or, you could write a script to
extract the information from the man pages themselves....)

#5 of 11 by twenex on Tue Sep 19 15:09:26 2006:

To clarify: on many (most?) systems the whatis command takes info from a flat
file, but this information is extracted by the makewhatis command from the
NAME field of manpages.

#6 of 11 by other on Tue Sep 19 21:12:39 2006:

I guess what I'm looking for is more a browseable list of the outputs of
'whatis <foo>' for all <foo> on the system.  I have a vast quantity of
executables in various directories on my computer, and if I want to look
and see if one exists that does a specific thing, or just look through a
list a see what some of the things are that tools have been written to
do, I don't know how to do that.

#7 of 11 by cross on Wed Sep 20 04:10:39 2006:

Regarding #5; Unfortunately, under OpenBSD, it appears to be a Berkeley DB
format file.  I suppose that's for fast searching, but it makes using grep
on it sorta impossible....

Regarding #6; On grex, there was a "listcommand" or "listcommands" script that
did just that.  I re-wrote it for grexsoft, but that never get put on after
the last upgrade, so it's probably back to original.  Here's my version:

#!/usr/bin/perl -w
use strict;

my $path = $ENV{'PATH'};
if (@ARGV) {
        $path = join ':', @ARGV;
}

print "Searching command directories.\n";
my %files = ();
foreach my $dir (split(/:/, $path)) {
        next unless $dir;
        print "Processing $dir...";
        opendir(DIR, $dir) || next;
        while (my $file = readdir(DIR)) {
                next unless -x "$dir/$file" && ! -d _;
                $files{$file}++;
        }
        closedir DIR;
        print "Done\n";
}

print "Grex Unix Commands\n";
foreach my $file (sort keys %files) {
        my $whatis = `whatis -- $file`;
        $whatis =~ s/.*(not found|nothing appropriate).*\n//;
        $whatis =~ s/^[^-]*-\s*([^\n]*)(\n.*)*/ - $1/;
        print $file, $whatis, "\n";
}

More of the grexsoft tools can be found in my home directory, under
~cross/grexsoft.

#8 of 11 by other on Wed Sep 20 13:13:06 2006:

i don't know perl, so i'm not sure why, but when i ran that script on my
machine, i got a long list of '<foo> - -: unknown option'

#9 of 11 by cross on Wed Sep 20 22:15:06 2006:

What machine are you running it on?  It would appear that the whatis command
on that machine doesn't understand the "--" notation (which is supposed to
mean, "halt argument list processing" - this is useful if a command begins
with a -).

#10 of 11 by other on Thu Sep 21 03:01:47 2006:

PowerBook G4, OS X 10.4.7

Based on your comment, I took the '--' out of the line which generates
the output, and it works now. 

There are some interesting looking items which have no explanation, such
as 'zipcloak' and 'testrb' and 'seg_hack'.

#11 of 11 by cross on Fri Sep 22 00:53:07 2006:

Hmm; I think that code works okay on my iBook running OS X 10.4.7, as well.
Well, maybe not; I just tried it and it gave me the same error.  I guess you
can't do whatis for a command that starts with a -.

testrb is a the Ruby Test::Unit runner.  zipcloak has something to do with
zipfiles; I assume it is intended to encrypt zip files, but I just get an
error message when I run it on my iBook.  I'm not sure what seg_hack is; I
don't appear to have it on my system.

Response not possible - You must register and login before posting.