Re: [Groff] colorized man pages

[Tadziu Hoffmann]

> Raw VT-100 escape sequences, in 2016.  Where will it all end?

Steering wheels.  On cars.  In 2016.  Where will it all end?

Seriously:  what's wrong with escape codes?  I mean, if you're
still working with a text terminal, I'd expect escape codes to
be your daily bread and butter, not something to scoff at.
(Unless I'm missing the good-natured, approving irony here?)

(Of course, for the sake of being terminal-independent, they
should have used tput to retrieve the correct codes from the
terminfo database.  But on the other hand, I'd wager most
terminals in use these days use the ANSI/ECMA escapes.)


> It shouldn't be too much work to instrument a few important
> man and mdoc macros and add an environment variable, say,
> MANUAL_COLOURS, in equal spirit to LS_COLORS.  In the Linux
> world there is now a dircolors(1) command which can be used
> to control LS_COLORS.

Coloring ls output adds semantic information from the mode
bits and the file type (normal files, device files, fifos,
links, etc.).  The "colored manpages" trick really has
nothing to do with man, it simply colors bold and underline
in the terminal.  To perform the equivalent of dircolors with
manpages will require actually rewriting the manual pages
and adding semantic information by hand (a *lot* of work).


> But one factor nobody's mentioned is the fact that some users
> are color blind, and the wrong combination of colors can make
> a page very difficult to read, and that is NOT what's needed.

Just like some people have difficulty reading one particular
font or the other.  Everyone's free to chose what works best
for them, be it colors or typefaces.  Nobody is mandating
Comic Sans for everybody.


> Black text on a white background has always worked well.

On paper, using ambient light, yes.  On a self-luminous screen,
large areas of white are too bright and are hard on the eyes.
Light gray or pastels work much better.  (Plus, this leaves
some brightness headroom for important stuff that needs to
be conspicuous.)


> Adding colours to manual-pages is a solution to a problem
> that doesn't exist. It's purely aesthetic.

Decidedly not.  It's in the same league as highlighting
words in bold or italic/underline.  Or are you saying that
this is superfluous as well?  Compare the following:

  zcat /usr/share/man/man1/bash.1.gz | GROFF_NO_SGR=yes nroff -man | less
  zcat /usr/share/man/man1/bash.1.gz | GROFF_NO_SGR=yes nroff -man | col -b | 
less

I prefer the former.

Another thing to keep in mind is that not all terminals can
display bold text (meaning a different typeface); some of them
substitute text with higher brightness.  It does strike me as
reasonable to give users some choice in the matter by allowing
them to switch to a different color instead (or in addition).
Gnome-terminal already has a built-in option to colorize bold
text.  Other terminals (such as xterm) can display italic text
in addition to underlining.  So the trick can be used to
display the underlining traditionally used by nroff as italics:

  LESS_TERMCAP_us=`tput sitm`
  LESS_TERMCAP_ue=`tput ritm`

This looks rather nice in manual pages, and leaves underlining
in the terminal (outside of less) free for other purposes.


> I despise such pointless chatter.  It makes a lot of
> stupid words about a trivial matter without being aware
> that a ready-to-use solution for a large superset of the
> task has long been available.  Sure, you can invest huge
> labor to trivially repaint the bikeshed: Change bold to
> red and underlined to green - but that doesn't provide any
> additional information or even additional standout features
> to the reader.

Why this bitterness?  The trick discussed is trivial to
apply (but useful), not "huge labor".  And regarding the
"ready-to-use solution" that has "long been available":
for the most part, the semantic information is simply not
encoded in the manpages.  Manpages work because humans are
good at guessing information from the context.


> Of course that isn't possible with [g]roff because [g]roff
> already throws away the information about macros in the
> preprocessor.

Uh, no.  (What preprocessor, by the way?)  Apart from bold
and italic, the information simply isn't there.  And if it
were, you could of course transfer it to the output by using
a different implementation of the manpage macros.
This has nothing to do with the *roff syntax per se, but
rather with what has been captured by the manpage author.

I think we have gone over this topic before on this list,
ad nauseam.  A long time ago, DEC had added semantic
information to their manual pages (all in [nt]roff format).
They called it "OSF Reference Semantic Markup Language"
and distinguished between ordinary text, emphasis, literals,
variables, alphabetic constants, numeric constants, system
(user) input, and system (computer) output, together with
markup descriptions of headings, lists, figures, etc.
Notwithstanding the effort, it hadn't really caught on.
My guess is because existing manual pages were "good enough".
Ultimately, they're intended to be read by humans, and if
humans understand them their purpose has been achieved.