4 ms·
Even the document I cited conceded that there are some very good Unix man pages — BSD Awk may very well be one of many, I have not read it. It follows, logical
by teddyh 13y ago
Even the document I cited conceded that there are some very good Unix man pages — BSD Awk may very well be one of many, I have not read it. It follows, logically, that there could be some very bad Info documentation manuals, and the GNU Awk manual may very well be one of many; I have not read it.
This does not disprove the point the citation made; namely, that the Unix man page structure is unsuitable for many things since its structure tends to make people write manuals badly, and there is no place for the kind of introductions and tutorials that good manuals should contain. On the contrary, the man page format lends itself to very strict and terse reference documentation, which is not what I would call a “manual”, as such.
Someone should perhaps do a study of which of the two formats seem to generate the better documentation.
> The bit that pisses me off is: man awk (see info awk instead). I think they fixed that but it was a pain in the butt for years. Is it in man or is it in info?
The official GNU system documentation is in Info. Now, the GNU system is meant to be compatible with Unix, and Unix uses man pages. And since many GNU tools were (and are) not actually developed to be used in the GNU system as such, but instead find their major use and development as parts of various Unix variants, it follows that most of them have Unix have man pages too. Since writing documentation is work, and writing duplicated documentation is even more work, the man pages for GNU tools are often overly terse, incomplete and/or out of date compared to the Info documentation, which is the official documentation. Some well-known exceptions exist, notably GNU Bash does not have any Info documentation, but instead has an (enormously long) Unix man page.
- nodata 13y ago> The official GNU system documentation is in Info There is nobody in the world outside of the GNU foundation who prefers using info pages to man pages.
- teddyh 13y ago(You are demonstrably wrong, but I will address your implied point instead of your hyperbole.) I think that the hostility to Info comes from exposure to the standalone Info reader. It is non-intuitive, non-Unix-like, and does, as far as I know, not even support text attributes, so it looks bad even for a text-based UI. It is not very newbie friendly (like GNU nano with its very explicit menus to guide you). Nor is it consistent with other Unix-based text UIs like “vim” or “less”. Instead it behaves like a brain-damaged Emacs, but without even many basic text-navigation features from Emacs, so even Emacs users feel lost in Info. I feel that if someone made a module for vim or something to read and navigate Info documentation (and made it the default instead of the barebones standalone Info reader), then Unix people would warm up to Info documentation. Personally, I read Info documentation using the Emacs built-in reader. It is, unofficially I think, the canonical Info documentation reader, and it is beautifully integrated with Emacs. I prefer reading most manuals this way (if they have an Info version).
- mpyne 13y agoKDE also has an interface to GNU Info pages. "info:foo" in Konqueror/Rekonq/etc. and you get hyperlinks and text. It's probably not nearly as good as emacs, but it's not nearly as bad as info(1).
- clarry 13y agoMy problem with info is the document structure. The manual for each application seems to be structured so differently with topics under specific titles and subtitles, I always get lost and it takes me a while to find the thing I'm looking for. And it really is frustrating to stumble in the dark looking for that one command line flag or input format that you've found and used many times before. For me the consistent reference-like structure and terse language of man pages is ideal. The whole document is shorter than a bunch of info pages will be, and because of the structure, I always know where to expect specific things to be. Some man pages do not quite fit the traditional model so there is a bit of compromise, but I still find it easier to scan through such pages and remember the location of things than I do with info pages. The difference between (Open)BSD and GNU/Linux world man pages is that the former group spend plenty of effort on polishing the language & structure to make the text clean, short and to-the-point, as well as consistent. So exactly the qualities I prefer man for are taken as far as possible. And because we love well written man pages, there's a man page for damn well near anything in the base system; whereas on other systems you're sometimes looking at info pages, sometimes html documentation installed where-ever or nowhere, READMEs, comments in config files, howtos and tutorials via Google, or at the source because nobody bothered write real documentation. If the source isn't at hand or you don't have the time for it, you try imitate what you see in use already, and pray..
- teddyh 13y ago> My problem with info is the document structure. The manual for each application seems to be structured so differently with topics under specific titles and subtitles, I always get lost and it takes me a while to find the thing I'm looking for. Use the index – it’s what it’s there for. In the usual Info readers, it’s the “i” key. This is what I use when, for instance, reading the GNU C Library manual and wanting the documentation for a specific function, struct or macro. If you want the command-line switches for the “foo” command, the node to go to in the manual you find yourself when invoking “info foo” is called “foo invocation”; you go to a specified node using the “g” key. Then you simply use the space key to navigate serially through all the following nodes. There are only three more keys that I use when reading Info documentation.¹ I think it’s mostly a question of habit. Man pages has taught you to read mostly the whole document quickly, while scanning for the information you need. These are habits unsuitable to both to reading a book of printed documentation or Info documentation. If you have a specific idea of what you want to find, you use the index. 1) The “l” key – “l” for “last” – corresponds to a web browser’s back button, the “u” key goes “up” in the document tree, and the “t” key goes to the top of the current document. These five keys are all the keys I use for Info navigation, except for normal searching with C-s, but that’s Emacs. This should not be difficult, but it is. I suspect, as I wrote previously, that it’s not Unix-y enough.
- ghshephard 13y agoI'll pile on with an additional anecdote - in 17 years of working almost daily with *nix/BSD systems (and hitting man pages routinely) - I've never once looked at an info page.
- sigzero 13y agoDitto! I have always read man pages. Never read an Info one and I fail to see any need to do so.
- ams6110 13y agoObligatory xkcd http://xkcd.com/912/ http://xkcd.com/912/
- cmccabe 13y agoIf 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.
- teddyh 13y agoAn 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 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.