Re: [TUHS] man-page style

[Steffen Nurpmeso <steffen@sdaoden.eu>]

Chet Ramey wrote in <e8810295-5146-e126-a4d8-65e814f4b431@case.edu>:
 |On 11/16/18 4:13 PM, Jon Steinhart wrote:
 |
 |> Well, not wanting to start a flame war here, but I don't use emacs. \
 |>  While
 |> it's a good piece of software, I just want a text editor.  Emacs sort of
 |> violates my UNIX-sense as it does many things instead of doing one thing
 |> well.
 |
 |That's fine. Everyone gets to use whatever they want.
 |
 |> But really the issue is that info introduced a new interface on a system
 |> that already had one that people were accustomed to.
 |
 |Improvement is in the eye of the beholder. RMS and other folks consider
 |info, with its hyperlinks, indexes, and tree-based navigation the superior
 |alternative.  Not just different, but better.

roff, however, does provide the power to support all that: all
you need to do is to write the macros that do this for you.
One thing i have never understood is that.  Just do it.  I always
wondered at first when i saw coming along the blue links in the
man markup that the Linux world introduced.  Which is very
half-assed!

Mind you, i have to say, i actually have written such a thing for
the mdoc(7) manual macros (called mdocmx), and it gives you
interactivity on a normal terminal, or in HTML, or in PDF, it
gives you TOC and it could give you more.  I couldn't even live
without it no more, it improves living with the large manual of
the MUA i maintain tremendously.

Half-assed, too, is that even after fourty or more years of Unix
manual pages you cannot even search properly in a displayed manual
page, or at least you will not find anything that uses the usual
and old-style BS formatting sequences (that my mdocmx uses to
embed the informations, for example).  I never thought about that,
but Jörg Schilling mentioned that his pager (as simply as it may
be) is capable of doing so (by reduction, he said, though).

But the largest pain is non-existent, incomplete, or unfindable
documentation.  This cannot be said about bash or mksh, not about
tmux or screen, not about the documentation of Plan9, and not
over the MUA i maintain i hope.  But i have just moved over to
Linux on bare metal, and even though the Linux man-page project
has made an _immense_ effort and has achieved equal improvements,
it took a long time to get all this going (on a minimal
Distribution which does not do all of that automatically for you,
because years of experience have created an internal database full
of hints which are used to do-the-right-thing).

I could actually enumerate a scary long list of problems (on two
old notebooks, a MacBook Air and an Acer Aspire, external Seagate
USB disk, USB WLAN), but from back in the Eighties or even older
is that US keyboard do not honour "ISO_Level3_Shift" unless
setxkbmap 'us(intl)' is called.  I mean, you use xev(1) and the
event flies by, but the driver does not do anything with it.  How
do you find that out.  Just like with many other things you have
to face a lot of those toilet writings that make up the internet
before you get something good.  The ArchLinux wiki is very often
a useful and helpful source, but better not look in the web
support forums of the large distributions, who get paid, if you
can look into them at all.

It seems the wonderful tradition of HOWTOs or good things
including documentation under /usr/share (on BSDs) has been
entirely lost.

--steffen
|
|Der Kragenbaer,                The moon bear,
|der holt sich munter           he cheerfully and one by one
|einen nach dem anderen runter  wa.ks himself off
|(By Robert Gernhardt)