Colorized man pages

http://boredzo.org/blog/archives/2016-08-15/colorized-man-pages-understood-and-customized

by ingve • 10 years ago

358 98 10 years ago

boredzo.org

mih• 10 years ago

If you're using oh-my-zsh, you can just enable the colored-man-pages plugin

tomtomtom777• 10 years ago

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

jlebrech• 10 years ago

yep, I can't tell the difference. oh-my-zsh much have it by default

kseistrup4• 10 years ago

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

http://www.jedsoft.org/most/

neuromute2• 10 years ago

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.

kseistrup4• 10 years ago

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.

therealmarv• 10 years ago

omg, why do I discover this only now? thanks.

karl42• 10 years ago

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.

pbhjpbhj3• 10 years ago

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

znpy• 10 years ago

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.

andlrc• 10 years ago

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.

lucb1e• 10 years ago

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.

Symbiote2• 10 years ago

It's using Emacs keybindings, so the shortcuts are ^N and ^P.

Space and backspace are equivalent to page down and page up.

kseistrup4• 10 years ago

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

eriknstr3• 10 years ago

My first reaction exactly!

devnonymous• 10 years ago

Or pinfo which supports both man and info pages.

Symbiote2• 10 years ago

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 )

rangibaby• 10 years ago

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

allendoerfer• 10 years ago

People would need to use tabs (gasp) instead of spaces for that :-P

That would be madness.

Senji• 10 years ago

You could just do a naive 4spaces to 1tab conversion.

voltagex_• 10 years ago

I'm 99% sure those are colour control codes, but what does that huge env string actually do?

coldtea3• 10 years ago

Temporarily adds the LESS env settings below on top of your existing env entries, for as long as you run man.

lake99• 10 years ago

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.

pbhjpbhj3• 10 years ago

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

anjbe2• 10 years ago

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

kiiski• 10 years ago

One could also use Emacs (in a graphical window rather than in the terminal) `woman` and `variable-pitch-mode`.

amyjess5• 10 years ago

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:

    $ kwrite 'man:/usr/share/man/man1/ls.1p.gz'

KIO man also offers indices, as well. For example, you can get a list of all commands by going to man:/(1)

ckastner• 10 years ago

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.

thristian• 10 years ago

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.

coldtea3• 10 years ago

That assumes that the terminal has full-color support.

As it should (assume and have) in 2016.

kccqzy2• 10 years ago

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

zo7• 10 years ago

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

0942v8653• 10 years ago

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.

AceJohnny24• 10 years ago

On OS X 10.11.6, Preview fails with "The PostScript file "open_afberandom.txt" could not be converted to a PDF file." :(

dkharrat• 10 years ago

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• 10 years ago

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

tuananh• 10 years ago

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

bramblerose• 10 years ago

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.

keeperofdakeys• 10 years ago

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

akerro2• 10 years ago

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

phunehehe0• 10 years ago

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

akerro2• 10 years ago

Most often it's really nice looking. https://gitlab.com/agilob/.files/raw/4249f5d58aca984ef32af76...

wtbob• 10 years ago

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.

IshKebab• 10 years ago

Storming into the 1980s...

pixelbeat• 10 years ago

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

cpr• 10 years ago

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• 10 years ago

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

Myrmornis• 10 years ago

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

anjbe2• 10 years ago

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/

gautamsomani• 10 years ago

Beautiful. Thanks. :)

pwenzel• 10 years ago

For my Fish shell comrades, see http://askubuntu.com/a/650192.

amyjess5• 10 years ago

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.

AceJohnny24• 10 years ago

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

BurningFrog• 10 years ago

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

akkartik• 10 years 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

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

a3n• 10 years 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

AceJohnny24• 10 years 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.

noselasd• 10 years ago

Do yourself a favor and install pinfo - an info viewer that's actually usable.

Animats• 10 years ago

"info" is much like gopher, but less well designed.

throwanem3• 10 years 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.

ansible2• 10 years ago

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.

fanf2• 10 years ago

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

ralph2• 10 years ago

`info foo | less' has it produce the whole "page" as plain text, suitable for easy reading and regexp searching.

benwaffle• 10 years ago

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

eriknstr3• 10 years 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.

ralph2• 10 years 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.

noobermin• 10 years ago

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

gnyman• 10 years ago

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.

to3m• 10 years ago

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.

rurban• 10 years ago

I like that, thanks!

kazinator2• 10 years ago

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.

Annatar• 10 years ago

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

kazinator2• 10 years ago

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

javaJake• 10 years ago

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

Colorized man pages

Related Stories