Re: [groff] improve a few terminal renderings of special characters

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sat, Sep 01, 2018 at 11:49:29PM +1000:
> Ingo Schwarze wrote:

>> I'd respectfully recommend the opposite approach:  Blacklist the (few)
>> systems where man -w is broken (if you don't want to test dynamically).

> Tips on testing dynamically? A `configure`-like script was my original
> idea, but I don't want tests to bring about unwanted side-effects for the
> user...

On a sane system, man(1) never writes anything to the file system
(except maybe to /tmp/ deleting the written files right afterwards,
if it needs to pass multiple files simultaneously to the pager).

On some traditional systems, man(1) used to write to preformatted
cache directories.  That's totally insane because it requires
installing man(1) SGID; some systems even installed it SUID for
that reason.  If you worry about that, you cannot use man(1) at
all.  But i'd say if any call to man(1), even a failing configure
probe, changes data on the target system, that's a bug in the target
system and not your fault.

So, just let your configure script try "man -w grep", if it returns
plausible results, use it, otherwise use "man -l" with the required
post-processing.

> There's also the issue of cat-paths being returned by `man -k` when the
> source files are required. I don't think I can just swap a few directory
> names out and expect to always find the unformatted version of a catted
> man-page. For example:
> 
> $ uname -a
> OpenBSD titan.my.domain 6.3 GENERIC.MP#8 amd64
> $ man -w groff_diff
> /usr/local/man/cat7/groff_diff.0
> $ stat /usr/local/man/man7/groff_diff.?
> stat: /usr/local/man/man7/groff_diff.?: No such file or directory
> 
> So this means we need to rely on man(1) having an option for *"un-catted
> pages only please"*.

That is impossible.  For example, on OpenBSD, we either (very
preferably) install only the unformatted version of a manual page,
or - if the unformatted version is of such terrible quality that
it cannot be rendered reliably without groff - we only install the
formatted version.  Incidentally, i switched the OpenBSD groff
package over from installing formatted to unformatted manual pages
about a week ago.  So on OpenBSD 6.3, you only have groff_diff.0
and no groff_diff.7, while on OpenBSD 6.4, you will only have
groff_diff.7 but not groff_diff.0.  Still, about 25 out of about
10000 packages remain that have to install formatted.  All this is
totally system dependent, of course; but i'd be rather surprised
if there weren't other systems out there installing some pages
formatted and some unformatted.  If you want access to all manual
pages on a system, you likely need a program that can process both
formatted and unformatted pages.

More specifically, an option to portably ask for "unformatted only" 
doesn't exist in man(1).  The mandoc implementation certainly
provides no such thing.  With the traditional BSD implementation,
you could only do it by writing your own man.conf file.  Some other
of the vastly different config file formats might allow similar tricks,
but i don't know the details off the top of my head.  The comprehensive
option list i have shown gives me the impression that there isn't a
single implementation providing that feature as a simple option.

Yours,
  Ingo