Re: Suggestion: "man git clone"

[Federico Lucifredi <flucifredi@acm.org>]

Colin Watson wrote:
> (Sorry I didn't see this until now. HPA only CCed the maintainer of one
> of the two man packages popular on Linux-based systems; I'm the other
> one. I happened to find this thread while searching for something else.)
> 

Really? Sorry, I thought I had added you. My bad.

> In article <48AE143C.8030704@acm.org>, Federico Lucifredi wrote:
>> Jeff King wrote:
>>> On Thu, Aug 21, 2008 at 08:07:56PM -0400, Federico Lucifredi wrote:
>>>> I am all for bass-ackwards compatibility, and I think the suggestion of  
>>>> going on "man foo bar" :
>>>>
>>>>  1) look for foo-bar; if success, terminate search
>>>>  2) look for foo
>>>>  3) look for bar
>>>>  ....
>>>>
>>>> may be acceptable - I don't see drawbacks at a first glance, and it would 
>>>> allow for groups of pages to be meaningful.
> 
> I think this is a sensible enough compromise, especially given an option
> to disable it. The code would be a little ugly, but *shrug* not that
> bad. The extra stat is cheap enough.
> 

Sounds good to me :)

> Using a plain 'git' section for this in order to provoke the
> happenstance of 'man git clone' working is definitely wrong as far as
> the manual page hierarchy goes; it means that things like searching for
> just user commands (section 1) that contain some term will fail. Putting
> them in section '1git' (i.e. section 1 with a git "extension") would be
> more in line with how manual pages are typically laid out, and at least
> with man-db would not require any configuration file changes. However, I
> think both of these are suboptimal. Section extensions are typically
> used for things like functions or modules in other programming
> languages, or sometimes for cases where file names would otherwise
> clash. I'm not much of a git user myself, but I don't get the impression
> that most git users think of 'git clone' as analogous to a 'clone'
> command in a hypothetical 'git' programming language; it's closer to an
> ordinary user command.
> 
> The only case where I've seen subcommands given their own unprefixed
> manual pages with only the section extension to tell them apart is
> OpenSSL, with pages like x509(1ssl). IME, this is very confusing and not
> a good example to follow: firstly, you can't trivially find a list of
> all the subcommands with something like 'apropos openssl-'; secondly,
> it's easy to miss that you're dealing with an openssl subcommand unless
> you keep your eyes peeled.
> 
> Short of some mechanism for git to provide a plug-in to man to tell it
> where to find subpages (eek! potential overengineering alert!), a
> foo-bar lookup seems tolerable enough.
> 
>>> Personally I have never ever wanted to see two manpages from one man
>>> invocation, so I have no real problem with that assumption.
>> I expected as much, and we should have an option to disable the "new" 
>> behavior as a safety anyway.
> 
> Would you like to suggest an option name for this, so that we can avoid
> unnecessary divergence? Perhaps something like --separate?

the option to trigger "classic" behavior? How about --no-subpages?

> 
>>>> Are you willing to put your patch where your mouth is? :-)
>>> I've never looked at man code before, but there seem to be at least two
>>> man packages for Linux. My boxes have man-db 2.5.2.
>> There are two man packages for linux, man and man-db, the latter being a 
>> 90's fork that uses Berkeley DB as a backend to speedup man -k searches 
>> (it helped back then).
> 
> (I hope git@ will excuse the digression.)
> 
> Don't be confused by the name. Once upon a time the main feature of
> man-db was indeed its database; these days that's almost one of the

[snip]

I am sorry Colin, I did not mean to say anything bad, just that there
are two packages, and as you said... there are differences but nothing
major.  I don't think we want to discuss "my package > yours" here
(although I can of course provide arguments for mine!).

Are you Git guys still interested in this? I actually have recently
worked on a project where we labeled man pages for subcommands with this
convention, so I would welcome the extension for neatness.

 Best -F

-- 
_________________________________________
-- "'Problem' is a bleak word for challenge" - Richard Fish
(Federico L. Lucifredi) - flucifredi@acm.org - GnuPG 0x4A73884C