Are Manpages Becoming Obsolete? 40
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.
I thought that info files should be src for man ? (Score:1)
Re:just a TODO in gnome... (Score:1)
Re:man page deficiencies? (Score:1)
for instance, the Sys module is documented in sys-intro(2) [vitanuova.com], sys-read(2) [vitanuova.com],sys-open(2) [vitanuova.com], 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) [vitanuova.com], sh-std(1) [vitanuova.com], sh-expr(1) [vitanuova.com].
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.
Re:Man pages and Info should not compete (Score:2)
Well, you are not really forced to use an Info browser. I just searched using Google and found a site with a info2html tool [dartmouth.edu].
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
__
Re:Man pages and Info should not compete (Score:1)
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!)
Re:Long live the man pages! (Score:1)
just a TODO in gnome... (Score:1)
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..)
Long live the man pages! (Score:1)
Re:Format conversion (Score:1)
This is not a format conversion, but a symantic conversion. Try writing a perl script for that.
User Friendly (Score:1)
<flamebait>
gnu-info, on the other hand, is downright hostile
</flamebait>
--
I hope man pages don't go away (Score:1)
Re:just a TODO in gnome... (Score:3)
Make sure to have keyboard shortcut for that command in your C-mode. It makes for a speedy lookup of the function name you have by the point.
The strength of using man-pages in an emacs buffer become apparent when repeatedly working with very long man-pages.
Lars
__
I like man pages... (Score:2)
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 [worldcom.com] - Generation Duh!
Man pages and Info should not compete (Score:3)
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
__
info2man or html2man? (Score:1)
man page deficiencies? (Score:1)
There exists a package of programs for producing maps and charts in PostScript using an entirely command-line interface (GMT [hawaii.edu]). 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?
Re:DocBook ! (Score:1)
DocBook is a promising alternative to that, though.
Re:just a TODO in gnome... (Score:1)
Re:Format conversion (Score:1)
s/symantic/semantic
--
DocBook ! (Score:1)
Re:I like man pages... (Score:2)
Similarly, there's a CGI script called inf2html that converts GNU info documentation into HTML. Between the two, you can have a single semi-unified portal to all standard documentation available online. Not sure of where it canonically is located, but I bet google can tell you.
Re:I like man pages... (Score:2)
You mean like man.cgi that all [freebsd.org] of the BSD [openbsd.org] projects [freebsd.org] use?
Re:Format conversion (Score:1)
Linux Documentation Poor; BSD Docs Rock! (Score:2)
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
Re:I like man pages... (Score:1)
Errrr, info2html, not inf2html. I got the names confused, since I use OS/2 :)
Re:User Friendly (Score:1)
One of my favorite man implementations is on SCO, SCO uses text-only html and runs a dedicated man web server.
pretty hardcopy (Score:2)
The 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.
Re:No! Never! (Score:2)
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/
Re:man page deficiencies? (Score:2)
(*sigh* Even as "Plain Old Text", the formatting is hosed. That's supposed to be two colums above.)
Lynx as "man" (Score:1)
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.
Browsers killed the man page (read about slashdoc) (Score:2)
See Dan Bernstein's slashdoc [cr.yp.to] standard.
-russ
No! Never! (Score:3)
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.
see the perl(1) manpage for an example. (Score:1)
I don't know what I'd do with no man pages (Score:1)
Re:I like man pages... (Score:2)
Thanks for the links - someone mod this up!
I should set this up on an internal server on my home system - it rocks!
Worldcom [worldcom.com] - Generation Duh!
Re:just a TODO in gnome... (Score:1)
Re:User Friendly (Score:1)
Re:DocBook ! (Score:1)
man:
info:
I've been meaning to get into the code to try to fix some of the annoying things I find about it.
Re:Long live the man pages! (Score:1)
Jesus suffering fuck, child! Just how is that flamebait?
Do you expect the fuckwit slashbots to go around writing detailed, over-emotional rants in response to every jesus-themed banality they read?
No - you don't.
So why mark it as flamebait? Do you suffer from the moderator's equivalent of Tourette's Syndrome, perhaps? Or are you just a fucking wankstain with no life?
Probably a mixture of the both, yes?. See? It's nice to find a good, "third way" reason behind your diseased moderation.
So, fuck away off until you've learnt to control yourself.
Oh, and, btw - did my post actually attract any flames? No. Did your moderation? Um, yes. Arsehole.
Re:Man pages and Info should not compete (Score:1)