[TUHS] Another "craft" discussion topic - mindless tool proliferation

Thu Sep 21 02:39:21 AEST 2017

To me that is a problem of the tools and the roff macros, but not
of the Unix man system itself.  If you look at the entire man/ual
collection as a computer book, then that layout is pretty much
what you get.  It is mysterious -- to me -- why noone ever tried
to tweak the man toolchain itself, but wrote programs like Rosetta
man etc.  It is nothing but a doable problem in the roff
programming language and the toolchain which could have been
worked around decades ago, and you have active cross references at
the man(1)ual level.

Instead people go an incredibly hard way and use docbook or other
such solutions with an endless number of processing tools (like
Jade etc.).  And there is other needless bloat, NetBSD for example
installs a complete set of HTML versions alongside the normal man
pages, for a rather minimal benefit.  But even more absurd is that
in the Linux world people start using low-level roff directives to
produce (inactive) blue URL links, even though GNU/Linux has the
entire toolchain under control and could have done this in
a regular fashion, with active URLs for at least PDF and HTML
output variants.

 |But sometimes the extra complexity of, say, gdb or gmake, provides a
 |lot of convenience.  And the question is whether man is a sufficient
 |way to provide documentation.  I would humbly submit that the choice
 |of using man pages as used by perl is an existence proof that man is
 |*not* the optimal way to provide documentation for a sufficiently
 |complex language or program.

POD is not in my opinion, especially if used with extensive
cross-referencing.  The problem is that today people expect
references all over the place, not only at the bottom in a SEE
ALSO section, and occasionally at other places.  But for this you
have to use a completely different way of writing the
documentation than has been used traditionally on Unix.  And this
is not only about the people, it is about the non-existing
context.  Those programming IDEs that i do not use but do exist
give you tooltips whenever your mouse moves over just anything,
this now also on german wikipedia, for example.  For this you need
keywords which can be followed, to be specified in semantic
context.

The man macros simply do not offer that.  The BSD mdoc macros
extend this a bit but are hard to use and documenting C interfaces
is a nightmare.  I have written an extension for mdoc that gives
you the possibility to specify context and the manual of the MUA
i maintain, as well as the manuals of my future roff fork (but
that already i think) support that.  Even on the TTY, and i do not
want to miss having active links in less(1), document internal as
well as external, i use it all the time.  Unfortunately this is
restricted to very few manuals, and sometimes the chain of started
less(1) instances (following .Xr external references starts a new
less(1), after confirmation) gets pretty deep, and you have to
quit them all in order to come back to the original manual.  Well.

But because the mdoc macros use a recursive parser you cannot use
recursive macros, like headline macros which include
a cross-reference macro, for example, and the generated reference
can only be placed as a suffix because of that.
And of course mdoc is a crux.  Something new, implemented from
scratch, with all that web-of-context in mind, something like
man2, would be nice to have.  Maybe it could be source compatible
with man.

 |(If the answer is that Unix programs should never be that complicated;
 |that's fine.  But at least for me personally, I prefer to use gdb,
 |with its texinfo/info files, over adb with its man page.  If you want
 |to argue that "real programmers" should be able to decipher structure
 |layouts by looking at C structure declarations and creating adb macros
 |by hand, and that DWARF annotations are for the weak and sickly, fair
 |enough.  :-)

A good manual, which is up-to-date and refers to the actual
program and not to some former version, is a key feature.
It is hard to do that, and it is impossible to keep several
instances at that level.  Many OSS projects ship with incomplete,
outdated or completely useless manuals.  GNU versions often do not
do anything but referring to the info manual, which likely could
have been addressed decades ago by directly loading that, for
example: that you read at the bottom i think.

I liked to read the Plan9 manuals, these fantastic ones have
really written in a way that describes the interface sufficiently,
it actually enables you to start going.  If that takes a few
screen pages: that is just the way it is.

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