Colorized man pages(boredzo.org)
boredzo.org
Colorized man pages
http://boredzo.org/blog/archives/2016-08-15/colorized-man-pages-understood-and-customized
102 comments
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.
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.
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.
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.
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:
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.
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.
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.
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.
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...
`info foo | less' has it produce the whole "page" as plain text, suitable for easy reading and regexp searching.
> 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
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
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.
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.
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.
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.
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.
> 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.
Except if the app opened the terminal in raw mode, in which case the app gets the control character.
Do yourself a favor and install pinfo - an info viewer that's actually usable.
"info" is much like gopher, but less well designed.
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
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
>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.
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.
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.
I use GNOME Help / Yelp to view info pages. Just hit ctrl-L and go to 'info:whatever'
I still use manpages now and then. But only by googling them.
It would be nice if we made better use of full-colour terminal support.
(See also, a script to display an image in the terminal: https://git.gnome.org/browse/vte/tree/perf/img.sh?h=vte-0-36 )
man() {
env \
LESS_TERMCAP_mb=$(printf "\x1b[38;2;255;200;200m") \
LESS_TERMCAP_md=$(printf "\x1b[38;2;255;100;200m") \
LESS_TERMCAP_me=$(printf "\x1b[0m") \
LESS_TERMCAP_so=$(printf "\x1b[38;2;60;90;90;48;2;40;40;40m") \
LESS_TERMCAP_se=$(printf "\x1b[0m") \
LESS_TERMCAP_us=$(printf "\x1b[38;2;150;100;200m") \
LESS_TERMCAP_ue=$(printf "\x1b[0m") \
man "$@"
}
(See also, a script to display an image in the terminal: https://git.gnome.org/browse/vte/tree/perf/img.sh?h=vte-0-36 )
> And it would be really nice if I could read man pages in the terminal in a proportional font, but preserving alignment etc.
Most man utilities can write postscript instead of directly to terminal. You can use that to achieve exactly what you want. Though this is not exactly in the terminal itself.
Example: I don't have zsh for comparison but on my OS X machine, running `man -t bash | open -f -a Preview` results in this: https://dl.dropboxusercontent.com/u/845567/bash%281%29.pdf
Most man utilities can write postscript instead of directly to terminal. You can use that to achieve exactly what you want. Though this is not exactly in the terminal itself.
Example: I don't have zsh for comparison but on my OS X machine, running `man -t bash | open -f -a Preview` results in this: https://dl.dropboxusercontent.com/u/845567/bash%281%29.pdf
That is beautiful! I didn't realize you could pipe into OSX's `open` util. (or how big the man page for bash really is!)
Here's zsh: https://drive.google.com/file/d/0B_jWp8d11aB5Wi15eVdJS1Nhdk0...
Here's zsh: https://drive.google.com/file/d/0B_jWp8d11aB5Wi15eVdJS1Nhdk0...
> I didn't realize you could pipe into OSX's `open` util
It kinda sucks that you can't just pipe directly to Preview, but I suppose we should be grateful this wonderful pipeline does actually work!
It kinda sucks that you can't just pipe directly to Preview, but I suppose we should be grateful this wonderful pipeline does actually work!
Is there a way to avoid Times New Roman? Some of the characters are pretty ambiguous. I remember, back when I used that command, I mixed up an l and a 1 for one of the flags.
To be pedantic, the font you're seeing isn't Times New Roman, but rather Times. They're similar, but there are subtle differences.
Yes, you can choose a default font. You need to change your /etc/man.conf, find the line that starts with TROFF, and add new options. For example, to use Palatino as the default font, you should additionally provide the option `-f P`. Then you'll get this output: https://dl.dropboxusercontent.com/u/845567/bash%281%29%20Pal...
Yes, you can choose a default font. You need to change your /etc/man.conf, find the line that starts with TROFF, and add new options. For example, to use Palatino as the default font, you should additionally provide the option `-f P`. Then you'll get this output: https://dl.dropboxusercontent.com/u/845567/bash%281%29%20Pal...
> To be pedantic, the font you're seeing isn't Times New Roman, but rather Times. They're similar, but there are subtle differences.
And there's an interesting history to that split: https://en.wikipedia.org/wiki/Times_New_Roman#Linotype_relea...
And there's an interesting history to that split: https://en.wikipedia.org/wiki/Times_New_Roman#Linotype_relea...
Just like my AT&T 3B2 manual from 1985!
If instead of -t you pipe the output of the manpages into groff which is responsible for the file type, formatting, etc there is a font-family flag.
On OS X 10.11.6, Preview fails with "The PostScript file "open_afberandom.txt" could not be converted to a PDF file." :(
For once, I'm glad I'm still running 10.9.5. Can anyone confirm whether issue is unique to OP or something broken in OS 10.11?
Worked on my machine with 10.11.6.
> And it would be really nice if I could read man pages in the terminal in a proportional font, but preserving alignment etc.
People would need to use tabs (gasp) instead of spaces for that :-P
People would need to use tabs (gasp) instead of spaces for that :-P
> People would need to use tabs (gasp) instead of spaces for that :-P
That would be madness.
That would be madness.
Yea, why use a character for what it's supposed to do when you can use 40+ year old workaround for broken editors?
[deleted]
You could just do a naive 4spaces to 1tab conversion.
This breaks for spacing between non-whitespace character. E.g. the list of flags, which may have varying lengths, but all descriptions start on the same alignment.
I have no idea what is actually used in man pages for alignment and spacing, but the example above is only to illustrate that 4space=1tab breaks even on trivial examples as a conversion rule.
This is a man page with a list of flags below
--flag1 Description of flag1
--secondflag Description of secondflag
I have no idea what is actually used in man pages for alignment and spacing, but the example above is only to illustrate that 4space=1tab breaks even on trivial examples as a conversion rule.
That does not matter for single dash and letter options. For double dash long options I like to split them on different lines so that you still have a lot of horizontal space for the descriptions themselves even with very ling option names, so a brute force way:
This is a man page with a list of
.I flags
below
.P
.BR --flag :
.RS
Description of flag1
.RE
.P
.BR --secondflag :
.RS
Description of secondflag
.RE
.P
$ man tbl> And it would be really nice if I could read man pages in the terminal in a proportional font, but preserving alignment etc.
Since you want proportional fonts, you'd have to be willing to leave the terminal already. If so, I'm aware of three options:
1. the classic, xman: fugly
2. the builtin, "man -H": it works sometimes. On my own system, the it's so unreliable that I'd call it alpha-stage software
3. and Konqueror. Works perfectly every time, but you'd have to install KDE components.
Since you want proportional fonts, you'd have to be willing to leave the terminal already. If so, I'm aware of three options:
1. the classic, xman: fugly
2. the builtin, "man -H": it works sometimes. On my own system, the it's so unreliable that I'd call it alpha-stage software
3. and Konqueror. Works perfectly every time, but you'd have to install KDE components.
Manpages are written in troff: https://manpages.bsd.lv/
This means that they can be converted to PostScript or PDF. There’s no portable way to do this with the “man” command, but on most Linuxes you can use “man -t” and on a system using Mandoc you can use “man -T pdf”.
Likewise, for HTML, “man -H” is not strictly portable, but only works on certain versions of Linux; a Mandoc system would let you use “man -T html”. (The only strictly portable, as in “POSIX specified,” flag for man is -k.)
Honestly it might be better to just get used to using an existing webpage for your distribution. For example, OpenBSD’s web manpage database (based on Mandoc) is very nice: http://man.openbsd.org/ls.1
This means that they can be converted to PostScript or PDF. There’s no portable way to do this with the “man” command, but on most Linuxes you can use “man -t” and on a system using Mandoc you can use “man -T pdf”.
Likewise, for HTML, “man -H” is not strictly portable, but only works on certain versions of Linux; a Mandoc system would let you use “man -T html”. (The only strictly portable, as in “POSIX specified,” flag for man is -k.)
Honestly it might be better to just get used to using an existing webpage for your distribution. For example, OpenBSD’s web manpage database (based on Mandoc) is very nice: http://man.openbsd.org/ls.1
> and Konqueror. Works perfectly every time, but you'd have to install KDE components.
For that matter, any KDE application that handles URLs can retrieve HTML-formatted man pages thanks to KIO slaves.
You want the source of the HTML-formatted man page so you can edit it and save your edited copy? OK:
For that matter, any KDE application that handles URLs can retrieve HTML-formatted man pages thanks to KIO slaves.
You want the source of the HTML-formatted man page so you can edit it and save your edited copy? OK:
$ kwrite 'man:/usr/share/man/man1/ls.1p.gz'
One could also use Emacs (in a graphical window rather than in the terminal) `woman` and `variable-pitch-mode`.
I don't understand 3.? Konqueror is the KDE3 web browser - how's that relevant here?
Konqueror is still included in current versions of KDE Applications (effectively 5.x, but the term "KDE 5" isn't really used).
Also, it's not so much a Konqueror thing as it is a feature of KDE's URL-handling subsystem. Any KDE application that interacts with URLs can retrieve HTML-formatted man pages. If you don't like Konqueror, you can always use Rekonq. Or you can open the source code in KWrite or Kate. Or you can browse man indices in Dolphin as if they were directories (though the actual pages will open in Konqueror).
KIO slaves are wonderful, wonderful things. It's the same technology that lets you use fish:// to access files and directories over SSH in every KDE program that deals with URLs (and since the file open/save dialogs are URL-based, this means it'll work with anything that uses those dialogs).
Also, it's not so much a Konqueror thing as it is a feature of KDE's URL-handling subsystem. Any KDE application that interacts with URLs can retrieve HTML-formatted man pages. If you don't like Konqueror, you can always use Rekonq. Or you can open the source code in KWrite or Kate. Or you can browse man indices in Dolphin as if they were directories (though the actual pages will open in Konqueror).
KIO slaves are wonderful, wonderful things. It's the same technology that lets you use fish:// to access files and directories over SSH in every KDE program that deals with URLs (and since the file open/save dialogs are URL-based, this means it'll work with anything that uses those dialogs).
Thanks, yeah I used to use fish:/ and fonts:/ and a couple of other kio slaves, just not man, low discoverability I guess. I thought kio slaves had died with KDE5 [that's still the right name IMO despite the framework:applications split].
TIL.
TIL.
Yeah, they neutered a lot of stuff with KF5 (the elimination of KLocale honestly makes me want to go back to Windows), but KIO is still around.
Unfortunately, it looks like fonts:/ was never ported to KF5, but fish:// and a bunch of others are still around.
Unfortunately, it looks like fonts:/ was never ported to KF5, but fish:// and a bunch of others are still around.
Konqueror has man: and info: IOslaves (KIO plugins) allowing it to natively handle local man and info pages.
That assumes that the terminal has full-color support.
It would be even better to use a sane default supported by all terminals (the ugly 16-color one), and enable full-color only on terminals known to support it.
There is probably an exact-but-complicated way to do this. All I do to determine 256-color support is to check for a -256color suffix in the TERM variable.
It would be even better to use a sane default supported by all terminals (the ugly 16-color one), and enable full-color only on terminals known to support it.
There is probably an exact-but-complicated way to do this. All I do to determine 256-color support is to check for a -256color suffix in the TERM variable.
The terminfo database records how many colours a terminal supports: if the shell command `tput colors` prints 256, then your terminal is configured to support 256 colours.
Unfortunately, there's no standard database field to record the presence of truecolor support; even if there were, there's terminals (like xterm, for example) that understand the control-sequences but map them to the nearest colour in the 256-colour palette rather than using them as-is.
Unfortunately, there's no standard database field to record the presence of truecolor support; even if there were, there's terminals (like xterm, for example) that understand the control-sequences but map them to the nearest colour in the 256-colour palette rather than using them as-is.
>That assumes that the terminal has full-color support.
As it should (assume and have) in 2016.
As it should (assume and have) in 2016.
Or you could just use most(1) as MANPAGER.
http://www.jedsoft.org/most/
http://www.jedsoft.org/most/
That site needs some updating. The 'features' and 'images' sections both lack content (merely a message stating "under construction"). Although content > style, I can't help but mention how dated the site looks also.
You're right, that webpage is sh*t. Nevertheless, that's the official webhome for most(1) which should be readily installable in most Linux distros.
I wouldn't go that far. That and other sections of the website may be incomplete, but the pages load quickly, don't require a multitude of JS calls or other slowdowns. I love pages that do what they're meant to without unwarranted bloat. Gmail and Github use JS for web apps, and that's okay, but a static page doesn't need that and is worse off if they incorporate it. If you go to a random wikipedia article and try to click through references and land on a newpaper's site, 4 out of 5 times the link will be dead. So much for complex CMS installations. I'm (not) sorry that I prefer web pages that work more than ones that chase some short-lived frontend tech.
With all that being said, I'm sure the author would appreciate a contribution to fill in the blanks.
With all that being said, I'm sure the author would appreciate a contribution to fill in the blanks.
I just installed it... it works beautifully. Thanks for the heads up!
Looks great! There's some info and a screenshot on the debian package page:
https://packages.debian.org/sid/most
The official website doesn't really contain any information.
The official website doesn't really contain any information.
"most" is impossible to search. "mostpager" would have been better with a soft-link from most as default.
Anyway, how do I use it, I've sudo apt install-ed it. Scanning the manpage doesn't give me any great hints e.g. "most /usr/share/man/man1/apt-add-repository.1.gz" brings it up but the manpage shows control data; using as if it were man just fails (it thinks I'm passing it a file).
Hint? Or do I need to read the source ...
Anyway, how do I use it, I've sudo apt install-ed it. Scanning the manpage doesn't give me any great hints e.g. "most /usr/share/man/man1/apt-add-repository.1.gz" brings it up but the manpage shows control data; using as if it were man just fails (it thinks I'm passing it a file).
Hint? Or do I need to read the source ...
If I recall correctly... add to your .bashrc
export PAGER=most
or for my fish friends, add to ~/.config/fish/config.fish
set -x PAGER most
This'll use `most` everytime a pager is needed (i.e. git log), if you want to use `most` only for man pages, replace PAGER with MANPAGER
export PAGER=most
or for my fish friends, add to ~/.config/fish/config.fish
set -x PAGER most
This'll use `most` everytime a pager is needed (i.e. git log), if you want to use `most` only for man pages, replace PAGER with MANPAGER
On fish same effect could be achieved by running
set -Ux PAGER mostU
If you prefer to keep fish.config cleaner, that is :)
set -Ux PAGER mostU
If you prefer to keep fish.config cleaner, that is :)
Either
export PAGER=most
export MANPAGER=most
Just installed most, but it doesn't support scrolling via the j and k keys. I'd have to move all the way over to the arrow keys. This is not a replacement for less. Uninstalling.
most is literally the first package I install on every box on which I get or am given admin right.
It works so well it is unsane not to use it.
Thank God I saw that name while installing Slackware a long time ago, and since then it had been a pleasure to use.
It works so well it is unsane not to use it.
Thank God I saw that name while installing Slackware a long time ago, and since then it had been a pleasure to use.
I use vim as a manpager. This way I get all my binds for navigating (I mapped <c-e> to scroll two lines, etc), colors is supported and folds.
Or pinfo which supports both man and info pages.
omg, why do I discover this only now? thanks.
If you're using oh-my-zsh, you can just enable the colored-man-pages plugin
Although the author uses zsh, the function works other shells as well; at least on bash.
yep, I can't tell the difference. oh-my-zsh much have it by default
I found this script on reddit once. It does the same but sets random colors for man pages.
https://gitlab.com/agilob/.files/blob/master/mancolor.sh
https://gitlab.com/agilob/.files/blob/master/mancolor.sh
First I thought random colors might just be a "because I can" thing, but the script apparently keeps consistent colors for each man page. Now I wonder if it has a use case...
Most often it's really nice looking. https://gitlab.com/agilob/.files/raw/4249f5d58aca984ef32af76...
If each man page has different random numbers (perhaps seeded on the man page section and name), then I could see that it might be a memory aid, kinda like having different floors of a building painted different colours, while different layers have different carpeting and different organisations inside the building have different artistic styles: one's subconscious learns what one's environment indicates, and it makes navigation much easier.
Bit of a "useless use of env" here. You don't need the env program for establishing environment variables for the execution of a command. That is a built-in shell feature:
Thus:
VAR1=val1 VAR2=val2 ... command
Thus:
man() {
LESS_TERMCAP_mb=$(printf "\e[1;31m") \
LESS_TERMCAP_md=$(printf "\e[1;31m") \
LESS_TERMCAP_me=$(printf "\e[0m") \
LESS_TERMCAP_se=$(printf "\e[0m") \
LESS_TERMCAP_so=$(printf "\e[1;44;33m") \
LESS_TERMCAP_ue=$(printf "\e[0m") \
LESS_TERMCAP_us=$(printf "\e[1;32m") \
command man "$@"
}For my Fish shell comrades, see http://askubuntu.com/a/650192.
Really interesting thoughts coming from the groff mailing list:
"Because of poverty owing to neglect -- that is, necessity being the mother of invention -- the author of the article I linked to decided he'd like color in his man pages. Where did he turn? A style sheet in the groff framework, perhaps? Any kind of improvement to the semantic-display connection? No, he reached about as far down as possible, and tweaked the control sequences emitted to the emulator. Because he could. Because, in a way, he had to, insofar as that strange bit of arcania gave him the most leverage.
"So, yes, he's still working with a text terminal, after a fashion. But the programmability of that text terminal is an accident of history, its feature set long since made obsolete -- not useless, but out-moded -- by graphical displays and GUIs. That he reached for that particular tool is a measure of how far we have come, and how far we have not."
https://lists.gnu.org/archive/html/groff/2016-08/msg00034.ht...
Thread root: https://lists.gnu.org/archive/html/groff/2016-08/msg00013.ht...
"Because of poverty owing to neglect -- that is, necessity being the mother of invention -- the author of the article I linked to decided he'd like color in his man pages. Where did he turn? A style sheet in the groff framework, perhaps? Any kind of improvement to the semantic-display connection? No, he reached about as far down as possible, and tweaked the control sequences emitted to the emulator. Because he could. Because, in a way, he had to, insofar as that strange bit of arcania gave him the most leverage.
"So, yes, he's still working with a text terminal, after a fashion. But the programmability of that text terminal is an accident of history, its feature set long since made obsolete -- not useless, but out-moded -- by graphical displays and GUIs. That he reached for that particular tool is a measure of how far we have come, and how far we have not."
https://lists.gnu.org/archive/html/groff/2016-08/msg00034.ht...
Thread root: https://lists.gnu.org/archive/html/groff/2016-08/msg00013.ht...
For people on OS X I recommend checking out Bwana https://www.bruji.com/bwana/ ,it's not the same thing, it's man pages in your browser but in combination with Alfred (or similar) and/or a terminal plugin it's great. I find it much faster to skim man pages with bwana.
Main issue is of course that this shows man pages for OS X, which is usually similar but not identical to the ones on your favourite distro.
Main issue is of course that this shows man pages for OS X, which is usually similar but not identical to the ones on your favourite distro.
If you like bwana, you could try my updated copy: https://bitbucket.org/tom_seddon/bwana (I've put a compiled version in the releases page - if it doesn't work, you can hopefully build it yourself)
Main improvement: man pages generated with this version include more links. Any time it spots a word that's bold, or underlined, or whatever it is - I don't remember what it was exactly - rather than just printing it that way it tries to turn it into a link to the man page by that name, if there is one.
Main improvement: man pages generated with this version include more links. Any time it spots a word that's bold, or underlined, or whatever it is - I don't remember what it was exactly - rather than just printing it that way it tries to turn it into a link to the man page by that name, if there is one.
I like that, thanks!
A good example of how function definitions in shell can be used to overlay commands (applications).
The man() shell function in the example, although slick, is terribly inefficient because every time the man(1) command is called, the function will execute multiple printf(1) applications, over and over and over again. If you've ever ran application startup and shutdown at the assembler level in a debugger, it became obvious pretty quickly than running an application involved many, often recursive libc and system function calls, just to be able to set up the environment in order to start and exit the application.
Here, then, is the fix; this runs only once at shell startup, and stores the resulting escape codes in variables; put this in your ~/.profile (not .kshrc, nor .bashrc, nor .bash_profile, but ~/.profile!):
it should be noted that this assumes that the terminal (or the terminal emulator) one is using is actually capable of correctly interpreting the escape command sequences, and in addition correctly displaying them. Not all terminal emulators nor all physical terminals are capable of displaying all, some or any of these display modes. The above also assumes that the shell implements \e, which not all shells do (C-shells notably do not).
Finally, a quick crash course on manual pages, manual pages versus info, and why manual pages are orders of magnitude better, and still a standard, because that is bound to come up sooner or later:
https://news.ycombinator.com/item?id=11927525
The man() shell function in the example, although slick, is terribly inefficient because every time the man(1) command is called, the function will execute multiple printf(1) applications, over and over and over again. If you've ever ran application startup and shutdown at the assembler level in a debugger, it became obvious pretty quickly than running an application involved many, often recursive libc and system function calls, just to be able to set up the environment in order to start and exit the application.
Here, then, is the fix; this runs only once at shell startup, and stores the resulting escape codes in variables; put this in your ~/.profile (not .kshrc, nor .bashrc, nor .bash_profile, but ~/.profile!):
LESS_TERMCAP_mb=`printf "\e[1;31m"`; export LESS_TERMCAP_mb
LESS_TERMCAP_md=`printf "\e[1;31m"`; export LESS_TERMCAP_md
LESS_TERMCAP_me=`printf "\e[0m"`; export LESS_TERMCAP_me
LESS_TERMCAP_se=`printf "\e[0m"`; export LESS_TERMCAP_se
LESS_TERMCAP_so=`printf "\e[1;44;33m"`; export LESS_TERMCAP_so
LESS_TERMCAP_ue=`printf "\e[0m"`; export LESS_TERMCAP_ue
LESS_TERMCAP_us=`printf "\e[1;32m"`; export LESS_TERMCAP_us
it should be noted that this assumes that the terminal (or the terminal emulator) one is using is actually capable of correctly interpreting the escape command sequences, and in addition correctly displaying them. Not all terminal emulators nor all physical terminals are capable of displaying all, some or any of these display modes. The above also assumes that the shell implements \e, which not all shells do (C-shells notably do not).
Finally, a quick crash course on manual pages, manual pages versus info, and why manual pages are orders of magnitude better, and still a standard, because that is bound to come up sooner or later:
https://news.ycombinator.com/item?id=11927525
Is there an advantage to overriding the man command over the approach of just directly exporting the env variables in bashrc? I currently do the latter and I don't override the man function. I suppose overriding the man function would allow for man-specific customizations, but perhaps there are other good reasons too?
You might not want to override termcap for less in other contexts. Or not in the same way.
Are man pages basically just a slab of informally structured prose, or do they stick to some sort of grammar? I.e. Can they be parsed? Can I query one for something like "the meaning of the command line short option -a", or am I stuck trying to use the pager's search functionality for "-a"?
Mandoc, the default manpage formatter in OpenBSD, Illumos, Minix, and some Linux distributions, does semantically parse manpages. The latest version even uses less’s tags functionality to allow jumping to flag definitions. For example, if I “man ls”, I can then type :tx to go to the definition of the -h flag, without hitting any false positives like a text search might.
http://mdocml.bsd.lv/
http://mdocml.bsd.lv/
That is awesome, ... and it cures the stupid underline disease!
What I'm talking about is that text which is marked up as a code (monospaced font) in the troff source being rendered annoying as bold and underlined! That creates ambiguities with actual underline characters and general readability nuisance.
With these settings, the underlining is gone.
What I'm talking about is that text which is marked up as a code (monospaced font) in the troff source being rendered annoying as bold and underlined! That creates ambiguities with actual underline characters and general readability nuisance.
With these settings, the underlining is gone.
I use vim to get colorized pages and drill down to other referenced man pages. Search for MANPAGER in:
http://www.pixelbeat.org/settings/.bashrc
http://www.pixelbeat.org/settings/.bashrc
Oh, this is wonderful. For the last few years, I've been going out of my way to add color to my terminal output, making use of things like COPE and zsh-syntax-highlighting. This will be a wonderful addition to that.
There is also a vimscript to turn vimpager into a man pager, which supports basic colouring.
Hmm, man is colored and has been for a few years or so on my box by default?
doesn't work very accurate for me. tried with `man curl`
Compared to the original formatting, this colorization does the following:
- normal text stays the same color,
- bold text (bright white) becomes red,
- underlined text becomes green,
- inverted text becomes yellow-on-blue
However, if the original does not use bold or underlined text to emphasise parts of the text, this re-formatting has no effect. This is what happens in the curl documentation, where the command-line options are in regular text rather than bold text.
- normal text stays the same color,
- bold text (bright white) becomes red,
- underlined text becomes green,
- inverted text becomes yellow-on-blue
However, if the original does not use bold or underlined text to emphasise parts of the text, this re-formatting has no effect. This is what happens in the curl documentation, where the command-line options are in regular text rather than bold text.
Beautiful. Thanks. :)
Storming into the 1980s...
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...