News for hackers. Stuff that matters.
Re:Colorized man pages by AceJohnny2 on Tuesday August 16, 2016 @01:48PM (#12299145)
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.h...

Re:Colorized man pages by throwanem on Tuesday August 16, 2016 @04:53PM (#12300559)
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.

Re:Colorized man pages by ansible on Tuesday August 16, 2016 @05:15PM (#12300708)
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.

Re:Colorized man pages by glandium on Tuesday August 16, 2016 @07:42PM (#12301491)
Even better: say, you've opened info for something and are lost in it, and try info info, what you get is a list of all the available info pages, preceded by (on my machine):

This is the Info main menu (aka directory node). A few useful Info commands:

  'q' quits;
  '?' lists all Info commands;
  'h' starts the Info tutorial;
  'mTexinfo RET' visits the Texinfo manual, etc.

You'd think that's helpful, but...

hitting '?' brings a "Regexp search backward" prompt...

hitting 'h' brings... (oh irony) the info man page (but it's displayed by info, not man), and the man page has absolutely no information about how this thing works. Only command line arguments.

Re:Colorized man pages by throwanem on Tuesday August 16, 2016 @08:15PM (#12301643)
There appears to exist throughout the "standalone" Info viewer an assumption that you have Emacs globally installed. (I can't imagine why.) If you don't, you're stuck with whatever info documentation your distro packager and software developers provide, which usually is both not much and not good.

Anyway, here's throwanem's handy-dandy cheat sheet for Info navigation:

m - Select a currently displayed menu item, with partial entry and tab completion

p, n - Move to the previous and next sibling nodes at this level of the tree

u - Move to the parent of the currently displayed node

t - Move to the top level of the currently displayed manual (and u from here takes you back to the directory)

s - Search incrementally forward, with wrapping, by substring or (Emacs) regexp

C-r - Search incrementally backward, etc., etc.

l, r - Move back and forward, respectively, among the list of nodes you've visited this section

q - Exit the Info viewer

As you see, in a lot of ways Info navigation conceptually corresponds with that in a web browser, especially if itimplements the semantic navigation UI that never really got the love it deserved. (I don't think any current browsers have had that in core for a long time, but there is a Firefox extension that provides them, in the rare case that you actually browse pages which include the metainformation that UI needs in order to work.) But, unlike a browser, Info's UI is so undiscoverable as to be actively hostile to the task-focused user. If you often find yourself struggling with it, perhaps the information here might help.

Re:Colorized man pages by fanf2 on Wednesday August 17, 2016 @09:43AM (#12304600)
I prefer to read GNU info manuals using less, like a man page. I have a shell script to find, unzip, and concatenate the parts: https://gist.github.com/fanf2/982811ac34a4ac146a3b7c9fcc729c...
Re:Colorized man pages by ralph on Friday August 19, 2016 @11:11AM (#12320570)
`info foo | less' has it produce the whole "page" as plain text, suitable for easy reading and regexp searching.
Re:Colorized man pages by a3n on Tuesday August 16, 2016 @03:27PM (#12299927)
> 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

Re:Colorized man pages by AceJohnny2 on Tuesday August 16, 2016 @03:46PM (#12300092)
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.

Re:Colorized man pages by ansible on Tuesday August 16, 2016 @05:20PM (#12300735)
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.

Re:Colorized man pages by eriknstr on Tuesday August 16, 2016 @06:16PM (#12301045)
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.
Re:Colorized man pages by AceJohnny2 on Tuesday August 16, 2016 @07:09PM (#12301343)
> 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.

Re:Colorized man pages by noselasd on Tuesday August 16, 2016 @05:25PM (#12300758)
Do yourself a favor and install pinfo - an info viewer that's actually usable.
Re:Colorized man pages by Animats on Tuesday August 16, 2016 @05:42PM (#12300862)
"info" is much like gopher, but less well designed.
Re:Colorized man pages by akkartik on Tuesday August 16, 2016 @02:54PM (#12299700)
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

[2] http://landley.net/aboriginal/history.html

Re:Colorized man pages by eriknstr on Tuesday August 16, 2016 @06:10PM (#12301003)
>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.

Re:Colorized man pages by ralph on Friday August 19, 2016 @11:13AM (#12320582)
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.
Re:Colorized man pages by benwaffle on Tuesday August 16, 2016 @05:59PM (#12300937)
I use GNOME Help / Yelp to view info pages. Just hit ctrl-L and go to 'info:whatever'
Re:Colorized man pages by BurningFrog on Tuesday August 16, 2016 @02:24PM (#12299452)
I still use manpages now and then. But only by googling them.