4 ms·

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

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!
- throwaway81523 4y ago
  One issue is that the main info browser is in Emacs, so if you're not an Emacs user, Info pages aren't that accessible. There is a standalone info browser but it's not as nice as the Emacs one. And there are html converters but those are even worse. Back in the day, I doubt that it occurred to anyone that a lot of GNU users might someday not use Emacs. I do constantly use the Info documentation for Org-mode and a few other things, but it is observable (and annoying) that some large GNU programs like bash are documented only as man pages afaict.
  - welterde 4y ago
    The standalone info browser really isn't that bad and neither are the generated html page(s) (especially now that they applied some light CSS) and also the generated pdf look fairly good. GNU bash also has fairly good info documentation.
- tpoacher 4y ago
  I recently decided to finally spend roughly 5 minutes to learn how to navigate around info manuals. Afterwards I was like, wow, where has this been all my life??? So my answer to your question would be inertia.
- hulitu 4y ago
  Because the info pages (although claimed otherwise) had the same info like man pages, with very few exceptions. And navigating info pages was a pain.
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.

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!
throwaway81523 4y ago
One issue is that the main info browser is in Emacs, so if you're not an Emacs user, Info pages aren't that accessible. There is a standalone info browser but it's not as nice as the Emacs one. And there are html converters but those are even worse. Back in the day, I doubt that it occurred to anyone that a lot of GNU users might someday not use Emacs. I do constantly use the Info documentation for Org-mode and a few other things, but it is observable (and annoying) that some large GNU programs like bash are documented only as man pages afaict.
- welterde 4y ago
  The standalone info browser really isn't that bad and neither are the generated html page(s) (especially now that they applied some light CSS) and also the generated pdf look fairly good. GNU bash also has fairly good info documentation.
tpoacher 4y ago
I recently decided to finally spend roughly 5 minutes to learn how to navigate around info manuals. Afterwards I was like, wow, where has this been all my life??? So my answer to your question would be inertia.
hulitu 4y ago
Because the info pages (although claimed otherwise) had the same info like man pages, with very few exceptions. And navigating info pages was a pain.

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.