4 ms·

Unix manpages are fine. If you've read the GNU awk manual vs BSD awk, you'll understand what I mean. GNU awk manual is hundreds of pages long and serves only to

by csmuk 13y ago

Unix manpages are fine. If you've read the GNU awk manual vs BSD awk, you'll understand what I mean. GNU awk manual is hundreds of pages long and serves only to confuse the user. Not only that, half of it is listing differences between GNU awk and other awks which is just mindnumbing. A fine case of cat -v. And don't get me started on glibc. 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? One tool for the job. Edit: cite your sources :) 1 - OpenBSD awk (6 pages if I print preview it): http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&s... 2 - GNU awk (330 pages if I print preview it): https://www.gnu.org/software/gawk/manual/gawk.html https://www.gnu.org/software/gawk/manual/gawk.html

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 ago
      KDE 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 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. 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..
emidln 13y ago
Given how readily good search and navigation exist, I'd much prefer GNU-style awk man pages to BSD-style awk man pages. 15 years ago I taught myself the AWK programming language using "man awk" on a Red Hat Linux box with no network connection. Had the manual been merely a listing of available switches, that wouldn't have been possible. I'd actually prefer it if more languages provided man pages with detailed language as opposed to random assortments of HTML posing as documentation. Always liked perl precisely due to this.
- csmuk 13y ago
  That 6 pages, if you read it, includes the language, all functions, flags and examples. Its possible to digest it fully in a few minutes. It is complete.

by csmuk 13y ago

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 ago
    KDE 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 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. 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..

emidln 13y ago

Given how readily good search and navigation exist, I'd much prefer GNU-style awk man pages to BSD-style awk man pages. 15 years ago I taught myself the AWK programming language using "man awk" on a Red Hat Linux box with no network connection. Had the manual been merely a listing of available switches, that wouldn't have been possible. I'd actually prefer it if more languages provided man pages with detailed language as opposed to random assortments of HTML posing as documentation. Always liked perl precisely due to this.

csmuk 13y ago
That 6 pages, if you read it, includes the language, all functions, flags and examples. Its possible to digest it fully in a few minutes. It is complete.