Re: How to avoid using '\c' in man pages

[G. Branden Robinson]

[Debian BTS users: please CC the groff list on replies.]

At 2023-05-29T19:15:32+0000, Bjarni Ingi Gislason wrote:
>   For a background material see Debian bug #1036826 or
> the home page of "Bug Reports" in Debian for the package "po4a".

That background is pretty important, because nothing you said after that
point in the message made any sense to me.

So I'll quote Helge Kreutzmann's original bug report:

>> .TP
>> .BI \-f " program-file\fR,\fP "\c
>> .BI \-\^\-file " program-file"
>> Read the \*(AK program source from the file
>> 
>> The "\c" causes the following (fatal) warning, i.e. no output:
>> 
>> Escape sequence \c encountered. This is not completely handled yet.

It is important for programs that interpret man pages to handle this.
It should be given some priority.  But I wouldn't be surprised if one
reason it hasn't already been is that there has historically been a lot
of mystique and folkore around the meaning of this roff escape sequence.

Some quotes from groff_man_style(7) from the forthcoming groff 1.23.0
release (now at release candidate 4) might help.[1]

    .TP [indentation]
        Set a paragraph with a leading tag, and the remainder of the
        paragraph indented.  A one-line input trap is planted; text on
        the next line, which can be formatted with a macro, becomes the
        tag, which is placed at the current left margin.  The tag can be
        extended with the \c escape sequence.  Subsequent text is
        indented by indentation, if specified, and by a default amount
        otherwise; see subsection "Horizontal and vertical spacing"
        below.  If the tag is not as wide as the indentation, the
        paragraph starts on the same line as the tag, at the applicable
        indentation, and continues on the following lines.  Otherwise,
        the descriptive part of the paragraph begins on the line
        following the tag.
[...]
    groff's own command-line interface serves to illustrate most of the
    specimens of synopsis syntax one is likely to encounter.

        .SY groff
        .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
        .RB [ \-d\~\c
        .IR cs ]
        .RB [ \-d\~\c
        .IB name =\c
        .IR string ]
        .RB [ \-D\~\c
        .IR enc ]
        (and so on similarly)
[...]
    Several features of the above example are of note.
[...]
    o The output line continuation escape sequence \c is used with font
      style alternation macros to allow all three font styles to be set
      without (breakable) space among them; see subsection "Portability"
      below.
[...]
    \c  End a text line without inserting space or attempting a break.
        Normally, if filling is enabled, the end of a text line is
        treated like a space; an output line may be broken there (if
        not, an adjustable space is inserted); if filling is disabled,
        the line will be broken there, as in .EX/.EE examples.  The next
        line is interpreted as usual and can include a macro call
        (contrast with \newline).  \c is useful when three font styles
        are needed in a single word, as in a command synopsis.

            .RB [ \-\-stylesheet=\c
            .IR name ]

        It also helps when changing font styles in .EX/.EE examples,
        since they are not filled.

            .EX
            $ \c
            .B groff \-T utf8 \-Z \c
            .I file \c
            .B | grotty \-i
            .EE

>> As a workaround I'm currently considering patching the source files
>> "on the fly" to get the build to proceed.
>> 
>> Until recently I was ignoring this message, because it implies that
>> just some detail is not properly handled; however I did not realize
>> that the build fails.

Now, quoting Bjarni's claims in the bug log, and adding in a bit more of
the original context...

> > .SH OPTIONS
> > .I Gawk
> > accepts the following options.
> > Standard options are listed first, followed by options for
> > .I gawk
> > extensions, listed alphabetically by short option.
> > .TP
> > .BI \-f " program-file\fR,\fP "\c
> > .BI \-\^\-file " program-file"
> > Read the AWK program source from the file
> > .IR program‐file ,
> This is a wrong use of '\c', as its purpose is to join the output of
> two macros _without_ an intervening space character.
>
>   So remove ' ' and '\c', changing
>
> .BI \-f " program-file\fR,\fP "\c
>
>   to
>
> .BI \-f " program-file\fR,\fP"

This is bad advice in a couple of respects.  Because you have only two
(space-separated) words before a break, there's no need for \c at all.

I would document the option as follows.

.TP
.BI \-f " program-file"
.TQ
.BI \-\-file " program-file"
Read the AWK program source from the file
.I program-file,

I made some other changes while I was at it.[2]

The other problem is that Bjarni's advice introduced a bunch of
superfluous italic correction escape sequences.  There is absolutely no
reason to do this when (1) you're abutting italic text with _space_ and
(2) you're using groff man(7)'s font alternation macros, which take care
of italic corrections _for_ you, as they are documented to do.

Quoting groff_man_style(7) again:

    Unlike the above font style macros, the font style alternation
    macros below set no input traps; they must be given arguments to
    have effect.  Italic corrections are applied as appropriate.  If a
    space is required within an argument, first consider whether the
    same result could be achieved with as much clarity by using single-
    style macros on separate input lines.  When it cannot, double-quote
    an argument containing embedded space characters.  Setting all three
    different styles within a word presents challenges; it is possible
    with the \c and/or \f escape sequences.  See subsection
    "Portability" below for approaches.

I'm attaching an abbreviated demonstration of my changes.  I tested it
with groff Git HEAD, groff 1.22.4, DWB 3.3 nroff, and Heirloom Doctools
nroff.

Bjarni, please do not offer yourself as an authority on correct man page
composition when you don't know what you're talking about and have filed
bug reports complaining of that fact.

https://savannah.gnu.org/bugs/?64238

Regards,
Branden

[1] https://mail.gnu.org/archive/html/groff/2023-04/msg00135.html

[2] I used groff man(7)'s permissively licensed `TQ` extension,[3] took
    out the hair space escape sequence, and switched from `IR` to `I`
    when setting a metasyntactic variable in running text with adjacent
    punctuation because it looks better when typeset.  But all of these
    are matters of taste, not correctness.

[3] The gawk(1) page author works around it by doing the `PD 0` push-pop
    trick with another `TP` call.  This is perfectly portable as far as
    I know, if mystifying to the novice man(7) author.  I find `TQ`
    cleaner.  I feel that `PD` tricks will be made unnecessary with some
    semantic/structural tagging reforms to man(7) I have in mind.

    https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html
    https://lists.gnu.org/archive/html/groff/2022-12/msg00078.html

    But those will have to wait for groff 1.24...

signature.asc
Description: PGP signature