Suggestion: "man git clone"

Suggestion: "man git clone"

[H. Peter Anvin]

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

Re: Suggestion: "man git clone"

["Peter Valdemar Mørch (Lists)"]

H. Peter Anvin hpa-at-zytor.com |Lists| 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

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...
-- 
Peter Valdemar Mørch
http://www.morch.com

Re: Suggestion: "man git clone"

[H. Peter Anvin]

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.

	-hpa

Re: Suggestion: "man git clone"

[Avery Pennarun]

On Thu, Aug 21, 2008 at 12:37 PM, H. Peter Anvin <hpa@zytor.com> wrote:
> 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?

Thanks,

Avery

Re: Suggestion: "man git clone"

[H. Peter Anvin]

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

	-hpa

Re: Suggestion: "man git clone"

[Jeff King]

On Thu, Aug 21, 2008 at 10:22:47AM -0700, H. Peter Anvin wrote:

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

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.

-Peff

Re: Suggestion: "man git clone"

[Jeff King]

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

Re: Suggestion: "man git clone"

[H. Peter Anvin]

Jeff King wrote:
> 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

Yeah, that pretty much makes it not a general solution.

	-hpa

Re: Suggestion: "man git clone"

[Jeff King]

On Thu, Aug 21, 2008 at 01:14:41PM -0700, H. Peter Anvin wrote:

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

Oh, sorry, this was just me being incompetent. I was testing with

  MANSECT=git man git am

and of course

  MANSECT=git man git

broke because we are no longer looking in section "1".

Setting the sections properly (by adding "git" to /etc/manpath.config,
or using MANSECT=1:git) and creating a linkfarm in .../man/mangit (with
am.git pointing to ../man1/git-am.1) makes both "man git" and "man git
am" work fine.

The changes to manpath.config make it a bit outside the scope of git's
regular install, but maybe this is something distro people would want to
do.

-Peff

Re: Suggestion: "man git clone"

[Bert Wesarg]

On Thu, Aug 21, 2008 at 19:22, H. Peter Anvin <hpa@zytor.com> wrote:
> 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.)
It works here. I have to add 'git' to the SECTION list in /etc/manpath.config.

Bert
>
>        -hpa

Re: Suggestion: "man git clone"

[A Large Angry SCM]

H. Peter Anvin wrote:
> 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.

Actually, the current "man" behavior is very convenient when  you want 
to lookup multiple things. And *I* do use that feature.

Re: Suggestion: "man git clone"

[Federico Lucifredi]

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


-- 

_________________________________________
-- "'Problem' is a bleak word for challenge" - Richard Fish
(Federico L. Lucifredi) - http://www.lucifredi.com

Re: Suggestion: "man git clone"

[H. Peter Anvin]

Federico Lucifredi wrote:
> 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...
> 

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

Re: Suggestion: "man git clone"

[Federico Lucifredi]

H. Peter Anvin wrote:
> Federico Lucifredi wrote:

[...]

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

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.

Are you willing to put your patch where your mouth is? :-)

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


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

Re: Suggestion: "man git clone"

[Jeff King]

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.

Personally I have never ever wanted to see two manpages from one man
invocation, so I have no real problem with that assumption.

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

-Peff

Re: Suggestion: "man git clone"

[Jeff King]

On Thu, Aug 21, 2008 at 08:40:52PM -0400, Jeff King wrote:

> 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

Re-reading this, it may not be clear what I meant. I mean there exists a
_manpage_ "X-Y" such that "X" and "Y" are also manpages. So on my system
there are three commands, each with a manpage: cvs, debc, and cvs-debc.

-Peff

Re: Suggestion: "man git clone"

[Miklos Vajna]

[-- Attachment #1: Type: text/plain, Size: 321 bytes --]

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.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: Suggestion: "man git clone"

[Jeff King]

On Fri, Aug 22, 2008 at 03:15:15AM +0200, Miklos Vajna wrote:

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

Right. What I meant was two-fold:

  1. "I am not going to take your patch challenge, because I don't even
     seem to be running your man pager."

  2. It has been noted in this thread that this will only affect Linux.
     But it is even worse; it will only affect some distributions. So
     people need to get several implementations to agree.

-Peff

Re: Suggestion: "man git clone"

[Federico Lucifredi]

Miklos Vajna wrote:
> 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.

Indeed. man-db has a higher numbering than man, which sometimes reduces 
confusion, and sometimes increases it.

  Best -F

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

Re: Suggestion: "man git clone"

[Federico Lucifredi]

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

That's right.

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

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

Re: Suggestion: "man git clone"

[Colin Watson]

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

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
least interesting features as far as I'm concerned (and I recommend GDBM
for the database layer nowadays anyway, since Berkeley DB is overkill
and has gone through an annoying number of disk format changes).

These days, much more relevant are things like the fact that man-db can
handle encodings properly (both in manual pages and its own translated
messages; *why* does man still use catgets?), and the effort put into
process glue libraries so that it doesn't have to be audited carefully
for unsafe shell code and so that it can be a lot more efficient when
processing large numbers of manual pages (e.g. man -K).

Anyway, if you look at the history, what happened is that John W. Eaton
wrote the original man way back in 1990/1 or so, then two different sets
of people developed it in different directions into man and man-db. That
was in the early 1990s when free software developers weren't
communicating as often as they do now. Then, by the time it became
obvious around 1995 that there'd been a fork, the two were already
separate packages with different aims and it was now too hard for anyone
to merge them. You could still see the common ancestry if you looked
closely (indeed, you still can in places), but they're really much more
like two completely separate implementations than a fork. It's a bit of
a shame in some ways, but harmless enough.

Cheers,

-- 
Colin Watson                                       [cjwatson@debian.org]

Re: Suggestion: "man git clone"

[Federico Lucifredi]

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

Re: Suggestion: "man git clone"

[Federico Lucifredi]

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

Re: Suggestion: "man git clone"

[Federico Lucifredi]

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.

  I would still go with the single big page (people are used to 
vi-search with "/" anyway), but if you want to split the manual this 
would work, and you could refer to the pages explicitly in the main git 
page.

  Finally, and importantly, "apropos clone" or "man -k clone" would 
correctly point to git::clone as a valid result.

  One more option for you.

  Best -F

Federico Lucifredi wrote:
> 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
> 
> 


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

Re: Suggestion: "man git clone"

[H. Peter Anvin]

Federico Lucifredi wrote:
> 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.
> 

That's just as bad as "man git-clone".  Arguably worse.

	-hpa

Re: Suggestion: "man git clone"

[Michael J Gruber]

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 inside git (warnings etc) from "man git-bla" to
"git help bla".

- Change all references in the help pages (gitlinks) accordingly.

- Put a warning in the main git man page which redirects the confused
("If you were looking for the manpage of "git bla" and issued "man git
bla", please refer to "man git-bla" or "git help bla".'), maybe just
before the command list there.

This could be supported by an alias mapping "git man" to "git help -m".

I've heard about some other SCMs which have only "scm help bla", so this
suggestion would be in-line with common usage. [Not that git would have
to learn from other SCM's ;) ]

Michael

Re: Suggestion: "man git clone"

[Derek Fawcus]

On Fri, Aug 22, 2008 at 01:02:57PM +0200, Michael J Gruber wrote:
> I've heard about some other SCMs which have only "scm help bla", so this
> suggestion would be in-line with common usage. [Not that git would have
> to learn from other SCM's ;) ]

Clearcase - commands such as 'cleartool describe',  man page in ct+describe.1

Has 'cleartool help describe' (and 'cleartool describe -help') which gives a
usage summary,  and 'cleartool man describe' (or 'man ct+describe') for the
man page.

So basically the same solution,  but a slightly different choice/use for keywords.

(and if one has an alias 'ct=cleartool',  it seems to make more sense).

DF

Re: Suggestion: "man git clone"

[Mikael Magnusson]

2008/8/22 Michael J Gruber <michaeljgruber+gmane@fastmail.fm>:
> 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.

I think that would break navigating man pages in any man reader... Most of
them detect and handle "foo(N)" magically and let you click on it.

-- 
Mikael Magnusson

Re: Suggestion: "man git clone"

[Matthieu Moy]

Michael J Gruber <michaeljgruber+gmane@fastmail.fm> writes:

> I've heard about some other SCMs which have only "scm help bla", so this
> suggestion would be in-line with common usage. [Not that git would have
> to learn from other SCM's ;) ]

OTOH, I like the fact that the manpages be browsable with man. As an
Emacs user, I often do M-x man RET git-whatever RET, other people can
enjoy their favorite man reader.

If git starts hiding that "man" stuff to the user, (s)he may just fail
to notice that it is possible.

-- 
Matthieu