4 ms·

As a tangent, I remain impressed by manpage's staying power. GNU tried to move ahead with Info, a tree-based doc format and viewer, but that never really seems

As a tangent, I remain impressed by manpage's staying power. GNU tried to move ahead with Info, a tree-based doc format and viewer, but that never really seems to have taken off, possibly due to UI issues (I'm always confused about how to use it) It's a pity: have you tried searching for something in, say, Bash's manpage? It's just a flattened version of its doc, and you're completely flooded with search results. I suppose manpages are another example of "worse is better". They are extremely simple to use, which is what you want when you're frustrated and looking for that *$#& option to 'find'. And yet, the troff/groff formatters used by manpages can be pretty sophisticated (Kernighan mentioned in an interview [1] he still used it to write books, eschewing to complexity of Latex) and can produce a variety of formats, such as HTML or PostScript. Why don't distributions make more use of this? I miss the days where you could "man foo" in KDE's quick launch bar and get a nicely HTML formatted version in Konqueror. [1] https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.html https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h...

BurningFrog 10y ago
I still use manpages now and then. But only by googling them.
akkartik 10y ago
Manpages as "worse is better"? Them's fighting words :) I think it's more an example of how GNU isn't Unix, for better and for worse[1][2]. Info seems to be deeply integrated with the Emacs mindset, so coming from a different editor it's got some learning curve. Except it never seemed to be setup properly by default on a new server, and when I installed something new I'd never remember what I had to do to add it to the root page. Many's the time I tried to info for something and got.. its manpage, but in a crappier setting. Scanning a large manpage with '/' seems far superior to playing whack-a-mole with Info's tree structure. I don't want to sip documentation with a straw, just give me the firehose. (This is also why I prefer 'man zshall' rather than the trying-to-be-helpful sections of the zsh manpage. Who in god's name remembers which of those sections the factoid they're looking for is going to be in?) All this would be surmountable if Info worked consistently out of the box. But the combination of encountering it only intermittently in working fashion meant that any lessons I learned quickly evaporated, and had to be repeatedly relearnt. I'm very happy now that GNU systems have given up on trying to make Info happen. Documentation quality is all about the quality of the content. Working on the tools instead of the content is classic bikeshedding. (The one great advance in Unix documentation recently is git's approach of opening the man page when you type --help.) [1] http://queue.acm.org/detail.cfm?id=2349257 http://queue.acm.org/detail.cfm?id=2349257 [2] http://landley.net/aboriginal/history.html http://landley.net/aboriginal/history.html
a3n 10y ago
> As a tangent, I remain impressed by manpage's staying power. GNU tried to move ahead with Info ... 1. man something 2. discover that something is a gnu utility whose authors decided to support by pointing its minimal manpage to an info page. 3. info something 4. ? 5. /search 6. ctl-g (trying to "Cancel the current operation") 7. alt-g 8. win-g 9. shift-g 10. ctl-shift-g 11. ctl-alt-g (I got a "Quit" message!) 12. ctl-alt-g 13. ctl-atl-g 14. ctl-z $ pkill info
- AceJohnny2 10y ago
  Exactly. Funny thing is, quitting is just 'q', or classic ctl-c! Searching is ctl-S. Also, I can't remember which pretty basic utility has a manpage that indeed redirects to the info page... which is just a copy of the manpage, down to the including the 'see Info page for more'. That said, that may be a packaging issue or just a good old documentation fail.
  - ansible 10y ago
    Searching is ctl-S. Ctrl-Q and Ctrl-S are still bad choices for commands. Why? Some terminals support flow control via XON/XOFF, which is Ctrl-S and Ctrl-Q. Back in the day, with a serial terminal running at 9600 bps, a human had fast enough reflexes to stop and start the screen output. These days, no so much. Heck, we had an incident just last week where one of my coworkers froze his output screen via Ctrl-S, and I told him about Ctrl-Q to unfreeze it. It's funny how long some of this stuff hangs around, long past its useful time. Ah, compatibility. Or cruft.
    - eriknstr 10y ago
      Every now and then I somehow manage to enter Ctrl-S into urxvt and freeze it, still don't know how I do that. Anyway, each time I have to Google "urxvt frozen" to find what to do.
    - AceJohnny2 10y ago
      > Why? Some terminals support flow control via XON/XOFF, which is Ctrl-S and Ctrl-Q. Except if the app opened the terminal in raw mode, in which case the app gets the control character.
throwanem 10y ago
Info was a brilliant idea for its time, and it synergizes brilliantly with Emacs for those of us who use that editor. For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them. And even leaving that aside, Texinfo is fundamentally broken in a really disappointing way: the source includes almost no semantic information whatsoever - imagine HTML with no whitespace squashing and no tags except <br> and <a>. Worse, there is no consistency whatsoever among different authors on what structural conventions to use. It's therefore somewhere between very difficult and nigh impossible to implement anything like this rather nice colorization of manual pages. There are a couple of Emacs packages which try to do that, but while they do the best they can, that best isn't very good - and, of course, they're only useful if you use Emacs. Honestly, it's a really frustrating situation. Texinfo manuals, especially those from the GNU project, tend to be much more detailed and complete on average than manual pages, which makes them an excellent reference for cases where the aide-memoire style of a man page doesn't convey the context you need. But the info system is practically impossible to use unless you're very familiar with Emacs, and even when you are, it's still almost impossible to make info any more useful than plain text would be. Given the age of Texinfo - older than three-fifths of the developers who answered Stack Overflow's 2016 survey! - it's not terribly surprising that it was born with flaws like these. But after thirty years, it is somewhat surprising that those flaws still exist.
- ansible 10y ago
  For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them. I hope future generations of user interaction designers pay heed to this. If you're going into the GNU info system to begin with, you're trying to get help, because you don't know something. Chances are, you may not know much about the system at all. So navigating your help system should be very, very easy. Because I'm trying to figure out some other program, and I don't want to spend 15 minutes trying to learn the help system first. A WordStar-like on-screen navigation help for GNU info would have helped me immensely through the years. Yes, it would have wasted valuable screen real estate, so the advanced users would eventually have created a command-line alias to disable it. Guys like me that used GNU info once a year (if that) would have had a much easier time.
benwaffle 10y ago
I use GNOME Help / Yelp to view info pages. Just hit ctrl-L and go to 'info:whatever'
eriknstr 10y ago
>have you tried searching for something in, say, Bash's manpage? I frequently have this problem where I have to wade through a lot of irrelevant matches in less when searching for a keyword in a manpage, and I've been thinking about it for a bit. In my mind, the best solution to the problem is for the manpage authors to be more careful in not using the important keywords elsewhere in the manpage, but in reality, I don't think it's doable to avoid that because what words are important will vary from person to person and even from situation to situation. Usually my way of finding an answer is to first consult the manpages and if I don't find an answer within a few seconds then I'll just use Google instead. It's a bad habit, I think, because when I'm without internet access -- which actually does happen from time to time, e.g. when I'm on vacation -- I end up having troubles finding out how to do things.
ralph 10y ago
I find searching bash(1) just fine with less(1) and do it quite often. The groff mailing list, the main discussion point for all things troff, is slowly chipping away at adding more semantic information to man pages. The BSDs have been making progress here.

BurningFrog 10y ago

I still use manpages now and then. But only by googling them.

akkartik 10y ago

Manpages as "worse is better"? Them's fighting words :) I think it's more an example of how GNU isn't Unix, for better and for worse[1][2]. Info seems to be deeply integrated with the Emacs mindset, so coming from a different editor it's got some learning curve. Except it never seemed to be setup properly by default on a new server, and when I installed something new I'd never remember what I had to do to add it to the root page. Many's the time I tried to info for something and got.. its manpage, but in a crappier setting. Scanning a large manpage with '/' seems far superior to playing whack-a-mole with Info's tree structure. I don't want to sip documentation with a straw, just give me the firehose. (This is also why I prefer 'man zshall' rather than the trying-to-be-helpful sections of the zsh manpage. Who in god's name remembers which of those sections the factoid they're looking for is going to be in?) All this would be surmountable if Info worked consistently out of the box. But the combination of encountering it only intermittently in working fashion meant that any lessons I learned quickly evaporated, and had to be repeatedly relearnt. I'm very happy now that GNU systems have given up on trying to make Info happen. Documentation quality is all about the quality of the content. Working on the tools instead of the content is classic bikeshedding. (The one great advance in Unix documentation recently is git's approach of opening the man page when you type --help.) [1] http://queue.acm.org/detail.cfm?id=2349257 http://queue.acm.org/detail.cfm?id=2349257 [2] http://landley.net/aboriginal/history.html http://landley.net/aboriginal/history.html

a3n 10y ago

> As a tangent, I remain impressed by manpage's staying power. GNU tried to move ahead with Info ... 1. man something 2. discover that something is a gnu utility whose authors decided to support by pointing its minimal manpage to an info page. 3. info something 4. ? 5. /search 6. ctl-g (trying to "Cancel the current operation") 7. alt-g 8. win-g 9. shift-g 10. ctl-shift-g 11. ctl-alt-g (I got a "Quit" message!) 12. ctl-alt-g 13. ctl-atl-g 14. ctl-z $ pkill info

AceJohnny2 10y ago
Exactly. Funny thing is, quitting is just 'q', or classic ctl-c! Searching is ctl-S. Also, I can't remember which pretty basic utility has a manpage that indeed redirects to the info page... which is just a copy of the manpage, down to the including the 'see Info page for more'. That said, that may be a packaging issue or just a good old documentation fail.
- ansible 10y ago
  Searching is ctl-S. Ctrl-Q and Ctrl-S are still bad choices for commands. Why? Some terminals support flow control via XON/XOFF, which is Ctrl-S and Ctrl-Q. Back in the day, with a serial terminal running at 9600 bps, a human had fast enough reflexes to stop and start the screen output. These days, no so much. Heck, we had an incident just last week where one of my coworkers froze his output screen via Ctrl-S, and I told him about Ctrl-Q to unfreeze it. It's funny how long some of this stuff hangs around, long past its useful time. Ah, compatibility. Or cruft.
  - eriknstr 10y ago
    Every now and then I somehow manage to enter Ctrl-S into urxvt and freeze it, still don't know how I do that. Anyway, each time I have to Google "urxvt frozen" to find what to do.
  - AceJohnny2 10y ago
    > Why? Some terminals support flow control via XON/XOFF, which is Ctrl-S and Ctrl-Q. Except if the app opened the terminal in raw mode, in which case the app gets the control character.

throwanem 10y ago

Info was a brilliant idea for its time, and it synergizes brilliantly with Emacs for those of us who use that editor. For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them. And even leaving that aside, Texinfo is fundamentally broken in a really disappointing way: the source includes almost no semantic information whatsoever - imagine HTML with no whitespace squashing and no tags except <br> and <a>. Worse, there is no consistency whatsoever among different authors on what structural conventions to use. It's therefore somewhere between very difficult and nigh impossible to implement anything like this rather nice colorization of manual pages. There are a couple of Emacs packages which try to do that, but while they do the best they can, that best isn't very good - and, of course, they're only useful if you use Emacs. Honestly, it's a really frustrating situation. Texinfo manuals, especially those from the GNU project, tend to be much more detailed and complete on average than manual pages, which makes them an excellent reference for cases where the aide-memoire style of a man page doesn't convey the context you need. But the info system is practically impossible to use unless you're very familiar with Emacs, and even when you are, it's still almost impossible to make info any more useful than plain text would be. Given the age of Texinfo - older than three-fifths of the developers who answered Stack Overflow's 2016 survey! - it's not terribly surprising that it was born with flaws like these. But after thirty years, it is somewhat surprising that those flaws still exist.

ansible 10y ago
For those who don't, it's a UX nightmare, because the standalone info viewer uses a specific, relatively ill-surfaced subset of Emacs conventions for its navigation commands. No one who doesn't use Emacs can be expected to know any of these. Even those of us who do use Emacs often don't know any of these. It took me more than half a decade of daily Emacs use to discover them. I hope future generations of user interaction designers pay heed to this. If you're going into the GNU info system to begin with, you're trying to get help, because you don't know something. Chances are, you may not know much about the system at all. So navigating your help system should be very, very easy. Because I'm trying to figure out some other program, and I don't want to spend 15 minutes trying to learn the help system first. A WordStar-like on-screen navigation help for GNU info would have helped me immensely through the years. Yes, it would have wasted valuable screen real estate, so the advanced users would eventually have created a command-line alias to disable it. Guys like me that used GNU info once a year (if that) would have had a much easier time.

benwaffle 10y ago

I use GNOME Help / Yelp to view info pages. Just hit ctrl-L and go to 'info:whatever'

eriknstr 10y ago

>have you tried searching for something in, say, Bash's manpage? I frequently have this problem where I have to wade through a lot of irrelevant matches in less when searching for a keyword in a manpage, and I've been thinking about it for a bit. In my mind, the best solution to the problem is for the manpage authors to be more careful in not using the important keywords elsewhere in the manpage, but in reality, I don't think it's doable to avoid that because what words are important will vary from person to person and even from situation to situation. Usually my way of finding an answer is to first consult the manpages and if I don't find an answer within a few seconds then I'll just use Google instead. It's a bad habit, I think, because when I'm without internet access -- which actually does happen from time to time, e.g. when I'm on vacation -- I end up having troubles finding out how to do things.

ralph 10y ago

I find searching bash(1) just fine with less(1) and do it quite often. The groff mailing list, the main discussion point for all things troff, is slowly chipping away at adding more semantic information to man pages. The BSDs have been making progress here.