Re: [Groff] colorized man pages

[Ingo Schwarze]

Hi Tadziu,

Tadziu Hoffmann wrote on Tue, Aug 23, 2016 at 01:29:07AM +0200:

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

Cynthia Livingston started that work in 1989 on behalf of the USENIX
association and completed it before the release of BSD Net/2 in
August 1991.  The first version of the Linux kernel was released a
few months later, in October 1991.  Rik Faith started the Linux
man pages project in 1993, Andries Brouwer took over in 1995.

> Ingo Schwarze wrote:

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

Exactly, the trick is trivial, and just as you explain, its effect
is rather limited, but the text describing it was very long; that
is what i was referring to as "pointless chatter" and "huge labor".
That great length gave the impression that something important and
clever was being done, while actually, neither was the task properly
described in the text, nor the most widespread solution mentioned.

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

That is true for the Linux manpages project, which still uses the
man(7) language for manual pages, and for some other projects, in
particular GNU software, as far as that uses manual pages at all.
For BSD software, that statement has no longer been true since the
switch of almost all manpages to mdoc(7) 25 years ago, and various
other projects also use mdoc(7).

> Manpages work because humans are
> good at guessing information from the context.

True.  That applies to human language in general, if i understand
correctly.

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

Specifically, the code in tmac/doc*.  Maybe you are right
that "preprocessing" is a slightly imprecise expression
for "macro expansion".  It's not a preprocessor in the
sense of tbl(1) or eqn(1).

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

The first version of OSF/1 was released in January 1992.  Even
though Net/2 was already available at that point, OSF/1 was still
mostly based on 4.3-Reno, which already contained Version 2 of
Cynthia's new macroset, but only a small number of manuals were
translated before the release of Reno.  So it seems that DEC copied
Cynthia's idea, but their implementation wasn't picked up by others
- which is not surprising given that the conversion in BSD (to
Version 3 of Cynthia's macros which have been available in groff
ever since and which FreeBSD, NetBSD, OpenBSD, DragonFly, and illumos
still use today) was already complete by the time OSF/1 was released.
Why would anybody have spent the time to redo those two years of
work?

> Ultimately, they're intended to be read by humans, and if
> humans understand them their purpose has been achieved.

Very true.  In addition to that, and less importantly, semantic
searching is at times useful.  And *if* people want semantic markup
(which started this thread), they can have it (of course, as you
say, only for those manuals that contain semantic markup in the
first place).

Yours,
  Ingo