Re: [Groff] Compression support for files?

[Ingo Schwarze]

Hi Steffen,

Steffen Nurpmeso wrote on Fri, Jul 18, 2014 at 01:16:31PM +0200:

> No, the original intention was to extend the `.so' request
> in a way that makes it possible to use it like in this example
> i've used for testing:

Unfortunately, your example is broken in multiple ways and can
hardly be amended to make it work, so it doesn't demonstrate
the usefulness of your intent at all.

> what.1:
> 
>   .Dd June 6, 1993
>   .Dt WHAT 1
>   .Sh NAME
>   .Nm what
>   .Nd "show what versions of object modules were used"
>   .Sh SYNOPSIS
>   .Nm
>   .Ar name Ar ...
>   .Sh DESCRIPTION
>   .Nm
>   reads each file
>   .Ar name
>   and searches for sequences of the form
>   .Dq \&@(#) ,
>   as inserted by the source code control system.
>   .so what-hist.1

That is not going to work.  As the man(1) utility chdir(2)'s to
the $MANPATH directory, e.g. /usr/share/man/, this would search
for a file what-hist.1 in the root of the $MANPATH, that is,
/usr/share/man/what-hist.1, which is certainly not where you
intend to store it.  If you wanted to store it alongside what.1,
you would have to write

  .so man1/what-hist.1

which is a bad idea as well.

> what-hist.1:
> 
>   .Sh HISTORY
>   The
>   .Nm
>   command appeared in
>   .Bx 4.0 .

If you store that as /usr/share/man/what-hist.1, man(1) will
try to serve it when someone says "man what-hist" and fail
catastrophically.  With groff, the output is:

  $ man what-hist
  The command appeared in
  [... and many blank lines]

With mandoc(1), the output is (whitespace slightly edited
to be readable in email):

  $ man what-hist
  unknown(1)                                              unknown(1)

  The command appeared in

                            July 18, 2014                 unknown(1)

Tools like makewhatis(8) are likely to do the wrong thing as well.

You might try the move the included file out of the $MANPATH.
But that's not going to work either.  At least mandoc(1) firmly
refuses absolute paths in .so requests, to avoid having man(1)
inadvertently display confidential files on the screen, visible to
bystanders, when viewing malicious manual pages as root.

Using .so in manuals is a terrible idea in the first place.
The only application that sort-of works half of the time is as a
poor man's replacement of ln(1), like X.org deplorably uses it.
But even that is quite fragile and should be avoided:

  $ man XArc | head -n8
  XDrawArc(3)               XLIB FUNCTIONS               XDrawArc(3)

  NAME
       XDrawArc, XDrawArcs, XArc - draw arcs and arc structure

  $ mandoc -Tlint `man -w XArc` 
  mandoc: /usr/X11R6/man/man3/XArc.3:1:1: WARNING: .so is fragile,
      better use ln(1): .so man3/XDrawArc.3
  mandoc: man3/XDrawArc.3: SYSERR: No such file or directory
  mandoc: /usr/X11R6/man/man3/XArc.3:1:20: FATAL: .so request failed:
     .so man3/XDrawArc.3

  $ groff -Wall -mandoc -Tascii `man -w XArc`
  /usr/X11R6/man/man3/XArc.3:1: can't open `man3/XDrawArc.3':
      No such file or directory

There are certainly uses for .so when preparing large, private,
typeset documents, for example books.  But i cannot think of
any good way to use it when using roff(7) as an operating system
support language.

> Now if the manuals get compressed as they usually are

Only on some systems.

> then with the proposed patch `what-hist.1' will still be found
> and included, i.e., `.so' can actually be used, transparently.

No, all the above still applies.  It is still as unusable in
practice as it was before.  Besides, what do you want to use
it for?  You are going to include the HISTORY of what(1)
into multiple manuals?  That doesn't make any sense to me
whatsoever.

> This is new.

But still useless, unfortunately, at least in the example you
have put forward for demonstration...

Yours,
  Ingo