formatting man pages in email (was: Assignment to RO variable)

[G. Branden Robinson]

At 2023-08-15T23:24:31-0500, Dennis Williamson wrote:
> From man bash:
> 
> readonly [-aAf] [-p] [name[=word] ...]
>               The given names are marked readonly; the values of these
> names may not be changed by subsequent assignment.  If the -f option is
> supplied, the functions
>               corresponding to the names are so marked.  The -a option

That man page quotation came out somewhat awkwardly.

I often find myself quoting man pages in email, so I have a shell
function for this scenario.  I call it "mailman", fully aware that
that's also the name of mailing list manager.  (Even if I ran it, I
wouldn't ever do so at an interactive shell prompt, because it's a
daemon.)

    mailman () {
        local cmd= opts=
        case "$1" in
            (-*)
                opts="$opts $1"
                shift
                ;;
        esac

        set -- $(man -w "$@")
        cmd=$(zcat --force "$@" | \
            grog -Tutf8 -b -ww -P -cbou -rU0 -rLL=72n -rHY=0 -dAD=l)
        zcat --force "$@" | $cmd | less
    }

This relies upon man-db man(1)'s `-w` option to locate the requested
pages (and it does the right thing if you specify file names, not just
page topics).

It also uses grog(1), much improved in groff 1.23.0 (released 5 July),
to figure out which preprocessor(s) and macro package the document
needs.

I'll walk through those groff options.

* `-Tutf8` formats for a UTF-8 terminal.
* `-P -cbou` passes options to grotty(1) to turn off all ISO
  6429/ECMA-48 escape sequences, _and_ all overstriking sequences; their
  formatting effects won't come through in plain text email anyway.
* `-rHY=0` turns off hyphenation.
* `-rLL=72n` sets the line length to 72 ens (character cells), which
  helps prevent ugly line wrapping.

Two options are new groff 1.23 features.

* `-rU0` turns off hyperlink support, so that any URIs in the man page
  will be formatted as text.  This is a new groff 1.23.0 feature.
* `-dAD=l` turns off adjustment (the spreading of output lines).

Two more options are ones I use, but maybe only maintainers of man pages
want them.

* `-b` produces backtraces for any formatter warnings or errors.
* `-ww` turns on all formatter warnings.

I hope people find this useful.

signature.asc
Description: PGP signature