man pages [LWN.net]

man pages

Posted Sep 4, 2008 10:17 UTC (Thu) by mp (subscriber, #5615)
Parent article: Feature removal sparks Git flamewar

"Because man requires a single argument, the dash style is used there as well, though git help foo is a reasonable alternative."

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

to post comments

man pages

Posted Sep 4, 2008 11:03 UTC (Thu) by epa (subscriber, #39769) [Link] (13 responses)

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.

Darn it, what a fantastic idea! This would also work for perl and solve the ridiculous practice of putting Perl modules in section 1 of the manual. Didn't Tcl use to have /usr/share/man/man1tcl? What happened to that?

man pages

Posted Sep 4, 2008 11:47 UTC (Thu) by mp (subscriber, #5615) [Link] (12 responses)

Going more off-topic.

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.

man pages

Posted Sep 4, 2008 16:56 UTC (Thu) by JoeBuck (subscriber, #2330) [Link] (11 responses)

The eight numbered sections are an artifact of the organization of the original Unix manual, which Bell Labs would send you in book form because typesetting was not available to most users. And yes, I'm old enough to remember, I'm an old fart who used Version 7 Unix on a PDP-11.

I hope we don't have to deal with that forever.

man pages

Posted Sep 5, 2008 22:58 UTC (Fri) by giraffedata (guest, #1954) [Link] (10 responses)

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.

man pages

Posted Sep 6, 2008 3:39 UTC (Sat) by dlang (guest, #313) [Link] (5 responses)

man's killer feature compared to your system is that it doesn't require network access to work.

man pages

Posted Sep 6, 2008 14:47 UTC (Sat) by bronson (subscriber, #4806) [Link] (3 responses)

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

man pages

Posted Sep 6, 2008 16:47 UTC (Sat) by paulj (subscriber, #341) [Link]

Try the 's' search, which searches the entire topic. Additionally, every GNU Info topic has an index page, which you can do a page-search in (the GNU 'info' viewer has a command specifically for searching the index, 'i', but pinfo doesn't seem to).

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.

man pages

Posted Sep 6, 2008 16:55 UTC (Sat) by giraffedata (guest, #1954) [Link] (1 responses)

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

man pages

Posted Sep 6, 2008 23:32 UTC (Sat) by bronson (subscriber, #4806) [Link]

Yes! It seems silly for every piece of documentation to have two links and two different representations: organized by section or all on one gigantic page.

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

man pages

Posted Sep 6, 2008 16:29 UTC (Sat) by giraffedata (guest, #1954) [Link]

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

man pages

Posted Sep 6, 2008 8:42 UTC (Sat) by paulj (subscriber, #341) [Link] (3 responses)

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.

man pages

Posted Sep 6, 2008 17:12 UTC (Sat) by giraffedata (guest, #1954) [Link] (2 responses)

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?

man pages

Posted Sep 6, 2008 23:28 UTC (Sat) by bronson (subscriber, #4806) [Link] (1 responses)

I'm not sure about that... I loathed info even before I really knew much about Archie or the WWW. It had some serious issues:

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

man pages

Posted Sep 6, 2008 23:48 UTC (Sat) by nix (subscriber, #2304) [Link]

info will instantly tell you if keywords are in the documentation. "i
KEYWORD" if there's an index (info documents have keyword indexes), "s
KEYWORD" otherwise.

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

man pages

Posted Sep 4, 2008 13:16 UTC (Thu) by pj (subscriber, #4506) [Link] (2 responses)

I've always thought it was pretty cool that 'git foo --help' would pull up the man page. Yay unix!

man pages

Posted Sep 5, 2008 23:29 UTC (Fri) by giraffedata (guest, #1954) [Link] (1 responses)

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

man pages

Posted Sep 6, 2008 14:54 UTC (Sat) by bronson (subscriber, #4806) [Link]

> It's actually counter-Unix, as the Unix tradition is for --help to give you something more brief than a man page.

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.