Guidance on man pages for the GNU project is wild
source link: https://social.jvns.ca/@b0rk/111607416578693170
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Julia Evans: "this guidance on man pages for…"
this guidance on man pages for the GNU project is wild https://www.gnu.org/prep/standards/html_node/Man-Pages.html
(they seem to think everyone should use info pages instead, which I personally have never used despite having used GNU tools for 20 years)
@b0rk I somehow expected the second paragraph to go "instead, we encourage you to write an info page", but uh, this is essentially saying "yeah, we don't need docs, docs aren't useful work".
@zhenech oh they do encourage you to make info pages later on, I just think that's kind of an absurd approach because I literally did not know info pages existed for the first 15 years I used GNU tools, and I've still never used one
@egallager @adriano @b0rk @zhenech @wesnoth Immediate guess, the long options you have are missing a equal sign. The argument to said long options is also in lower case. Consider "--validate-schema arg" vs "--block-size=SIZE" from GNU ls. Long options should generally require an equal sign between argument an option.
@egallager @adriano @b0rk @zhenech @wesnoth Additionally, stuff like:
-v [ --version ] prints the game's version number and exits.
is sorta "weird" from a user perspective, "is --version optional to -v?" -- normally you'd something like
-w, --width=COLS set output .....
@egallager @adriano @b0rk @zhenech @wesnoth But looking at the thread, maybe messages going to stderr?
Maybe I should install Wesnoth and just stop asking questions! 
@wim @dmaonR @adriano That was one thing (not all the manuals though ended up under non-free); the other was that you generally had to install FOO-doc, which also did not populate the "top file" with correct entries, so @b0rk issue of navigating to say xargs, didn't work (we made this easier for distributions improving the #GNU Texinfo).
Even the feature where info shows man pages was to make users happy -- better have something than nothing. Can't make everyone happy...
So, if I get this straight, from these quotes:
"Debian only packaged the info pages in non-free due to licensing issues"
and
"you generally had to install FOO-doc, which also did not populate the "top file" with correct entries"
You invented a new system of documentation which required extra work for the common user, forced distros to consider licensing issues, did not work correctly when installed from a secondary package, *but the fault is the distros'*
@adriano @amszmidt @wim @dmaonR @b0rk this is the most FOSS thread I’ve read in weeks 
I vaguely remember coming in contact with info pages ca. 2002 and wondering, “why did they replace archaic, confusing thing with a different archaic, confusing thing, made it incompatible, and then barely marketed it?”
Not shocked to see none of that has changed in the intervening two decades.
@adriano @b0rk @zhenech this RIGHT HERE is why I quickly gained a hatred for info pages. I felt that documentation was being withheld; seems that it wasn't just me.
Debian went to the effort to correct this somewhat. It's not exciting work, but someone recognized that it's important work and is worthy of effort.
@sysop408 @zhenech no it's a great question! You can theoretically view them on linux with `info grep` but it sucks. Apparently there's an HTML view on the internet at https://www.gnu.org/software/grep/manual/grep.html
@b0rk I wrote my first Web page using Emacs over dial-up to be viewed by NCSA Mosaic browsers. I can't believe that today is the first time I've ever accessed an info page. Awesome!
It's interesting that info appears to have no dependency on locally installed programs whereas man only gives you documentation bundled with your installed tools.
Like you said, kinda odd that they haven't updated this policy. Whatever the original point was, seems to have been lost to time.
I guess someone decided man hill was the hill he wanted to die on and for purposes of humor, I do hope it was a *he*.
@sysop408 @b0rk @zhenech I can tell just by the writing style that this was one of RMS's personal hobbyhorses.
The saddest thing about the whole situation, to my mind, is that some of the GNU info manuals are really good, if considered on their own terms. When I was teaching at CMU I found it was often helpful to point students at specific sections of <https://sourceware.org/glibc/manual/html_node/index.html>, for instance. And I have heard that the FSF actually used to fund technical writers to write them, which, if it's true, I wish they hadn't given up on it.
@zwol yeah it really feels like if there were more investment in discoverability they could be useful
@zwol what's supposed to be the difference between a man page and an info page? Just from the few that I sampled, I gather that today that the info page is the man page expanded to include additional info that's not specific to usage commands.
I guess it seems to me that the man page is more of an info sheet and the info page is actually a manual. Is that how it always was?
@sysop408 @b0rk @zhenech Individual man pages can be a bunch of different things. The *collection* of all man pages, however, was originally intended to be a comprehensive *reference* manual for Unix. This means a good manpage is written with the expectation that people are going to read just one or two manpages at a time, and also that readers already basically know what the thing is for and want to be reminded of all the details.
To get a sense for what people often find lacking in manpages converted from command --help output, compare <https://man7.org/linux/man-pages/man1/ls.1.html> (generated from ls --help) with <https://man.freebsd.org/cgi/man.cgi?query=ls&apropos=0&sektion=1&manpath=FreeBSD+14.0-RELEASE+and+Ports&arch=default&format=html> (written by hand by someone steeped in the tradition of manpages).
@zwol this is starting to make sense. Thanks for staying with me on this.
It makes perfect sense to me that a man page is supposed to be a quick reference that could be compiled to be part of a much larger volume and an info page should be something that stands on its own. Was there a very practical 1980's reason for that level of hostility toward man pages or was it really just an ideology that condensed info is a waste of resources?
@sysop408 @b0rk @zhenech I do not know for certain, but I think a lot of it was that RMS thought the *source format* for manpages was really painful to write, and he thought GNU contributors would be more willing to work on Texinfo format manuals.
In general, the people who worked on GNU in the early years had no hesitation to declare that some existing thing about Unix was bad and they had a better idea. Sometimes they were right (yes, all programs _should_ be able to handle arbitrarily long lines of text) and sometimes they antagonized everyone who liked the existing thing (vi versus emacs). And sometimes, they were right as far as their thinking went, but ignored another class of problems that were just as significant: sure, Texinfo is easier to *write* than troff -man or -mdoc, but nobody likes that standalone "info" reader, and the *structure* of Texinfo documentation makes it hard to provide the same ease of looking up things in the index as you get from "man".
(Have a skim through https://github.com/besser82/libxcrypt/blob/develop/doc/crypt.3 to get a sense for what writing troff-format documentation is like -- and be aware that this is the newer, slightly less painful "mdoc" notation.)
@zwol appreciate you sharing all this information about the history of reference documentation, I'm learning a lot
@b0rk @sysop408 @zhenech konqeror browser used to have builtin `info:grep` support in the address bar and you could click to navigate the pages it rendered. The chapters and links seem to be the main differentiation from a manpage. I started Linux with dial-up internet (8 debian floppies and a 486) and learned a lot with `apropos` or `... --help| less` and the installed docs.
@b0rk @sysop408 @zhenech info always seemed to demand emacs keybindings, so I used man pages instead
there were definitely some where the info pages were more complete than the man pages
At this point I used AsciiDoc for everything it and it can make man pages, so it seems I chose correctly all those years ago :)
@b0rk @sysop408 @zhenech i have known about info pages for about 30 years but still haven't read one for more than 20 years. i got curious as to how they appear now. so i tried `info grep` on my mac; to my surprise it works…
and shows me the BSD man page, lol (with the highlighting removed). Nothing else about info seems to changed, including info’s own note about itself that it doesn’t support the mouse (still true in 2023).
@flamingos_cant @sysop408 @b0rk @zhenech I've only started to seldom peruse info pages after discovering pinfo, a good 5 or 6 years after my first Linux install. You can find it here: https://github.com/baszoetekouw/pinfo — and it can even render man pages and navigate around them. The key bindings are similar to Lynx and much more reasonable than those of GNU info and it uses colors while being smaller than the bloated GNU offering 
Same. They (probably RMS) have always insisted on this as a religious point, even after the ship clearly sailed.
Another case of a personal programming preference being elevated to dogma.
@omarshehata @dadregga @b0rk No, it's just an early, primitive attempt at hypertext that originated (I think) in the early-1980s MIT hacker culture. Also used as an excuse to write a rambling, garrulous tome in place of a few compact paragraphs.
@omarshehata @dadregga @b0rk Indeed. Long, detailed, even stream-of-consciousness docs have a place. But they're no replacement for cat(1).
@b0rk Good thing that advice is ignored by most people.
@b0rk the trick with gnu is to learn what is good and what should just be ignored. This is just super bad advise.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK