Re: Suggestion: "man git clone"

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 [ref], Federico Lucifredi wrote:

quoted

Jeff King wrote:

quoted

On Thu, Aug 21, 2008 at 08:07:56PM -0400, Federico Lucifredi wrote:

quoted

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.

quoted

quoted

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?

quoted

quoted

quoted

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