
Colorized man pages - ingve
http://boredzo.org/blog/archives/2016-08-15/colorized-man-pages-understood-and-customized
======
AceJohnny2
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...](https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.html)

~~~
throwanem
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
_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.

~~~
glandium
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.

~~~
throwanem
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.

------
Symbiote
It would be nice if we made better use of full-colour terminal support.

    
    
        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 "$@"
        }
    

And it would be really nice if I could read man pages in the terminal in a
proportional font, but preserving alignment etc.

(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](https://git.gnome.org/browse/vte/tree/perf/img.sh?h=vte-0-36)
)

~~~
lake99
> 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.

~~~
pbhjpbhj
I don't understand 3.? Konqueror is the KDE3 web browser - how's that relevant
here?

~~~
amyjess
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).

~~~
pbhjpbhj
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.

~~~
amyjess
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.

------
kseistrup
Or you could just use most(1) as MANPAGER.

[http://www.jedsoft.org/most/](http://www.jedsoft.org/most/)

~~~
lucb1e
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.

~~~
kseistrup
Key bindings can be configured in ~/.mostrc, read most(1).

------
mih
If you're using oh-my-zsh, you can just enable the _colored-man-pages_ plugin

~~~
tomtomtom777
Although the author uses zsh, the function works other shells as well; at
least on bash.

------
akerro
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)

~~~
phunehehe0
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...

~~~
akerro
Most often it's really nice looking.
[https://gitlab.com/agilob/.files/raw/4249f5d58aca984ef32af76...](https://gitlab.com/agilob/.files/raw/4249f5d58aca984ef32af761b6366d6383c15e2c/man_page.png)

------
kazinator
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:

    
    
        VAR1=val1 VAR2=val2 ... command
    

However, env here is serving the purpose of avoiding unwanted recursion,
because "env man" runs the external man rather than the function. But we can
get that with the "command" builtin, or by using "/usr/bin/man":

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 "$@"
      }

------
pwenzel
For my Fish shell comrades, see
[http://askubuntu.com/a/650192](http://askubuntu.com/a/650192).

------
javaJake
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...](https://lists.gnu.org/archive/html/groff/2016-08/msg00034.html)

Thread root:
[https://lists.gnu.org/archive/html/groff/2016-08/msg00013.ht...](https://lists.gnu.org/archive/html/groff/2016-08/msg00013.html)

------
gnyman
For people on OS X I recommend checking out Bwana
[https://www.bruji.com/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.

~~~
to3m
If you like bwana, you could try my updated copy:
[https://bitbucket.org/tom_seddon/bwana](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.

~~~
rurban
I like that, thanks!

------
Annatar
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!):

    
    
      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
    

this code is portable and should work on every Bourne-family shell from the
original '70's Bourne shell all the way to ksh93 and bash without
modification; if it does not, it is a bug in the shell interpreter. Bug your
operating system vendor to fix the interpreter program.

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](https://news.ycombinator.com/item?id=11927525)

------
dkharrat
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?

~~~
JoshTriplett
You might not want to override termcap for less in other contexts. Or not in
the same way.

------
Myrmornis
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"?

~~~
anjbe
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/)

------
cpr
Is the "env" really necessary?

I thought if you just prefixed the eventual 'man "$@"' with those environment
variable settings that it would have the same result.

~~~
ksherlock
sure, except instead of running [/usr/bin/]man, it will run the man shell
function.

------
kazinator
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.

------
pixelbeat
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)

------
amyjess
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.

------
keeperofdakeys
There is also a vimscript to turn vimpager into a man pager, which supports
basic colouring.

------
noobermin
Hmm, man is colored and has been for a few years or so on my box by default?

------
tuananh
doesn't work very accurate for me. tried with `man curl`

~~~
bramblerose
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.

------
gautamsomani
Beautiful. Thanks. :)

------
IshKebab
Storming into the 1980s...

