Slashdot Mirror
Are Manpages Becoming Obsolete?
Navarre asks: "While I really like the GNOME desktop, and it's good to see that it's being taken up by HP and Sun, I noticed that it's a little weak on manpages. While I know that GNU prefers Info pages, I personally hate them and greatly prefer man. It's bad enough already when half the GNU apps I use refuse to give decent manpages in favour of info. Now GNOME includes help in HTML format, but no manpages that I've seen. Are we now at a point where we cannot survive on a Unix box without some kind of web browser? What happened to that great common-demoninator of a terminal, troff and a pager? The minimum bloat on Linux continues to increase, and I question if it's a good thing. How much trouble is it to include a manpage anyway?" I'm all for better documentation in formats that have richer functionality than troff, but let's not forget that man pages have worked for years and is still standard on just about every Unix system out there. I'm not as much of a fan of GNU Info, but that's probably more due to my familiarity with man than anything else. How do you all feel? Should we retire man for info or HTML (you can always use lynx)? Or do you think man pages still have a place on modern Unix systems?
On a side note, I'm sure maintainers who currently do not have man pages wouldn't mind it if someone out there would take the time to convert whatever has been provided into proper man pages.
-nt
I'm still trying to figure out what people mean by 'social skills' here.
>(Yeah, should code it myself I guess..) You just gave me one of those "Catcher In The Rye" moments. Noooooooo! Don't do it! Save yourself! Once about a gazillion years ago, more or less, I told myself that I should make tarballs magically flesh out while in Windows 95 by simply double clicking on file.tgz or file.tar.gz. I succeeded. However, I spent a big chunk of my life. About the time that I was ready to show my nifty little x-platform sysadmin programming coup to the world, I realized that it was more or less redundant.
for instance, the Sys module is documented in sys-intro(2), sys-read(2),sys-open(2), etc.
man 2 sys gets you sys-intro. this also works for commands, for instance the shell (sh, not the Bourne shell) is documented along with its loadable modules, e.g. sh(1), sh-std(1), sh-expr(1).
i'd concur with the people that like the standard format of man pages - writing a man page forces you to put your thoughts into order, rather than splurge your current mindset. this is great for searching for information.
traditionally, unix has used the "paper" format for tutorial or detailed descriptions of larger commands. the man page for troff, for example, doesn't mention all the troff directives - for that you need the troff paper (/sys/doc/troff.ms on plan 9)
call me a die-hard if you like, but the man page format has survived as well as it has for a reason (actually it predated unix by some time) - it makes for an excellent reference manual. the fact that it uses [nt]roff is not entirely relevant - the important thing is that the sections are standard, so if you want to find info on a command, you know where to look.
Well, you are not really forced to use an Info browser. I just searched using Google and found a site with a info2html tool.
For me, however, the main argument is that there is an excellent info browser in my programming editor and it is very easy to switch from programming to reading. OK, so there is the W3 browser implemented in elisp, but it does not quite cut it for me. The web pretty much need a "real" GUI browser.
And there is no way you will be able to have a ready-to-print typeset manual using an HTML format. If you have a manual in Info, there are sources marked up using texi, and then you have a TeX backend. It is unbeatable for printing quality. To me this is one of the most remarkable aspects of Info. The markup is so carefully chosen that a document is instantly ready for both pleasurable online viewing and printing.
Lars
__
Reality or nothing.
I HATE info. It isn't
intelligent enough to
pay any attention to
the size of the display
(or gnu or redhat
prerendered the pages)
so that everything
is still wrapped to
80 columns.
Man, on the other hand, wraps properly to fill all 132 columns. Just like HTML. (Hail Curses!)
~~~LXT~~~
Life is like a computer program: anything that can't happen, will.
I don't have to access my linux server often but when I do, I need to ref. some command option that I forgot. I need man pages and I don't want them to go away. Long live man pages!
But the gtk/gnome documentation is in sgml. I guess it's not to difficult to generate man-pages from it. Just the way the gtk html-reference is organized would cut it for me: huge man-pages with several functions per page. Just as long as there is a sym-link for every function to the page.
(Yeah, should code it myself I guess..)
Man pages still play an important role because they provide a lot of information in a nice compact space in a standardized manner. That last part is very important in my view. No matter which man page you look at, you can always find the command-line options at the top, followed by a description, and so on. This makes it very easy to find information for any command because it's always in the same place. Neither info docs nor HTML-formatted help files have this same standard structure (or at least I haven't seen it). Granted, GUIs are making command line options less important for everyday program use, but man pages are for me still invaluable when I forget which letter corresponds to which switch. For the quick and dirty help man pages give you, I don't think much more formatting is needed - just keep what works and is easy to use (scroll up and down...no-brainer).
Info files are hierarchical. Man pages are flat. This, info pages tend to be the definitive documentation (doubly so as they can be printed into chapters) and man pages are the concise reference, listing the usage only.
:-)
This is not a format conversion, but a symantic conversion. Try writing a perl script for that.
The 'man' system (including whatis, apropos etc.) is one of the most user-friendly help systems I've ever come across. It would be a pity to see it die because someone thinks the bloat of html, hyperlinks, graphics etc. is in some way "better".
<flamebait>
gnu-info, on the other hand, is downright hostile
</flamebait>
--
Every bloody emperor has his hand up history's skirt [Peter Hammill/VdGG]
I hate having to mess with a browser to read documentation. I also hate info. I use it so rarely that everytime I do use it I have to figure it out again. It's so much nicer just being able to type man and get the information I want.
But I also like HTML help as well. I have looked at info help, but didn't like it as much.
The thing I like about HTML is the ability, which is lacking in man pages, of hyperlinks - when a command or program you are getting help on refers to another command or program, man pages highlight what command/program it is, but there is no simple way to just "go" to that other man page - you have to start another term window and "man" it.
How hard would it be to write a script to replace "man", in say, perl, and this script would perform the function of converting man pages into browsable HTML pages (using Lynx?) or automatically use Lynx if the page is already in HTML, or if the page is info based, convert that? Something like this should be possible.
I can't think of too many systems where you couldn't have a simple browser like Lynx to view help with. HTML makes perfect sense of help files, IMO.
Worldcom - Generation Duh!
Reason is the Path to God - Anon
I don't much about Gnome and their help system, but I think it is sad if they are not using the man pages.
However, one should not see the Gnu Info system as a competitor, as they have totally different purposes. The man page should be fairly short and give you a speedy answer. The Info manual should give you access to complete manuals for large systems. For instance, a complete bash manual does not belong in a man page. Yes, I know it is there, but how managable is it? Then on the other hand, I should not have to use an Info browser to get the command line options for 'cat'.
In Info, you get easily navigated sections, hyperlinks, and a good index system. In addition, a manual set in Info can also be beautifully printed on paper since there is an excellent TeX backend. The result is beyond what you can get using HTML!
Lars
__
Reality or nothing.
Why not to try to write a tool for automated tranlation of HTML or Info to (less rich) troff format? Surely this process is less obvious than the reverse. For HTML, it may take following hyperlinks and aggregating several html files together if they are too small to make separate man entry. Index man page (a la perl's) may be needed for bigger document sets. While the goal seems achievable, I wonder if anybody would care to actually write appropriate code %-)
Computers make very fast, very accurate mistakes
There exists a package of programs for producing maps and charts in PostScript using an entirely command-line interface (GMT). Currently, the package is installed by default as a number of executables, along with man pages for each. However, it was recently discovered that the names of the executables conflict with other names of executables in another package.
One proposed solution was to change the interface so that every command is instead run as "gmt cmdname options" (like CVS). The immediate deficiency with this is that how to organize man pages is no longer obvious (the man page for each command was already quite long enough---we don't want a huge result to "man gmt"). Leaving the man pages the way they are is not an option---the names could still conflict with man pages for other packages. This is, of course, easily solved by info or HTML.
Any alternative solutions?
DocBook is a promising alternative to that, though.
:wq
Here's a 'symantic' conversion
;-)
s/symantic/semantic
--
"It's tough to be bilingual when you get hit in the head."
I agree that man is the best command line documentation format. But the main problem is the multiple sources for documentation formats, as there is man , info , plain text, html and and and. I think all these tools should become interfaces with a single DocBook datatabase and using xslt and similar filters to provide output for every interface. In particular this is a long term project I started on sourceforge called dox. But recently it moved to a very long term project.
Just because I can imagine doing a hippopotamus, doesn't mean I'd like to do it.
Hmmm... I wonder if I can hook a spell checker into Galeon? ;-)
In contrast, the BSD man(1) pages are supreme. They are concise, accurate, and informative. They always exist. They are highly important. As an example of how important man(1) pages are: a significant amount of traffic on the OpenBSD mailing lists is on the best way to concisely express something in a grammatically correct way on a man(1) page.
Unless the Linux world changes soon and rediscovers the unix man(1) page, I personally will be dumping my beloved Linux in favor of the superiorly documented BSD.
Ken Hendrickson
Something to remember about man pages is that it's trivial to produce a nicely formatted, easy-to-read hardcopy version:
groff -man manpage.1 | gsThe other formats might be a little easier to read online, but I've always found the hardcopy versions a little harder to read.
This might be generational - for the first decade of my career man pages were the only option, and I learned the standard C library from a printed version of those pages.
For every complex problem there is an answer that is clear, simple, and wrong. -- H L Mencken
True, but don't pick on Linux too much here. I often telent into my Linux box to check a man page because the AIX man pages are worse!
Texinfo has its place for longer docs - I love the emacs info pages. Remember that it can generate TeX as well as info, so you can get pretty hard copy as well as hypertext, which is pretty sweet. Still, failing to have a man page that at least documents the basic usage is k-lame.
Tom Swiss | the infamous tms | http://www.infamous.net/
Tom Swiss | the infamous tms | my blog
You cannot wash away blood with blood
Still and all, manpages are "the right thing" for basic docs. For html to replace it, we'd need to do the equiv of the manpath for lynx. Setting a default page with an index of available "man" pages would be close, but not as easy as typing "man foo" to get help on foo.
Short version: Use html for more indepth online manuals. Long live man! 'nuff said.
--
If your map and the terrain differ,
trust the terrain.
The man page is dead, simply because there are more HTML browsers than nroff browsers.
See Dan Bernstein's slashdoc standard.
-russ
Don't piss off The Angry Economist
Man pages are extremely adequate for almost every purpose, and most software. There are a few reasonable criticisms, and a lot of unreasonable ones... here goes:
For Gnome, there's no reason to not rely upon something standard like man (or even info) over HTML, when man and info translate much better to HTML than vice versa.
--Matthew
Perl has an interesting solution to that problem; it provides links to sub-manpages indexed off the main page. For heavy users, man perlfunc is quite effective at immediately isolating the section of the very large documentation set that is desired; you might find that a useful way to organize your man pages.
Man pages are essential for people like me, admins trying to make their way in the world without having to rely on someone constantly for answers to things. This sort of behavior doesn't help one learn to be resourceful, and instead increases the reliance on easy answers, not to mention doesn't allow you to learn the full array of options for any given command. When I first started using *NIX, I found the man pages a bit confusing, but now I find them invaluable. Man pages are the equivalent of the dictionary for whatever OS you're using or trying to become familiar with. You're not ever going to learn anything without your dictionary...
Palaces, barricades, threats, meet promises