Suggestion: "man git clone"
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
Quoted 3 lines · H. Peter Anvin hpa-at-zytor.com |Lists|
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...
Signature · 2 lines
Peter Valdemar Mørch http://www.morch.com
Quoted 7 lines · Peter Valdemar Mørch (Lists)
Sorry man that behaviour is the way "man" works. See "man man".
$ git clone --help or $ git help clone
Quoted 5 lines
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
Quoted 8 lines · H. Peter Anvin
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
Quoted 11 lines · Avery Pennarun
[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
Quoted 4 lines · H. Peter Anvin
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
Quoted 7 lines · Jeff King
There is some configuration magic about what is a section. Try
perl -pi -e 's/^SECTION.*/$& git/'
/etc/manpath.configThat 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
Quoted 10 lines · Jeff King
Quoted 7 lines · Jeff King
There is some configuration magic about what is a section. Try
perl -pi -e 's/^SECTION.*/$& git/'
/etc/manpath.configThat 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.
Quoted 5 lines
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
Quoted 5 lines · H. Peter Anvin
Quoted 3 lines
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
Quoted 9 lines · H. Peter Anvin
Quoted 8 lines · Avery Pennarun
[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.
Quoted 8 lines
Quoted 3 lines
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
Quoted 2 lines
-hpa
Quoted 10 lines · H. Peter Anvin
Quoted 9 lines · Peter Valdemar Mørch (Lists)
Sorry man that behaviour is the way "man" works. See "man man".
$ git clone --help or $ git help clonework right?
Quoted 7 lines
Quoted 3 lines
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.
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
Quoted 9 lines · 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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - http://www.lucifredi.com
Quoted 4 lines · Federico Lucifredi
Hello HP,
I have seen this in (funnily enough) a project I manage myself, which
has subcommands structured similarly to Git.
Quoted 9 lines
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
Quoted 1 line · H. Peter Anvin
Federico Lucifredi wrote:
[...]
Quoted 5 lines
Quoted 3 lines
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
Quoted 4 lines
However, at some point we have to be willing to do things other platforms won't, or we'll never do anything new...
-hpa
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected]
Quoted 10 lines · Federico Lucifredi
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.
Quoted 1 line
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
Quoted 2 lines · Jeff King
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
Quoted 2 lines · Jeff King
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.
Quoted 7 lines · Miklos Vajna
Quoted 2 lines · Jeff King
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
Quoted 7 lines · Miklos Vajna
Quoted 2 lines · Jeff King
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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected]
Quoted 9 lines · Jeff King
Quoted 7 lines · Federico Lucifredi
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
....
Quoted 7 lines
Quoted 1 line
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.
Quoted 3 lines
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.
Quoted 4 lines
Quoted 1 line
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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected]
(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.)
Quoted 5 lines · Federico Lucifredi
Quoted 4 lines · Jeff King
Quoted 3 lines · Federico Lucifredi
I am all for bass-ackwards compatibility, and I think the suggestion of going on "man foo bar" :
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
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.
Quoted 5 lines
Quoted 2 lines
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?
Quoted 8 lines
Quoted 4 lines
Quoted 1 line
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,
Signature · 1 line
Colin Watson [[email protected]]
Quoted 4 lines · 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.)
Really? Sorry, I thought I had added you. My bad.
Quoted 11 lines
Quoted 10 lines · Federico Lucifredi
Quoted 9 lines · Jeff King
Quoted 8 lines · Federico Lucifredi
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
....
Quoted 7 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
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 :)
Quoted 27 lines
Using a plain 'git' section for this in order to provoke the happenstance of 'man git clone' working is definitely wrong as far as the manual page hierarchy goes; it means that things like searching for just user commands (section 1) that contain some term will fail. Putting them in section '1git' (i.e. section 1 with a git "extension") would be more in line with how manual pages are typically laid out, and at least with man-db would not require any configuration file changes. However, I think both of these are suboptimal. Section extensions are typically used for things like functions or modules in other programming languages, or sometimes for cases where file names would otherwise clash. I'm not much of a git user myself, but I don't get the impression that most git users think of 'git clone' as analogous to a 'clone' command in a hypothetical 'git' programming language; it's closer to an ordinary user command.
The only case where I've seen subcommands given their own unprefixed manual pages with only the section extension to tell them apart is OpenSSL, with pages like x509(1ssl). IME, this is very confusing and not a good example to follow: firstly, you can't trivially find a list of all the subcommands with something like 'apropos openssl-'; secondly, it's easy to miss that you're dealing with an openssl subcommand unless you keep your eyes peeled.
Short of some mechanism for git to provide a plug-in to man to tell it where to find subpages (eek! potential overengineering alert!), a foo-bar lookup seems tolerable enough.
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
Personally I have never ever wanted to see two manpages from one man invocation, so I have no real problem with that assumption.
I expected as much, and we should have an option to disable the "new" behavior as a safety anyway.
Would you like to suggest an option name for this, so that we can avoid unnecessary divergence? Perhaps something like --separate?
the option to trigger "classic" behavior? How about --no-subpages?
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
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.
Quoted 8 lines
Quoted 3 lines
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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected] - GnuPG 0x4A73884C
Quoted 4 lines · 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.)
Really? Sorry, I thought I had added you. My bad.
Quoted 11 lines
Quoted 10 lines · Federico Lucifredi
Quoted 9 lines · Jeff King
Quoted 8 lines · Federico Lucifredi
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
....
Quoted 7 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
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 :)
Quoted 27 lines
Using a plain 'git' section for this in order to provoke the happenstance of 'man git clone' working is definitely wrong as far as the manual page hierarchy goes; it means that things like searching for just user commands (section 1) that contain some term will fail. Putting them in section '1git' (i.e. section 1 with a git "extension") would be more in line with how manual pages are typically laid out, and at least with man-db would not require any configuration file changes. However, I think both of these are suboptimal. Section extensions are typically used for things like functions or modules in other programming languages, or sometimes for cases where file names would otherwise clash. I'm not much of a git user myself, but I don't get the impression that most git users think of 'git clone' as analogous to a 'clone' command in a hypothetical 'git' programming language; it's closer to an ordinary user command.
The only case where I've seen subcommands given their own unprefixed manual pages with only the section extension to tell them apart is OpenSSL, with pages like x509(1ssl). IME, this is very confusing and not a good example to follow: firstly, you can't trivially find a list of all the subcommands with something like 'apropos openssl-'; secondly, it's easy to miss that you're dealing with an openssl subcommand unless you keep your eyes peeled.
Short of some mechanism for git to provide a plug-in to man to tell it where to find subpages (eek! potential overengineering alert!), a foo-bar lookup seems tolerable enough.
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
Personally I have never ever wanted to see two manpages from one man invocation, so I have no real problem with that assumption.
I expected as much, and we should have an option to disable the "new" behavior as a safety anyway.
Would you like to suggest an option name for this, so that we can avoid unnecessary divergence? Perhaps something like --separate?
the option to trigger "classic" behavior? How about --no-subpages?
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
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.
Quoted 8 lines
Quoted 3 lines
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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected] - GnuPG 0x4A73884C
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
Quoted 27 lines · 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
Quoted 9 lines · 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
Signature · 3 lines
_________________________________________ -- "'Problem' is a bleak word for challenge" - Richard Fish (Federico L. Lucifredi) - [email protected]
Quoted 4 lines · 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:
Quoted 8 lines
man
APR::Brigadewill work just fine, with a file by the same name. This convention is in current use, and would map to
man
git::clonewhile :: 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
H. Peter Anvin venit, vidit, dixit 21.08.2008 02:11:
Quoted 11 lines
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
Quoted 3 lines · Michael J Gruber
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
2008/8/22 Michael J Gruber <[email protected]>:
Quoted 13 lines
H. Peter Anvin venit, vidit, dixit 21.08.2008 02:11:
Quoted 11 lines
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...
Quoted 7 lines
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.
Signature · 1 line
Mikael Magnusson
Quoted 3 lines · Michael J Gruber
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.
Signature · 1 line
Matthieu