Not logged in
Log in now
Create an account
Subscribe to LWN
LWN.net Weekly Edition for May 16, 2013
A look at the PyPy 2.0 release
PostgreSQL 9.3 beta: Federated databases and more
LWN.net Weekly Edition for May 9, 2013
(Nearly) full tickless operation in 3.10
For an ureasonable alternative the manual pages could be placed in a new "git" section (eg. /usr/share/man/mangit/foo.git.gz) and then "man git foo" would work.
Though I cannot believe I could even think of such an anti-FHS blasphemy :->
Posted Sep 4, 2008 11:03 UTC (Thu) by epa (subscriber, #39769)
For an ureasonable alternative the manual pages could be placed
in a new "git" section (eg. /usr/share/man/mangit/foo.git.gz) and then "man
git foo" would work.
Posted Sep 4, 2008 11:47 UTC (Thu) by mp (subscriber, #5615)
In general manpages are put into the eight numbered sections and for disambiguation may have additional subsection/extension specified, so eg. Perl modules have their manpages named /usr/share/man/man3/Foo::Bar.3pm.gz
Now, there are some things which are distribution specific.
Debian man has the -e option to select the subsection, so placing the git manpages in man1/foo.1git.gz would allow "man -e git foo" (and also "man 1git foo") to work, and of course "man foo" if this were the only foo to find.
Fedora man seems not to have anything like the -e option, but some manpages *are* placed in additional section directories there, so man1git/foo.1git.gz with "man 1git foo" would work there.
Of course none of these options looks as cool as man git foo.
Posted Sep 4, 2008 16:56 UTC (Thu) by JoeBuck (subscriber, #2330)
I hope we don't have to deal with that forever.
Posted Sep 5, 2008 22:58 UTC (Fri) by giraffedata (subscriber, #1954)
Man is obsolete in so many ways. Few parts of Unix have endured so long without upgrade.
One problem, as has been pointed out, is its flatness, which not only makes it impossible to go right to information you want (you have to navigate through thousands of lines of the git "page" to find the subcommand you want, or else make git a hundred separate main commands), but also crowds the namespace.
The fact that it can't get the text from the network also places it in olden times. There's lots of information you have to get today by browsing the web that would be much nicer via a quick shell command.
And finally, the source is in the ancient nroff and troff languages, which are now unique to man. And don't hyperlink.
I wrote a replacement almost 10 years ago that is based on Lynx and can find pages locally or on the web, in a hierarchical structure. (It works -- I use it exclusively for locally developed stuff). While I've watched more and more documentation move to the web, I haven't seen 'man' keep up with it. So it's actually getting harder to look something up.
Posted Sep 6, 2008 3:39 UTC (Sat) by dlang (✭ supporter ✭, #313)
Posted Sep 6, 2008 14:47 UTC (Sat) by bronson (subscriber, #4806)
Posted Sep 6, 2008 16:47 UTC (Sat) by paulj (subscriber, #341)
he GNU Info documentation format is pretty nice from the user's perspective (once you use pinfo), shame it never caught on outside of GNU. The Texinfo markup language for producing info docs has some quirks (e.g. having to escape full-stops in some situations), but those could probably be fixed.
Posted Sep 6, 2008 16:55 UTC (Sat) by giraffedata (subscriber, #1954)
[another killer feature that tradition man has that the proposed replacement doesn't is] that you can trivially search the entire topic (page). You ever try to find something in pinfo when you can't remember what page it's on? It gets tedious quick.
You're referring to the fact that in these systems you can (and therefore do) break a manual up into subtopics such as a separate page per subcommand. (Though I haven't actually experienced it with pinfo; when I've used pinfo, the entire topic, e.g. GNU libc, has been one searchable unit).
That's a good point, and one that has always bugged me about the worldwide web too. I don't suppose it would be hard to achieve that by having a browser function to combine the entire tree below the index page into a single document. Then you can still organize the documentation by directory hierarchy and provide direct access to a page, but also be able to browse the entire topic at once.
Posted Sep 6, 2008 23:32 UTC (Sat) by bronson (subscriber, #4806)
That's really good to hear that Info allows you to search whole documents. Last I looked at Info (probably the late 90s), I feel like it could only search by the page you were on or the woefully incomplete indexes. Though, maybe it did, the memory is getting hazy... :)
Posted Sep 6, 2008 16:29 UTC (Sat) by giraffedata (subscriber, #1954)
man's killer feature compared to your system is that it doesn't require network access to work.
My system has that feature. It requires network access only for documentation that is on the network (which is totally unreachable with traditional man). If you have "man pages" in /usr/man, my program reads them from there (still via Lynx, but with a file: URL).
Posted Sep 6, 2008 8:42 UTC (Sat) by paulj (subscriber, #341)
I wrote a replacement almost 10 years ago that is based on Lynx and can find pages locally or on the web, in a hierarchical structure.
You're describing the GNU info format and the Lynx-like 'pinfo' viewer. Try pinfo gcc sometime, or just pinfo to view all available. I think the GNOME help browser also can view GNU info docs.
Posted Sep 6, 2008 17:12 UTC (Sat) by giraffedata (subscriber, #1954)
You're describing the GNU info format ...
Thanks for bringing that up. Info is evidence that almost 20 years ago people recognized that man was outdated. And I believe Info would have taken over the world except for the fact that the worldwide web followed closely on its heels, muted much of its value, and standardized a different markup language.
GNU Info was a heavy influence for me in inventing my own replacement for man-style lookups, but its lack of network capability was the biggest weakness. Using an esoteric source language (compared to HTML) was the next biggest. And you can't do 'pinfo git foo' (hierarchical name space), can you?
Posted Sep 6, 2008 23:28 UTC (Sat) by bronson (subscriber, #4806)
- It's manually laborious. With manpages, when you see an unrecognized keyword in a Bash script: 'man bash' /REPLY. Turnaround time two seconds. With info, you spend minutes clicking forward and back through a hierarchical structure of pages never knowing if you're hunting in the right place or not. The manpage will tell you instantly if the keyword is in the man documentation, info won't really.
- Info documentation tends to contain a lot more philosophical junk and background info that you need to sift through. I'm all for documenting that stuff, just make sure the reference docs come first!
- If you quit the info reader, it took a lot of effort to find your way back to where you were. With manpages, just '334G'.
- The original info reader was quite user-hostile. At least pinfo came along later.
So, I completely agree that manpages are really showing their age and that we need a better system. The system should be optimized for reference documentation though, not the lean-back, chopped up docs that Info, Gopher, Archie, and the WWW are built for.
Posted Sep 6, 2008 23:48 UTC (Sat) by nix (subscriber, #2304)
Most people's complaints about info boil down to "I don't know its
keybindings". This one does too.
(What I really dislike is the way the info format ditches all the nice
layout and formatting in the source texinfo documents.)
Posted Sep 4, 2008 13:16 UTC (Thu) by pj (subscriber, #4506)
Posted Sep 5, 2008 23:29 UTC (Fri) by giraffedata (subscriber, #1954)
I've always thought it was pretty cool that 'git foo --help' would pull up the man page. Yay unix!
As a workaround by git develoeprs for the fact that you can't use the more logical command, 'help git foo', maybe.
It's actually counter-Unix, as the Unix tradition is for --help to give you something more brief than a man page. And the Unix one-program-one-function rule says if you want to display a man page, you should invoke the man page displayer program, not the SCM access program. (That gives you the power to choose the man page displayer, etc.).
Posted Sep 6, 2008 14:54 UTC (Sat) by bronson (subscriber, #4806)
Absolutely true. It would be nice if each Git page started with a good synopsis and maybe a few examples. If those don't answer your questions, you can keep reading.
> And the Unix one-program-one-function rule says if you want to display a man page, you should invoke the man page displayer program, not the SCM access program.
This is only true for typical medium-complexity tools. Man is simply insufficient for more complex programs (most other scms, gdb, etc). At least Git still uses man! gdb and svn require you to use a different reader entirely.
Copyright © 2013, Eklektix, Inc.
Comments and public postings are copyrighted by their creators.
Linux is a registered trademark of Linus Torvalds