Re: [groff] soelim: Ignoring Some ’so’ Requests

[Ralph Corderoy]

Hi Jeff,

> A traditional idiom for doing this was calling ‘so’ with the no-break
> control character, e.g.,
>
> 'so /usr/lib/tmac/tmac.m
>
> This probably wouldn’t be the preferred way of doing things anymore

I see no reason to demote it.  :-)
soelim(1) from heirloom-doctools says

    Note that inclusion can be suppressed by using ‘'’ instead of ‘.’,
    i.e.
            'so /usr/ucblib/doctools/tmac/s

> I can’t find any mention of this in the groff documentation.

I think groff's info has empty sections for `gsoelim'.

    File: groff.info,  Node: gsoelim,  ...

    6.8 'gsoelim'
    =============

    * Menu:

    * Invoking gsoelim::

    File: groff.info,  Node: Invoking gsoelim,  Prev: gsoelim,  Up: gsoelim

    6.8.1 Invoking 'gsoelim'
    ------------------------

> The careful reader of the groff soelim man page will see that the same
> thing can be accomplished by putting whitespace between the standard
> control character and the request (e.g., “. so”)

But doesn't suggest why that's useful.

Whilst looking at this, I noticed groff's info says

    -- Request: .so file
       ...
       Since 'gtroff' replaces the 'so' request with the contents of
       'file', it makes a difference whether the data is terminated with
       a newline or not: Assuming that file 'xxx' contains the word
       'foo' without a final newline, this

            This is
            .so xxx
            bar

       yields 'This is foobar'.

A Unix (POSIX) text file is zero or more lines, each terminated by ASCII
LF.  If a non-empty file doesn't end with LF then it's not a text file,
and traditionally various Unix programs would silently ignore that
trailing noise so it was a bad idea to import foreign programs that
created such corruption.  ;-)  Should groff's documentation be
encouraging such practice?  Does it work?

    $ cat nontext
    This is
    .so emacs.bin
    bar.
    $ od -c emacs.bin
    0000000   f   o   o
    0000003
    $ groff -Tascii -s nontext | sed '/^$/q'
    This is foo bar.
    $
    $ soelim nontext
    .lf 1 ./nontext
    This is
    .lf 1 ./emacs.bin
    foo
    .lf 3 ./nontext
    bar.
    $

OK, the LF is being added to separate the `lf' request.  Turn those off.

    $ soelim -r nontext
    This is
    foo
    bar.
    $

soelim must still add it.  It's not in the input.

    $ LC_ALL=C strace -e trace=read soelim -r nontext
    ...
    read(3, "This is\n.so emacs.bin\nbar.\n", 4096) = 27
    This is
    read(4, "foo", 4096)                    = 3
    read(4, "", 4096)                       = 0
    foo
    bar.
    read(3, "", 4096)                       = 0

And can't that effect be portably obtained with `\c'?

    $ cat text
    This is
    .so continued
    bar.
    $ sed -n l continued
    foo\\c$
    $ groff -Tascii -s text | sed '/^$/q'
    This is foobar.

    $

I think groff's documentation should acknowledge an old technique, say
it was never a good idea, that it doesn't work with groff, and that `\c'
can achieve the desired result.

Heirloom does handle it.

    $ /usr/heirloom/bin/ucb/soelim nontext
    This is
    foobar.
    $

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy