# Suggestion: "man git clone" 29 messages from 2008-08-21 to 2009-07-06. Participants: H. Peter Anvin, Peter Valdemar Mørch (Lists), Avery Pennarun, Jeff King, Bert Wesarg, Federico Lucifredi, Miklos Vajna, Michael J Gruber, A Large Angry SCM, Derek Fawcus, Mikael Magnusson, Matthieu Moy, Colin Watson. Thread: https://gitlist.dev/t/15117 ## H. Peter Anvin, 2008-08-21 00:11 Subject: Suggestion: "man git clone" Message-ID: <48ACB29C.7000606@zytor.com> URL: https://gitlist.dev/e/48ACB29C.7000606%40zytor.com ``` 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 ``` ## Peter Valdemar Mørch (Lists), 2008-08-21 00:25 Subject: Re: Suggestion: "man git clone" Message-ID: <48ACB5F4.3000905@sneakemail.com> URL: https://gitlist.dev/e/48ACB5F4.3000905%40sneakemail.com In-Reply-To: <48ACB29C.7000606@zytor.com> ``` 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 ``` ## H. Peter Anvin, 2008-08-21 16:37 Subject: Re: Suggestion: "man git clone" Message-ID: <48AD99DF.5090802@zytor.com> URL: https://gitlist.dev/e/48AD99DF.5090802%40zytor.com In-Reply-To: <48ACB5F4.3000905@sneakemail.com> ``` 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 ``` ## Avery Pennarun, 2008-08-21 17:07 Subject: Re: Suggestion: "man git clone" Message-ID: <32541b130808211007xf295e40l567ecf785a8fca22@mail.gmail.com> URL: https://gitlist.dev/e/32541b130808211007xf295e40l567ecf785a8fca22%40mail.gmail.com In-Reply-To: <48AD99DF.5090802@zytor.com> ``` On Thu, Aug 21, 2008 at 12:37 PM, H. Peter Anvin 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 ``` ## H. Peter Anvin, 2008-08-21 17:22 Subject: Re: Suggestion: "man git clone" Message-ID: <48ADA467.1030407@zytor.com> URL: https://gitlist.dev/e/48ADA467.1030407%40zytor.com In-Reply-To: <32541b130808211007xf295e40l567ecf785a8fca22@mail.gmail.com> ``` 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 ``` ## Jeff King, 2008-08-21 17:38 Subject: Re: Suggestion: "man git clone" Message-ID: <20080821173842.GB26920@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080821173842.GB26920%40coredump.intra.peff.net In-Reply-To: <48ADA467.1030407@zytor.com> ``` 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 ``` ## Bert Wesarg, 2008-08-21 17:52 Subject: Re: Suggestion: "man git clone" Message-ID: <36ca99e90808211052k5a67b7ccv7031c38d28f75f73@mail.gmail.com> URL: https://gitlist.dev/e/36ca99e90808211052k5a67b7ccv7031c38d28f75f73%40mail.gmail.com In-Reply-To: <48ADA467.1030407@zytor.com> ``` On Thu, Aug 21, 2008 at 19:22, H. Peter Anvin 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 ``` ## Jeff King, 2008-08-21 20:13 Subject: Re: Suggestion: "man git clone" Message-ID: <20080821201307.GC27705@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080821201307.GC27705%40coredump.intra.peff.net In-Reply-To: <20080821173842.GB26920@coredump.intra.peff.net> ``` 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 ``` ## H. Peter Anvin, 2008-08-21 20:14 Subject: Re: Suggestion: "man git clone" Message-ID: <48ADCCB1.6040803@zytor.com> URL: https://gitlist.dev/e/48ADCCB1.6040803%40zytor.com In-Reply-To: <20080821201307.GC27705@coredump.intra.peff.net> ``` 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 ``` ## Jeff King, 2008-08-21 20:18 Subject: Re: Suggestion: "man git clone" Message-ID: <20080821201828.GA28844@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080821201828.GA28844%40coredump.intra.peff.net In-Reply-To: <48ADCCB1.6040803@zytor.com> ``` 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 ``` ## Federico Lucifredi, 2008-08-21 21:49 Subject: Re: Suggestion: "man git clone" Message-ID: <48ADE2FF.4080704@acm.org> URL: https://gitlist.dev/e/48ADE2FF.4080704%40acm.org In-Reply-To: <48ACB29C.7000606@zytor.com> ``` 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 ``` ## H. Peter Anvin, 2008-08-21 23:07 Subject: Re: Suggestion: "man git clone" Message-ID: <48ADF542.9010105@zytor.com> URL: https://gitlist.dev/e/48ADF542.9010105%40zytor.com In-Reply-To: <48ADE2FF.4080704@acm.org> ``` 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 ``` ## Federico Lucifredi, 2008-08-22 00:07 Subject: Re: Suggestion: "man git clone" Message-ID: <48AE035C.8000504@acm.org> URL: https://gitlist.dev/e/48AE035C.8000504%40acm.org In-Reply-To: <48ADF542.9010105@zytor.com> ``` 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 ``` ## Jeff King, 2008-08-22 00:40 Subject: Re: Suggestion: "man git clone" Message-ID: <20080822004052.GA30476@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080822004052.GA30476%40coredump.intra.peff.net In-Reply-To: <48AE035C.8000504@acm.org> ``` 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 ``` ## Jeff King, 2008-08-22 00:42 Subject: Re: Suggestion: "man git clone" Message-ID: <20080822004250.GB30476@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080822004250.GB30476%40coredump.intra.peff.net In-Reply-To: <20080822004052.GA30476@coredump.intra.peff.net> ``` 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 ``` ## Miklos Vajna, 2008-08-22 01:15 Subject: Re: Suggestion: "man git clone" Message-ID: <20080822011515.GY23800@genesis.frugalware.org> URL: https://gitlist.dev/e/20080822011515.GY23800%40genesis.frugalware.org In-Reply-To: <20080822004052.GA30476@coredump.intra.peff.net> ``` On Thu, Aug 21, 2008 at 08:40:52PM -0400, Jeff King 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. ``` ## Federico Lucifredi, 2008-08-22 01:19 Subject: Re: Suggestion: "man git clone" Message-ID: <48AE143C.8030704@acm.org> URL: https://gitlist.dev/e/48AE143C.8030704%40acm.org In-Reply-To: <20080822004052.GA30476@coredump.intra.peff.net> ``` 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 ``` ## Jeff King, 2008-08-22 01:21 Subject: Re: Suggestion: "man git clone" Message-ID: <20080822012112.GA31615@coredump.intra.peff.net> URL: https://gitlist.dev/e/20080822012112.GA31615%40coredump.intra.peff.net In-Reply-To: <20080822011515.GY23800@genesis.frugalware.org> ``` 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 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 ``` ## Federico Lucifredi, 2008-08-22 01:21 Subject: Re: Suggestion: "man git clone" Message-ID: <48AE1489.9050103@acm.org> URL: https://gitlist.dev/e/48AE1489.9050103%40acm.org In-Reply-To: <20080822011515.GY23800@genesis.frugalware.org> ``` Miklos Vajna wrote: > On Thu, Aug 21, 2008 at 08:40:52PM -0400, Jeff King 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 ``` ## Michael J Gruber, 2008-08-22 11:02 Subject: Re: Suggestion: "man git clone" Message-ID: URL: https://gitlist.dev/e/g8m6d1%247nf%241%40ger.gmane.org In-Reply-To: <48ACB29C.7000606@zytor.com> ``` 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 ``` ## A Large Angry SCM, 2008-08-22 11:37 Subject: Re: Suggestion: "man git clone" Message-ID: <48AEA510.6040004@gmail.com> URL: https://gitlist.dev/e/48AEA510.6040004%40gmail.com In-Reply-To: <48AD99DF.5090802@zytor.com> ``` 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. ``` ## Derek Fawcus, 2008-08-22 15:03 Subject: Re: Suggestion: "man git clone" Message-ID: <20080822150353.GC13490@cisco.com> URL: https://gitlist.dev/e/20080822150353.GC13490%40cisco.com In-Reply-To: ``` 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 ``` ## Mikael Magnusson, 2008-08-22 15:53 Subject: Re: Suggestion: "man git clone" Message-ID: <237967ef0808220853k24b2d969l55d04ec13bd7c8c9@mail.gmail.com> URL: https://gitlist.dev/e/237967ef0808220853k24b2d969l55d04ec13bd7c8c9%40mail.gmail.com In-Reply-To: ``` 2008/8/22 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 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 ``` ## Matthieu Moy, 2008-08-25 12:38 Subject: Re: Suggestion: "man git clone" Message-ID: URL: https://gitlist.dev/e/vpqk5e52rrx.fsf%40bauges.imag.fr In-Reply-To: ``` Michael J Gruber 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 ``` ## Federico Lucifredi, 2008-09-04 02:22 Subject: Re: Suggestion: "man git clone" Message-ID: <48BF4662.9000305@acm.org> URL: https://gitlist.dev/e/48BF4662.9000305%40acm.org In-Reply-To: <48ADE2FF.4080704@acm.org> ``` 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 ``` ## H. Peter Anvin, 2008-09-04 03:31 Subject: Re: Suggestion: "man git clone" Message-ID: <48BF5678.8080201@zytor.com> URL: https://gitlist.dev/e/48BF5678.8080201%40zytor.com In-Reply-To: <48BF4662.9000305@acm.org> ``` 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 ``` ## Colin Watson, 2009-06-28 02:34 Subject: Re: Suggestion: "man git clone" Message-ID: <20090628023458.297703BC143@sarantium.pelham.vpn.ucam.org> URL: https://gitlist.dev/e/20090628023458.297703BC143%40sarantium.pelham.vpn.ucam.org In-Reply-To: <48AE143C.8030704@acm.org> ``` (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] ``` ## Federico Lucifredi, 2009-07-06 02:48 Subject: Re: Suggestion: "man git clone" Message-ID: <4A5165F0.8020107@acm.org> URL: https://gitlist.dev/e/4A5165F0.8020107%40acm.org In-Reply-To: <20090628023458.297703BC143@sarantium.pelham.vpn.ucam.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 ``` ## Federico Lucifredi, 2009-07-06 04:11 Subject: Re: Suggestion: "man git clone" Message-ID: <4A517966.1060401@acm.org> URL: https://gitlist.dev/e/4A517966.1060401%40acm.org In-Reply-To: <20090628023458.297703BC143@sarantium.pelham.vpn.ucam.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 ```