Want to read Slashdot from your mobile device? Point it at m.slashdot.org and keep reading!

 


Forgot your password?
Close
typodupeerror
×
Linux Software

Are Manpages Becoming Obsolete? 40

Posted by Cliff from the let's-not-forget-what-has-worked-for-years dept.
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.
This discussion has been archived. No new comments can be posted.

Are Manpages Becoming Obsolete? More

Are Manpages Becoming Obsolete?

Comments Filter:
  • >(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.
  • the inferno [vitanuova.com] OS solves that problem by having prefix-subcomponent entries.

    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.

  • I like the argument of man for quick summaries and something else for manuals. I still say use html for what is currently in info. Then I can use lynx, links, w3m, Netscape, Konqueror, Opera, ... whatever I want. Why must I be forced to use info?

    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
    __

  • 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!)
  • 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!
  • I agree, man pages rock, especially to just look up the signature of a function. And apropos of course (man -k). That make it really easy and fast to compensate for sloppy memory. Fast crucial here, any gui interface to man, like in nautilus, is too slow to be useful. For that kind of reading, html is more appropriate I would say.

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

  • Re:just a TODO in gnome... (Score:3)

    by Lars Arvestad ( 5049 ) on Monday February 26, 2001 @11:00PM (#399401) Homepage Journal
    While not a true GUI solution, (X)Emacs offers the command M-x manual-entry which loads the man-page in a buffer. You may then navigate using scrollbars if you are so inclined and, more importantly, click on references to other man-pages to get those in its own buffer.

    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
    __
  • 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 [worldcom.com] - Generation Duh!

  • Man pages and Info should not compete (Score:3)

    by Lars Arvestad ( 5049 ) on Monday February 26, 2001 @11:09PM (#399403) Homepage Journal
    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
    __
  • 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 %-)
  • Just today encountered the following (possible) deficiency with man pages.

    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?

  • Man pages are my favourite choice of documentation for the nitty-gritty, get it done details. Info is fucking nearly useless and whoever decided on that interface should be shot and pissed on and then have coke poured over them and maybe a bit of cigarette smoke blown on them for good measure.

    DocBook is a promising alternative to that, though.

  • Yeah, I do use that sometimes. You're right, it would be really useful if I made the keyboard-shortcut, and open it up in a new frame. But I'm a bit hesitant to configure emacs too much, it wouldn't be the first time I work all day on custumization 'to increase my productivity'... I do use info often in xemacs, that interface makes me hate info a lot less. Man pages work great in terminals, so that's what I use.
  • Here's a 'symantic' conversion

    s/symantic/semantic ;-)

    --
  • 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 [sourceforge.net]. But recently it moved to a very long term project.

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

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

    You mean like man.cgi that all [freebsd.org] of the BSD [openbsd.org] projects [freebsd.org] use?

  • Hmmm... I wonder if I can hook a spell checker into Galeon? ;-)

  • Linux Documentation Poor; BSD Docs Rock! (Score:2)

    by Anonymous Coward
    The worst thing Stallman ever did for the world was to deprecate man(1) pages. As a result of this action, Linux documentation is in a very sorry state.

    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

  • Errrr, info2html, not inf2html. I got the names confused, since I use OS/2 :)

  • HTML for manpages is especially stupid since Linux does not have an adequate web browser.

    One of my favorite man implementations is on SCO, SCO uses text-only html and runs a dedicated man web server.
  • Something to remember about man pages is that it's trivial to produce a nicely formatted, easy-to-read hardcopy version: <code>groff -man manpage.1 | gs</code>

    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.
  • This is not relevant to man pages, but certain operating systems' [Linux] man pages.

    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/

  • Take a look at man perl -
    For ease of access, the Perl manual has been split up into

    several sections:
    perl Perl overview (this section)

    perldelta Perl changes since previous version
    perl5005delta Perl changes in version 5.005
    perl5004delta Perl changes in version 5.004
    perlfaq Perl frequently asked questions
    etc. In similar fashion, man gmt could reference gmtfoo (for 'gmt foo'), gmt bar, and so forth.

    (*sigh* Even as "Plain Old Text", the formatting is hosed. That's supposed to be two colums above.)
  • Html is fine as an online manual format, as long as the pages are lynx friendly. Lynx starts up quick, runs fast, and most importantly, lynx can use a vi keymap. It has the advantage (over info) of being a standard format that most everyone knows some of, and that has many tools for manipulating/generating it.

    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 [cr.yp.to] standard.
    -russ

  • No! Never! (Score:3)

    by Matthew Weigel ( 888 ) on Tuesday February 27, 2001 @10:17AM (#399421) Homepage Journal

    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:

    • There's no hyper-text linking! Not entirely true. Because references to other man pages are in a standard format, it is trivial to compute references... there are perl scripts out there that turn troff(1)-formatted man pages into HTML with useful links to other man pages reliably and easily. It wouldn't be difficult to forego HTML completely, and simply rewrite the man(1) program to handle these links. In fact, with a slight change to the manner in which references were made, you could even specify sections of other man pages easily, since the sections are standard.
    • Man pages don't give useful information! This is an amalgation of a few complaints, actually - that man pages only discuss commands and APIs, for instance, that they don't include examples, etc. This is not relevant to man pages, but certain operating systems' [linux.org] man pages. If you look at OpenBSD, there are man pages that discuss general issues involved in VPNs(8) [openbsd.org], IPSec(4) [openbsd.org], and even general introductory information (afterboot(8) [openbsd.org]). Man pages suit this sort of topic treatment reasonable well, and lead to more centralized documentation (a real win!).
    • You can't print good books from man pages! OK, true enough. Info, DocBook, etc. are well-suited for writing general books intended to teach. However, Trying to use Info or DocBook documents as references is unpleasant, and involves a lot of poking around for just the link. They essentially serve a completely different purpose.

    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.

  • 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...
  • Well, yeah...

    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!
  • Man pages are good for remembering a function you already know, but they totally suck for learning how to use a function or command. Often the text doesn't even say what the thing does, just that you can pass this or that as parameter... frankly, if Linux people want to spread their favorite OS around, they'll have to make an effort on documentation (and not just howtos, it sucks to open up a browser anytime you just want to do something on the command line)
  • .. Yeah it's pretty exciting that just becuase you want the ability to look up the syntax of a command you have a web server sitting out there waiting for someone to find an exploit for it... ah I mean waiting to find a way into every SCO Box on the planet. Excellent tip there...
  • I've been using gnome-help (I think that's the name, or gnome-help-browser) Which lets you look up man pages, info pages, and gnome help pages in a browser like environment with clickable x-ref. Its got quirks but generally works ok. The syntax it uses is:
    man:
    info:

    I've been meaning to get into the code to try to fix some of the annoying things I find about it.




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







  • I like the argument of man for quick summaries and something else for manuals. I still say use html for what is currently in info. Then I can use lynx, links, w3m, Netscape, Konqueror, Opera, ... whatever I want. Why must I be forced to use info?

Slashdot Top Deals

THEGODDESSOFTHENETHASTWISTINGFINGERSANDHERVOICEISLIKEAJAVELININTHENIGHTDUDE

Close