4 ms·

Most official GNU project software usually has pretty solid GNU info documentation. But, of course, GNU/Linux has a lot of major not-GNU pieces like the Linux k

Most official GNU project software usually has pretty solid GNU info documentation. But, of course, GNU/Linux has a lot of major not-GNU pieces like the Linux kernel and systemd. I can't place it, but I seem to remember Richard Stallman stating in some early GNU project goals that he'd seen much software usefulness hindered by poor documentation and made it a notable priority for the GNU project to have good documentation from the beginning. GNU manuals online: https://www.gnu.org/manual/ https://www.gnu.org/manual/

SoftTalker 4y ago
The bifurcation of GNU documentation between info pages and man pages is endlessly frustrating. WHY do we need a separate info system? Just put the relevant information into the man page.
- throwaway81523 4y ago
  Man pages were a Un*x thing. GNU wasn't supposed to have bifurcated documentation: its official doc format was (is) texinfo, from which info pages and printed manuals are generated. People kept writing man pages anway, of course. But the proper question is "WHY do we need a separate man page system? Just put the relevant information into the texinfo manual". Particularly: man pages were fine for PDP-11 Unix utilities, when they were formatted with nroff/troff and the printed versious usually literally fit onto one page (a few of them ran over into two pages). So they don't have any navigation features, TOC's, indices, or whatever. That fails badly when the man page is large: I see rsync's is 4341 lines (72 pages) and bash's is over 100 pages. There are many other large ones as well. The only way you can find stuff in a large man page is search the text, which is a pain because there is no metadata to distinguish the search hits. Texinfo on the other hand produces navigable hypertext doc and an organized printed manual with an index, TOC, cross-references with page numbers, and so on. So it is a much superior format.
  - ninjin 4y ago
    It all sounds great in terms of a format. But if it is so superior, how come even on the GNU “home turf” we are still mainly using man pages in 2022? Is it not a classic example of “worse is better”? Where man may have major obvious flaws, but it is simply just good and standardised enough so that texinfo simply can not displace it despite its advantages.
    - spijdar 4y ago
      I think it's definitely a case of "worse is better", not because it's "good enough" but because man pages are just "plain text" without the ToC or hyperlink features of texinfo. There is no interface, it's just blasted into a pager and you use the familiar interface of less or more or whatever to navigate. It's the difference between man/less showing '(press h for help or q to quit)' and Info showing 'Type H for help, h for tutorial.' I accept Info's technical superiority, but I've never intentionally used it because man/less works well enough without having to learn a new interface. (the other elephant in the room is HTML/web browsers, which I think eclipse Info in reach and familiarity so much that no-one would want to learn a secondary rich-text hyperlinked document viewer)
      - somat 4y ago
        An interesting tangent to this. The openbsd manual renderer (mandoc) creates less tags which can help on some of the bigger pages (ksh, pf.conf, ifconfig) An example: to get to the inet option in ifconfig, the normal '/inet' search will have a lot of false positives. but the tag ':tinet' search goes to the item in question. Nothing against gnu info pages but I always preferred man pages as it feels like less cognitive effort to use. The less tags are indicative of openbsd culture where they try to improve existing systems. linux(due to it's development model) has a tricky problem where it is very hard to improve anything. you can only create something new and abandon the old.
        SoftTalker 4y ago
        TIL about "less tags" This is a big help in reading openbsd docs, where they tend to put a lot in one page. For example, linux will split up the openssl man pages, one for each subcommand. OpenBSD has one page. With less as my PAGER, hitting :tx509 makes that a lot easier. Also discovered you can do this: man -O tag=x509 openssl Thanks!
  - rleigh 4y ago
    The problem with Texinfo is that it predated HTML and is now thoroughly obsolescent. There is value in being able to generate a printed book, and to have other formats. But the generated Info format is completely eclipsed by HTML. It existed in a world where we weren't allowed to have proper figures or tables, and linking was very limited. A world like a traditional Emacs buffer. The "info" viewer was despised, and with good reason. None of this is not to say that GNU didn't do a good job with documentation. The documentation is often excellent. But the documentation format and tooling needed replacing two decades ago. Texinfo is an anachronism. It's painful to author (I have written a Texinfo manual, later replaced by DocBook) and limited in its output capabilities. But today we have Sphinx and other tools which are greatly superior in their ease of use and capabilities. While in some respects Texinfo was more structured than troff dot codes, it was at the same time vastly less flexible with its formatting, figures, tables and equations. troff let you use tbl, pic and eqn etc. I personally find it easier to search a single massive manpage than hunt through all of the Info nodes. The nagivigability of Info documents is atrocious. But that's all ancient history. Both troff and Texinfo are several decades out of date at this point. Arguing which is better is pointless when both have been eclipsed by far superior replacements. Which can generate manpages, HTML and PDFs with ease.
    - anthk 4y ago
      Mandoc it's far easier than plain Troff/Groff and it can export to PDF and/or HTML5 perfectly.

SoftTalker 4y ago

The bifurcation of GNU documentation between info pages and man pages is endlessly frustrating. WHY do we need a separate info system? Just put the relevant information into the man page.

throwaway81523 4y ago
Man pages were a Un*x thing. GNU wasn't supposed to have bifurcated documentation: its official doc format was (is) texinfo, from which info pages and printed manuals are generated. People kept writing man pages anway, of course. But the proper question is "WHY do we need a separate man page system? Just put the relevant information into the texinfo manual". Particularly: man pages were fine for PDP-11 Unix utilities, when they were formatted with nroff/troff and the printed versious usually literally fit onto one page (a few of them ran over into two pages). So they don't have any navigation features, TOC's, indices, or whatever. That fails badly when the man page is large: I see rsync's is 4341 lines (72 pages) and bash's is over 100 pages. There are many other large ones as well. The only way you can find stuff in a large man page is search the text, which is a pain because there is no metadata to distinguish the search hits. Texinfo on the other hand produces navigable hypertext doc and an organized printed manual with an index, TOC, cross-references with page numbers, and so on. So it is a much superior format.
- ninjin 4y ago
  It all sounds great in terms of a format. But if it is so superior, how come even on the GNU “home turf” we are still mainly using man pages in 2022? Is it not a classic example of “worse is better”? Where man may have major obvious flaws, but it is simply just good and standardised enough so that texinfo simply can not displace it despite its advantages.
  - spijdar 4y ago
    I think it's definitely a case of "worse is better", not because it's "good enough" but because man pages are just "plain text" without the ToC or hyperlink features of texinfo. There is no interface, it's just blasted into a pager and you use the familiar interface of less or more or whatever to navigate. It's the difference between man/less showing '(press h for help or q to quit)' and Info showing 'Type H for help, h for tutorial.' I accept Info's technical superiority, but I've never intentionally used it because man/less works well enough without having to learn a new interface. (the other elephant in the room is HTML/web browsers, which I think eclipse Info in reach and familiarity so much that no-one would want to learn a secondary rich-text hyperlinked document viewer)
    - somat 4y ago
      An interesting tangent to this. The openbsd manual renderer (mandoc) creates less tags which can help on some of the bigger pages (ksh, pf.conf, ifconfig) An example: to get to the inet option in ifconfig, the normal '/inet' search will have a lot of false positives. but the tag ':tinet' search goes to the item in question. Nothing against gnu info pages but I always preferred man pages as it feels like less cognitive effort to use. The less tags are indicative of openbsd culture where they try to improve existing systems. linux(due to it's development model) has a tricky problem where it is very hard to improve anything. you can only create something new and abandon the old.
      - SoftTalker 4y ago
        TIL about "less tags" This is a big help in reading openbsd docs, where they tend to put a lot in one page. For example, linux will split up the openssl man pages, one for each subcommand. OpenBSD has one page. With less as my PAGER, hitting :tx509 makes that a lot easier. Also discovered you can do this: man -O tag=x509 openssl Thanks!
- rleigh 4y ago
  The problem with Texinfo is that it predated HTML and is now thoroughly obsolescent. There is value in being able to generate a printed book, and to have other formats. But the generated Info format is completely eclipsed by HTML. It existed in a world where we weren't allowed to have proper figures or tables, and linking was very limited. A world like a traditional Emacs buffer. The "info" viewer was despised, and with good reason. None of this is not to say that GNU didn't do a good job with documentation. The documentation is often excellent. But the documentation format and tooling needed replacing two decades ago. Texinfo is an anachronism. It's painful to author (I have written a Texinfo manual, later replaced by DocBook) and limited in its output capabilities. But today we have Sphinx and other tools which are greatly superior in their ease of use and capabilities. While in some respects Texinfo was more structured than troff dot codes, it was at the same time vastly less flexible with its formatting, figures, tables and equations. troff let you use tbl, pic and eqn etc. I personally find it easier to search a single massive manpage than hunt through all of the Info nodes. The nagivigability of Info documents is atrocious. But that's all ancient history. Both troff and Texinfo are several decades out of date at this point. Arguing which is better is pointless when both have been eclipsed by far superior replacements. Which can generate manpages, HTML and PDFs with ease.
  - anthk 4y ago
    Mandoc it's far easier than plain Troff/Groff and it can export to PDF and/or HTML5 perfectly.