TOC for man

[Eric "Shubes"]

Alex LeDonne wrote:
> On 2/14/07, Eric Shubes <plug at shubes.net> wrote:
>> Jon M. Hanson wrote:
>>> On Wed, Feb 14, 2007 at 08:50:20AM -0700, Eric Shubes wrote:
>>>> Jon M. Hanson wrote:
>>>>> On Wed, Feb 14, 2007 at 07:53:43AM -0700, Eric Shubes wrote:
>>>>>> I'm tired of hunting for man pages. My problem is, "man what"?
>>>>>>
>>>>>> I usually know what package I'm looking for some documentation about (or
>>>>>> want to learn about), so I "rpm -ql package | grep man" to see what man
>>>>>> pages are available.
>>>>>>
>>>>>> Is there a better way? Of course there could be. I've googled and came up
>>>>>> with nothing that's CLI oriented (which is what I want).
>>>>>>
>>>>>> I'm thinking of writing a script:
>>>>>> mansfor [package_name]
>>>>>> that will give me a nice menu of man pages to browse for a particular
>>>>>> package. That would satisfy my immediate need. Then I'd probably add -s to
>>>>>> search for a string included in a package_spec, and optional section numbers
>>>>>> to filter, so it'd look more like
>>>>>> mansfor {section_number} ... {-s} [package_spec]
>>>>>>
>>>>>> Does anyone know of something like this that already exists? I'm just not
>>>>>> inclined to reinvent the wheel.
>>>>> Do you know about the -k switch to man. This looks for a specific
>>>>> keyword in all of the man pages. Also the apropos command may also be
>>>>> able to help you.
>>>>>
>>>> No I didn't. It appears (man man) that the -k switch is equivalent to
>>>> apropos. apropos helps, but it's not always sufficient. I don't necessarily
>>>> know what I'm looking for (especially in learning mode). I can sometimes
>>>> chase things down using SEE ALSO references, but I feel like I'm on a
>>>> scavenger hunt, and it's difficult to get the big picture. All the pieces
>>>> are there, but there's no sense of the puzzle.
>>> I'll admit that man -k isn't the best solution but it does help even if
>>> it does take a couple of tries to find what you're looking for. Do you
>>> have a recent example of something that you were looking for but didn't
>>> know where to start looking?
>>>
>> I'm using qmail-toaster, and each one of the many packages has its own set
>> of man pages. I've found the most difficulty with DJB related packages
>> (daemontools, ucspi-tcp, and qmail), although. DJB's stuff is a love-hate
>> sort of thing.
>>
>> As an example, I just stumbled upon qmail-spamthrottle. I never knew it was
>> there. Looks kinda cool. How did I find it? Browsing through all of the man
>> pages for qmail-toaster. There's very little documentation of DJB stuff
>> apart from the man pages. Other packages (pick any) seem to lack any way of
>> looking at the man pages top down. Everything seems to be bottom up.
>>
>> apropos is like an index, and a good one. I'm looking for a Table Of Contents.
>>
>> I appreciate everyone's input on this.
>> --
>> -Eric 'shubes'
> 
> shubes,
> 
> I found a manpage online,
> qmail-spamthrottle(5) - the qmail spam throttle mechanism
> 
> This means that 'apropos qmail' should have returned it among the
> manpage listings, since qmail appears in the description.
> 
> What does 'apropos qmail' return on your system?
> 
> -A

Forget that example. That came up on my test machine which had an older
version of the toaster. spamthrottle has since been removed, which is why
I'd never seen it. <blush>

I'll see if I can't do better with apropos (along with grep perhaps).

-- 
-Eric 'shubes'