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?)
