Re: [Groff] .if !dTS - GNU extension?

[James K. Lowden]

On Sun, 1 May 2016 15:29:19 +0200
Ingo Schwarze <address@hidden> wrote:

> Besides, your idea causes an unreasonable amount of work and bloat.

My idea is evidently at odds with your goal to replace the entire
manual viewing & formatting subsystem.  I don't share that goal.  

> It doesn't just add a command line option to mandoc(1), which i
> consider almost prohibite bloat all by itself, 

You said that once already.  Any code can be be pejoratively labelled
"bloat" if the speaker considers unheipful.  What you're really
saying is that you're uninterested in helping people use mandoc without
adopting it as the user interface.  

> but requires changing *all* the man(1) programs, and basically, each
> system has its own of these.

Isn't that exactly what you propose to do?  Or is replacing a program
not changing it?  I consider changing a configuration file to be much
less intrusive, and easier, than replacing a binary.  

NetBSD + mandoc has been a net loss in functionality for me so far.
Apropos is less convenient, see below.  And the 5% of pages that don't
format correctly unfortunately include several that I frequent.  

> (groff.7 and groff_ms.7 are two examples of files mandoc can't
> render.)
> 
> The best way to deal with that is to make your packaging system
> install manual pages that use some of the more arcane groff extensions
> not supported by mandoc, or some gory low-level roff(7) not supported
> by mandoc, as preformatted files rather than as source code.  

Best?  Defined how?  Who says the man pages in question come through
the packaging system, and not from Github?  

As far as I can tell, you're defining "best" in terms of the goal of
delivering a base OS without a troff dependency for manual display.  I
really don't understand why you consider that desirable.  I would like
to see groff used more, not less.  

Ingo, even if I felt cooperative, you know, I'm cut off at the
beginning. Mandoc offers, last I checked, no way to verify correct
formatting except by visual inspection, and does not document what
subset of troff requests and macros it supports. Instead of "use mandoc
and fall back to troff on error" as a policy, mandoc implicitly demands
all-or-nothing adoption.  

> > Have you experimented with a single index for all man pages?
> 
> No.
> 
> > I wonder how useful that would be,
> 
> Not useful at all.  

So, lacking data, your conclusion is based on your assumptions.  

The rest of your answer is a list of specious objections based on
erroneous design choices.  The very idea that an index need rely on
output format is ridiculous.  The point of using an index is *not* to
use apropos, which is a much more generalized search.  

I can believe that searching for "read" in an index would be better
than scanning the page text with less.  That's what interested me to
start with.  By the same token, searching more than one page would
bring novel functionality that has been lacking in Unix man pages since
their inception (afaik).    

And, no, apropos is not the answer.  For example, let's look for socket
functions.  

$ man -k -l socket
socket(n) - Open a TCP network connection
curl_multi_socket_action(3) - reads/writes available data given an
action curl_multi_socket(3) - reads/writes available data
CURLOPT_UNIX_SOCKET_PATH(3) - set Unix domain socket
CURLOPT_OPENSOCKETFUNCTION(3) - set callback for opening sockets
CURLOPT_OPENSOCKETDATA(3) - custom pointer passed to open socket
callback CURLOPT_EGDSOCKET(3) - set EGD socket path
CURLOPT_CLOSESOCKETFUNCTION(3) - callback to socket close replacement
function CURLOPT_CLOSESOCKETDATA(3) - pointer passed to the socket
close callback CURLMOPT_SOCKETFUNCTION(3) - callback informed about
what to wait for CURLMOPT_SOCKETDATA(3) - custom pointer passed to the
socket callback BIO_s_socket(3) - socket BIO
socket(2) - create an endpoint for communication
socketpair(2) - create a pair of connected sockets
dbus-cleanup-sockets(1) - clean up leftover sockets in a directory

Do you think that's atypical?  apropos doesn't respect section
numbers.  To get what I want, 

$ man -k -l socket | grep '(2)'
socket(2) - create an endpoint for communication
socketpair(2) - create a pair of connected sockets

but of course I have to *know* that, and I have to accept the idea that
I might miss something.  Like, say, unix(4).  Or bind(2), which
apropos used to return.  How did that get lost?  

> If apropos(1) tells you which page to look at

        $ man -k socket | wc -l
            1398

It doesn't.  The information density of that output is near zero.  Just
casting a wider net does not yield better results.  I'm amazed anyone
thinks 1400 lines of "socket" context is useful.  

What I would like is a comprehensive index of functions relevant to
socket(2).  From what I have read, good indexes can't be generated
automatically.  That suggests to me that index-generation should be
seeded by automatic construction (from the .Nd tag, say), and then
amplified/filtered by incremental user-supplied inputs.  If all bug are
shallow given enough eyeballs, indexes should be, too.  

Your presentation slides, and your argument here, characterize unified
documentation as primarily a technical problem made somewhat more
difficult by the confounding use of nonsemantic markup.  I suggest to
you that's only partly true.  Documentation is written by and for
people, and the meaning of the language will for the foreseeable future
be beyond the ken of the machine.  "Just use apropos" will never be the
solution.  

--jkl