Re: [Groff] colorized man pages

[Ingo Schwarze]

Hi James,

James K. Lowden wrote on Fri, Aug 19, 2016 at 12:07:22AM -0400:

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

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.

> It's a little far afield, but some here might be interested in the
> interest in manpages.  mdoc has no color features, leaving folks to
> resort to some pretty brutal techniques. 

Huh?  Of course mdoc does have color features.  Just use

  mandoc -Thtml -Ostyle=/some_path/color.css manual.mdoc | lynx -stdin

With the mandoc implementation of man, it shouldn't be difficult
to set up MANPAGER="lynx -force_html",
put "output style /some_path/color.css" into man.conf(5), and tell
the shell "alias man='man -Thtml'".  All of that has been documented
in the obvious manual pages for years: You could use -Ostyle in the
alias before the advent of man.conf(5).

That way, saying "man command", you get colored manual pages that
show each mdoc(7) macro in its own color.  Of course that isn't
possible with [g]roff because [g]roff already throws away the
information about macros in the preprocessor.  That's not a fault
of groff:  Groff is an excellent typesetter, but roff was never
intended as a semantic markup system for manual pages.

As a matter of fact, even if you do *not* write any style sheet,
but use nothing but these two simple lines,

  export MANPAGER='lynx -force_html'
  alias man='man -Thtml'

you get each macro in its own color already:  It seems that lynx(1)
picks different colors by default for different <... class="..."> tags.
I just tried it on OpenBSD, and it is likely to also work out of the
box on FreeBSD, NetBSD, DragonFly, illumos, Minix 3, Alpine Linux,
and Void Linux, and it ought to be easy to make it work on Debian
Linux, Arch Linux, Slackware Linux, and Crux Linux by installing
the readily available mdocml packages.  On Debian, you have to say
"alias man='mman -Thtml'" because that's the name Bdale Garbee
(reasonably) picked for the man(1) binary to not clash with the
default and well-established man-db package.  You can easily compile
mandoc from source on any Linux distro even if there are no packages,
and from pkgsrc on many other systems.

Now, i'm sure a few things could be made easier for the end user.

 1) I could provide a man.conf(5) command "format html"
    in addition to "output style" such that no shell alias
    would be needed (or even make that implicit in "output style").
 2) I could provide a man.conf(5) command "pager" such that
    users wouldn't need to set MANPAGER.
 3) I could provide a file color.css in the mandoc distribution
    such that users wouldn't need to write one themselves.
    I could define a standard path to place it, maybe /etc/man.css
    in the vicinity of /etc/man.conf.
 4) I could improve the actual tags used in the HTML code to
    match the macro names, which are already used in apropos(1)
    for semantic searching instead of inventing new names
    for the tags, to make remembering them easier for users.

Even though this functionality has been available for about half
a decade, i never worked on it, basically for two reasons:

 1) There is no demand.  It almost never happens that anybody asks
    for it.  If any mention it, it's usually windbags who talk a
    lot, don't do actual work, and understand almost nothing.
    I have shown above the two commands needed to do it on the
    console.  Of course, it's even easier for web manuals.  It would
    be trivial to implement this on man.openbsd.org (which also
    serves the Linux man pages project pages, by the way; of course,
    those wouldn't get coloring because they still use the obsolete
    1979 UNIX v7 man(7) format).  All that would be required would
    be a few trivial additions to the CSS file on the server.  But
    literally, nobody ever wanted it.  If somebody would want it,
    i might add a checkbox "use color", it would be much less than
    a day of work to get it up and running in production.

 2) Personally, i very strongly hate any kind of color in text
    display, and syntax highlighting in particular - no need to
    say that syntax highlighting using heuristic guesswork is
    harmful because it often guesses wrong and than adds
    wrong and misleading markup - but colorized mdoc(7) would be
    flawless, it wouldn't need to guess, it *knows* the syntactic
    function of words.  I would still strongly hate it,
    i simply consider any kind of color in text distracting.

All that said, it would also be trivial to directly add color
support to console (-Tascii, -Tutf8, -Tlocale) man(1) output
in the mandoc distribution - a few days of easy work, maybe.
But i might reject such a patch even if somebody would write it,
given the lack of demand, striving to keep the code simple.
If there were demand, i might consider it.

So, no demand from others and hating it myself - that's why even
though it's available and documented for half a decade, i never
worked on it and never mentioned it in any of my half a dozen
conference talks on manual pages.

In any case, Walter Harms can be unafraid:  I promise that i will
never make color output the default, but keep the default at as
it is.  He is right, accessibility is yet another reason for that.

Yours,
  Ingo