Re: [Groff] Mission statement

[Charlie Kester]

On Sun 16 Mar 2014 at 01:57:31 PDT Eric S. Raymond wrote:
> Here's what I think is going on.  There are two different access cases
> for man pages: directed and serendipitous.
>
> In the directed case, you know the man page you want.  You browse it locally,
> through a terminal emulator or (if you're me) more often in an in an Emacs
> buffer.
>
> In the serendipitous case, you found the page via search engine.
> *That* is when browser usage dominates.

I doubt that what I'm going to describe is a common usage, but I'll add
another use-case for the browser.

I've often found that I have things installed on my system that I didn't
know about.  Things that probably came in with some package I installed.

I found myself wanting some kind of index of the available commands.
Something a little more informative than a listing of the contents of
/usr/bin or /usr/local/bin.

So I wrote a script to put html'ized versions of all the available
manpages in a directory and created an index.html to list and access
them all.  That was a little better than ls'ing the bin directories and
then man'ing anything that looked interesting, but not by much.  At
least it weeded out things where there was no manpage.

I thought it about it some more and decided to add some more structure
to the index.  I modified my script to read a file listing all the
commands for which I had manpages, along with a category (e.g.,
SYSADMIN, TEXT_FORMATTING, CRYPTO).  Any commands thus categorized got
moved to a corresponding "sub-index" page, which in turned got
referenced on the main page.

Since then there have been lots of tweaks to automate as much as
possible, but at the heart there is still a need to manually categorize
the commands.  I wish manpages would contain something that would help
with that.  The existing section numbers are next to useless, since
almost everything I'm trying to get a handle on is in section 1.

To summarize, my scheme leverages two features readily available in the
browser, but not so easily obtained through a terminal: using an
index.html page to present a customized interface to directory contents;
and hypertext linking from that index to the desired information.

I've found that using this scheme, my system is much more discoverable.

My apologies for adding to an apparently unkillable OT discussion!  (Or
is it merely a digression?)