Hacker News Reader

Comment by cmccabe | Hacker News Reader

If I want an introduction to complex topic, I usually won't use man pages. I will open up a web browser and search. That will give me web pages that have pictures, diagrams, and possibly even introductory essays about the topic.

There are many more people who know how to write web pages or forum posts than who know how to write "info" pages. There are also great tools for searching the web, but poor tools for search info pages. "info" pages can't even have diagrams or pictures. Consequently, information obtained via "info" tend to be stale, incomplete, and generally unhelpful.

The real question is why "man" pages are still useful in the era of the internet. The answer is that sometimes, you want a concise, accurate, quick reference to what is installed on your system. "man" fills this function admirably. "info" fills that function awkwardly and poorly.

View on HN

This is true for me too as long as I don't use OpenBSD. The cause is that GNU/Linux manpages are horrible. They are mostly outdated and not in sync with the versions that are actually installed.

As soon as you log in to your newly installed OpenBSD system, your root account has a mail in her mailbox stating to read the "afterboot" manpage. When I first time entered "man afterboot" in my shell, I was blown away.

http://www.openbsd.org/cgi-bin/man.cgi?query=afterboot

  The idea is to create a list of items that can be checked
  off so that you have a warm fuzzy feeling that something
  obvious has not been missed.

It gives you a fast introduction with all informations you need and then references all locations where you find every other topic. At that point, you don't need google anymore where you again find outdated and incorrect informations.

The documentation is so high quality that this is the biggest advantage I appreciate the most.

Yeah. One thing that some people seem to miss is that you can have multiple man pages for a topic-- perhaps one that lays out the general outlines, and one for more specific information.

git does this: it has "man gittutorial" and "gitcvs-migration", as well as man pages for each command. It makes a lot of sense and avoids the "giant wall of irrelevant text" approach.

Bash, on the other hand... yeah. Just try finding anything in there.

An internet search will give me many different choices of documentation of unknown provenance, authorship, official status, datedness, accuracy, and comprehensibility. This, to me, is not helpful, since I have no way of knowing which are any good, even after reading them. On the other hand, Info documentation will give me the official, up-to-date, correct, and mostly well-written documentation.

Internet searches certainly have their place if I want forum posts, mailing lists or blog posts, which I sometimes do. But I often want the official documentation corresponding exactly to my installed version of the software, and this is often harder to find using a web search than simply using the Info documentation, because of the above issues. Also, something to keep in mind in these modern times is that web usage is monitored. Local reading of Info documentation is not.

Tools for searching Info pages are built-in to most Info browsers. I use the Emacs Info browser, which has both the usual Emacs way of searching (C-s and C-r searches both in the current node and in the whole document), and the Info Index, which is what I start with when looking up the reference documentation for something.

Also, contrary to what you claim, Info documentation can and do contain images. For example, the HTML GnuTLS documentation here: (http://gnutls.org/manual/html_node/OpenPGP-certificates.html) was generated from Texinfo, and the images are still there when I browse the corresponding Info documentation with the Emacs Info reader. Those images are simple because they are generated from Dia drawings via EPS files, but images can be anything, just like in HTML.

An internet search will give me many different choices of documentation of unknown provenance, authorship, official status, datedness, accuracy, and comprehensibility.

True. But the documentation for GNU programs, both man and info, is often also "of unknown provenance, authorship, datedness, accuracy, and comprehensibility." You even said yourself that the man pages for many of these GNU programs are years out of date on some systems. Official status is not guaranteed either, since anyone can fork an open source program and produce a clone.

Somehow, despite all that, we manage to muddle on. Probably, it's because we're humans, with the ability to filter out bad information and incomprehensible explanations, and find the real information. And in my experience, this is much easier to do with a man page, which usually simply gets to the point, than with a long, meandering info page which treats me like an idiot and yet often fails to mention vital information.

Thank you for the clarification that info pages can support images. Since I have only ever used info in a terminal, I was not aware of this.

In a lot of ways, info reminds me of Microsoft's CHM format, another HTML workalike with limited abilities. CHM can also support images.

Web usage may be monitored, but I suspect that searching for information about open source programs won't reveal anything about me that downloading Linux did not.

Reply on news.ycombinator.com