I second the motion! It's hard enough figuring out how to use programs without having to hunt for docs. I think these modern devs assume we're all going to Google for help and don't need to bother.

Wow, I'm glad to know I'm not the only person who thinks that 'info' really bites it! Info is my last resort because it's so doggone hard to use. (strangely, I'm a vi lover and I still hate info--maybe if it used vi commands for navigation I'd feel more at home! :)

Yeah, you guys should stick with UNIX and BSD. ;)

Try comparing section 3 man pages! ( getaddrinfo(3) is a good example)

I agree. A single standard format (and I think man pages qualify) can be converted to any other desired format on-demand if needed. As you mentioned KDE does this, and I think Apache comes pre-configured to do this as well (at least it did last time I installed it on Debian).

I cringe every time I have to go looking in the info pages.

Amen! OpenBSD sets the standard for man pages and system documentation. Linux distros could learn a lot from Theo's passion/obsession w/documentation.

Couldn't agree more!
But I guess man pages will go away -- maybe slowly, but they will.
--pat

Agreed, man pages are great.

Maybe we, the man-page loving community, should start (a project) to convert different kinds of documentation to man pages for packages that have none and get them included in packages and distributions.

This is so true.

Me too! Man pages have a more-or-less (no pun intended) standard layout, with commonly needed information near the top. I love the 'bugs' section in man pages too; somehow the fact that the documentation has a bugs section gives me confidence that i'm working with a quality product

There are some examples of overly long pages such as the one for sh, but generally man pages are much better than the book format that we so often encounter in MS-Windows, gnome and kde. Not to mention the pile of various things commonly found under /usr/share/docs
I do like a hypertext facility, but info(1) misses the target.

An important point to remember is that "man page" does not mean "typing *roff". We can write docs in high-level languages such as Docbook or POD and then having them automatically translated in man pages, HTML documents, etc.

Writing *roff will probably become a lost art. But man pages may survive.

I couldn't agree more!

I agree whole-heartedly. I love man, can't seem to navigate info, and hate the HTML pages.

testing, testing, where have all the comments gone?

I agree, man pages are great and I hope developers keep writing them. It's my reason to use OpenBSD.

we Must not loose man pages.

others might like the html, but it is not always handy.

often when I am at my dual head work terminal, I have a google open.
and if I need to look something up it is often: man Xorg

I enter that in google. and read a man page in a web browser.
still my favourite way to get the info I need.
the layout is consistent and tight, not full of fluff.

so my question is, what can We do about it collectively?

I still use man pages daily, and you are right, "info" sucks. I truely hope man isn't an endangered species.

Nice to see someone else uses the term arse - Commitments fan? Oh yeah, I want man pages too. Too often, HTML pages are autogenerated crap.

I couldn't agree more. Info sucks. Even in emacs.

Thanks for the article!

Amen sister.

Too right. I've been using man pages for coming up to 20 years now on I don't know how many different machines. There used to be a time when you went up to a machine running any flavour of Unix and you'd get by with man.

I've tried so hard to like info but it's just impossible. It looks to me like a solution looking for a problem.

absolutely I swear mildly to myself whenever I have to use info or html docs greping these is horrible.

Amen.

I can't agree more! I work with a lot of servers and it is really frustrating to find html docs with not only no web server anywhere near, definitely no gui in sight, and it would be a pain to have to go through and setup the directory to serve them anyway. I end up having to install lynx, which they generally didn't even bother considering as a browser when they wrote the docs in the first place, so it's practically unreadable anyhow. info may work for emacs users, but for the rest of us, it's just something that you can't get out of once you get into and is needlessly complex. KISS!

info can use VIm keys:

info $file --vi-keys

I love manpages, but like the ubiquity of them over html. I have to go against the flow and state that info pages can be quite usefull.

HOWEVER. Only when viewed with a decent browser. Info (capital I) - the documentation format, seems very good when well written (not entirely uncommon). info (1) - the viewer (eg /usr/bin/info), is terrible however. I think most peoples hate of info is hating info, not Info.

I suggest everyone try pinfo before passing judgement on Info. pinfo will try to load the Info page, and if that fails, it'll try the manpage (or -m to default to manpage viewing). It provides a lynx-like interface, and is a superior manpage browser than 'man' (imho anyway, mainly because it makes the "see also" links clickable and navigatable. :)

Hope people find this of some assistance.

--Nemo

Right on, man pages... ever try

>man woman

or better yet

>man man

If it ain't broke...

Um... ever heard of Lynx or Links? Using a console doesn't mean you can't render HTML.

Is there a man page for the Bourne again shell? Is it "man bash" - or is that too sexist for this forum?

i agree, but one thing i really miss is more examples in the man pages, more like HOWTO's

Man pages lack a lot of things: diagrams, detailed usage samples, ...
Man pages do require dedicated configuration, at least by the MANPATH environment variable.

Moreover, they are tied to a particular machine/host, thus you might get them on this machine, not on its neightbour, depending of the installation mode used.

HTML man pages are available from editors on a central web place and you can get them when desired, if you have a network connexion.

So, I agree that we need man pages, but not the ones localy installed, but the ones centrally installed and remotely reached when required.

I also miss man pages. They're esp. great for short- to medium-length docs and it's hard to beat "man foo" for findability.

However, I also love info files. They're my favorite way to look up the details of some Python module I haven't used for months, and I also like them for commands that have a zillion options, like gcc. I use emacs, so that's what I usually read info in, and I think it's pretty good.

I wholeheartedly agree with this. I loath info pages, and most of the Linux boxes I set up have no GUI, so HTML is worthless.

pinfo(1) is a nice tool to read the info pages, but man(1) pages are better if only because they don't make up & back considerations. but man pages still need to be done right. Not including a "bugs" or "errata" section or a "see also" or a "files" -- well, without such peices of information, how does one get anything done?

that said, the most absurd problem i've seen with info pages is that the manpage is precisly the same as the info page, including the exortation to use info instead of man.

And I thought I was the only one left, who loves to read man pages. They have been the guiding light all throughout my long run of fun with software development. Wouldn't agree more with keeping the man pages alive.

yeah that nice man pages, but too bad if u don`t know how to read them becouse you don`t have a reader and just the binary files. and everything you find in google about man is just this article or things like 'read the man page for ...' i never liked man pages becouse they r less portable less comfortable to view, html docs are more comfortable and you also just can view online documentations.

I like man pages because they are brief. You flash in and out of them.
Info is fine if you want to STUDY documentation, but info is not substitute for a decent man page. Info fell short. They tried to come up with a better format, but it isn't much more useful than man pages.

I like man pages because I don't have to mentally context switch. Info pages force my brain to enter "Info" mode.

I think there is agreement on your thoughts about info pages. I'm not finding nearly as many info pages packed in the programs for Ubuntu as I once did in Debian. Is it my imagination, or are the package maintainers leaving them out? I like looking at them with pinfo and have generally found the information easier to understand than what is in the manpages.

Hooray for living in the past!

GOD YES. Have you ever tried to quickly figure out how to do something with tar using the info pages at the command line? It's a nightmare! What a gross waste of time trying to navigate around the levels and sections just to find the list of options and explanations.

Manpages are a breeze to use as a reference. If I want to read a book on tar, yeah I'll go to the info pages with a browser. Take a look at this - and imagine trying to refer to it via a command line view: http://www.gnu.org/software/tar/manual/html_section/tar.html That is NOT a reference, that's a book.

Furthermore navigation is totally non-standard and un-intuitive - one has to spend 15 minutes reading the info info page just to learn how to scroll up, and God help you if you accidentally go up or down a node level.

We must have a quick reference at the command line. Info pages are totally not acceptable for that. Info pages are books. They remind me of a deep complex gopher site, just not as nice to get around.

My rant on manpages, whatever you use for a pager, ctrl-c should leave the content on the screen, they should have meaningful examples (there are programs that "compile" rsync command lines, ya' know I might just want to do something simple and straight-forward once in a while, not sift through the entirety of all the possibilities your very impressively flexible program has), and UNIX-like means manpages, require them. As man pages are a dying art in the Linux world, OpenBSD will probably be my refuge for the foreseeable future. I've been searching for some man page standards, (to steal for another internal project), and I am quickly finding that Google doesn't answer all questions.