Suggestion: "man git clone"

> 
> Sorry man that behaviour is the way "man" works. See "man man".
> 
>   $ git clone --help
> or
>   $ git help clone
> 
> work right?
> 
> Peter
> 
> P.S: man, there are puns in that...

> man git clone
>
> [...]
>
> I doubt you find *anyone* who relies on the current behaviour, so I am
> suggesting changing man.  That's why the man author was on the recipient
> list, but you removed it.
>

> 
> [and I put him back...]
> 
> Unfortunately what we don't have is a proposal that would work better.
>  Also, changing the behaviour of 'man' wouldn't work on any platform
> other than Linux (presumably), which means the git documentation
> wouldn't be able to rely on that behaviour.
> 
> Still, in a perfect world, what *should* man do in such a case?
> Automatically open /usr/man/man1/git/clone.1?
> 

> There is some configuration magic about what is a section. Try
> 
>   perl -pi -e 's/^SECTION.*/$& git/' /etc/manpath.config
> 
> That seems to convince my man to look in .../mangit, but I'm having
> trouble actually getting it to find a page and I don't have time to
> investigate further now.

> On Thu, Aug 21, 2008 at 01:38:42PM -0400, Jeff King wrote:
> 
>> There is some configuration magic about what is a section. Try
>>
>>   perl -pi -e 's/^SECTION.*/$& git/' /etc/manpath.config
>>
>> That seems to convince my man to look in .../mangit, but I'm having
>> trouble actually getting it to find a page and I don't have time to
>> investigate further now.
> 
> Ah, OK. My problem was that the pages actually need to be named "am.git",
> etc. But with 'git' in the section field, "man git am" does work.
> Unfortunately, it seems to break "man git". :(
> 
> -Peff

>> Ah, OK. My problem was that the pages actually need to be named "am.git",
>> etc. But with 'git' in the section field, "man git am" does work.
>> Unfortunately, it seems to break "man git". :(
>
> Yeah, that pretty much makes it not a general solution.

> Avery Pennarun wrote:
>>
>> [and I put him back...]
>>
>> Unfortunately what we don't have is a proposal that would work better.
>>  Also, changing the behaviour of 'man' wouldn't work on any platform
>> other than Linux (presumably), which means the git documentation
>> wouldn't be able to rely on that behaviour.
>>
>> Still, in a perfect world, what *should* man do in such a case?
>> Automatically open /usr/man/man1/git/clone.1?
>>
>
> That would probably be the best option, other options are $MANPATH/man1/git\
> clone.1 or $MANPATH/mangit/clone.git (I actually tried that on the
> assumption that it might treat "git" as a section; unfortunately, it didn't
> work.)

> Peter Valdemar Mørch (Lists) wrote:
>>
>> Sorry man that behaviour is the way "man" works. See "man man".
>>
>>   $ git clone --help
>> or
>>   $ git help clone
>>
>> work right?
>>
>> Peter
>>
>> P.S: man, there are puns in that...
> 
> I know that that is the way "man" currently works.
> 
> I doubt you find *anyone* who relies on the current behaviour, so I am 
> suggesting changing man.  That's why the man author was on the recipient 
> list, but you removed it.

> Given the recent change of "git-foo" to "git foo", it would be really 
> nice if one could type, for example:
> 
>     man git clone
> 
> and actually get the man page for the git clone command.  There are 
> quite a few other pieces of software which also could benefit from that 
> kind of indirection.
> 
> Right now the above command shows the man page git(1) followed by 
> clone(2), which I believe has be classified as utterly useless behaviour...
> 
>     -hpa

> Hello HP,
>  I have seen this in (funnily enough) a project I manage myself, which 
> has subcommands structured similarly to Git.
> 
>  I have looked at options, but so far the current behavior (man foo-bar) 
> seems the best option for foo's subcommand bar. The alternative, also 
> acceptable, is a large page with subsections for each command. Sections 
> (man 1) are used for chapter-like page groupings, not for subsections on 
> a single command - those would have to be implemented as an additional 
> layer.
> 
>  But, as another participant in the thread has commented, that would not 
> port to other platforms very quickly (although it would get to Linux and 
> OS-X promptly, and may eventually make its way into other platforms).
> 
>  I am open to ideas, but so far the two options above are better than 
> anything else that has been so far suggested...
> 

>>  I am open to ideas, but so far the two options above are better than 
>> anything else that has been so far suggested...
>>
> 
> One option would be to support "man foo bar" showing the page labelled 
> foo-bar.  That way you'd get at least a modicum of bass-ackwards 
> compatibility.

> 
> However, at some point we have to be willing to do things other 
> platforms won't, or we'll never do anything new...
> 
>     -hpa

> 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.

> On Thu, Aug 21, 2008 at 08:40:52PM -0400, Jeff King <peff@peff.net> wrote:
> > 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.
> 
> Obviously that's not the one Federico maintains. ;-)
> 
> See http://primates.ximian.com/~flucifredi/man/, it's at 1.6f.

> On Thu, Aug 21, 2008 at 08:40:52PM -0400, Jeff King <peff@peff.net> wrote:
>> 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.
> 
> Obviously that's not the one Federico maintains. ;-)
> 
> See http://primates.ximian.com/~flucifredi/man/, it's at 1.6f.

> 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.
> 
> Well, the drawback is that there exist X-Y such that X and Y both have
> manpages (e.g., cvs-debc on my debian box). So we are assuming that the
> risk is acceptably low of somebody asking for "man X Y", wanting two
> manpages, and that X and Y fit this pattern.
> 

>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.

>> 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.

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

> 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.
> 

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

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

> 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.
> 

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

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

> Hello HP,
>  I have seen this in (funnily enough) a project I manage myself, which 
> has subcommands structured similarly to Git.
> 
>  I have looked at options, but so far the current behavior (man foo-bar) 
> seems the best option for foo's subcommand bar. The alternative, also 
> acceptable, is a large page with subsections for each command. Sections 
> (man 1) are used for chapter-like page groupings, not for subsections on 
> a single command - those would have to be implemented as an additional 
> layer.
> 
>  But, as another participant in the thread has commented, that would not 
> port to other platforms very quickly (although it would get to Linux and 
> OS-X promptly, and may eventually make its way into other platforms).
> 
>  I am open to ideas, but so far the two options above are better than 
> anything else that has been so far suggested...
> 
>  Best -F
> 
> H. Peter Anvin wrote:
>> Given the recent change of "git-foo" to "git foo", it would be really 
>> nice if one could type, for example:
>>
>>     man git clone
>>
>> and actually get the man page for the git clone command.  There are 
>> quite a few other pieces of software which also could benefit from 
>> that kind of indirection.
>>
>> Right now the above command shows the man page git(1) followed by 
>> clone(2), which I believe has be classified as utterly useless 
>> behaviour...
>>
>>     -hpa
> 
> 

> Hello HP, All,
>  I somehow managed to forget this (age must be taking its toll), but 
> there is a convention commonly used for man pages of Perl Modules, which 
> can be reasonably usable for subcommands as well:
> 
>  man APR::Brigade
> 
> will work just fine, with a file by the same name. This convention is in 
> current use, and would map to
> 
>  man git::clone
> 
> while :: is not as immediate in context as in Perl, it does do the job, 
> and works regardless of pager.
> 

> Given the recent change of "git-foo" to "git foo", it would be really 
> nice if one could type, for example:
> 
> 	man git clone
> 
> and actually get the man page for the git clone command.  There are 
> quite a few other pieces of software which also could benefit from that 
> kind of indirection.
> 
> Right now the above command shows the man page git(1) followed by 
> clone(2), which I believe has be classified as utterly useless behaviour...

> H. Peter Anvin venit, vidit, dixit 21.08.2008 02:11:
>> Given the recent change of "git-foo" to "git foo", it would be really
>> nice if one could type, for example:
>>
>>       man git clone
>>
>> and actually get the man page for the git clone command.  There are
>> quite a few other pieces of software which also could benefit from that
>> kind of indirection.
>>
>> Right now the above command shows the man page git(1) followed by
>> clone(2), which I believe has be classified as utterly useless behaviour...
>
> The discussion seems to show that altering man and relying on the new
> behaviour is no option, and neither is playing games with man's section
> options.
>
> How about:
>
> - Change all references in the help pages (gitlinks) accordingly.