Re: man: EX/EE nested within nf/fi

[G. Branden Robinson]

Hi Alex,

At 2024-06-10T21:24:54+0200, Alejandro Colomar wrote:
> Hi Branden,
> 
> Is it correct to nest EX/EE within nf/fi?

It's harmless.  "Correct" is a question of taste and attempts at
portability to legacy systems.

>       $ cat nfi.man 
>       .TH EXE 7 2024-06-10 alx
>       .SH Name
>       nf \- EX
>       .SH SYNOPSIS
>       .nf
>       .B #include <foo.h>
>       .P
>       .EX

I find myself wondering why you're postponing the change of typeface to
Courier on typesetters here.

>       struct {
>               int a;
>               int b;
>       };
>       .EE

...and leaving it early.

>       .P
>       .B #include <bar.h>
>       .P
>       .B #define BAR \[dq]bar\[dq]
>       .fi

I think the foregoing would be off-putting with family changes in it.
I've also never seen this idiom of setting the preprocessor directives
in roman used anywhere else in man pages.

I'd structure what you have like this:

.nf
.EX
...
.EE
.fi

> Or should I terminate the nf/fi block before entering EX/EE?  I ask
> because mandoc(1) is bugging me.  groff(1) seems to do the right thing
> --mandoc(1) also seems to do the right thing; it just complains--.

I'll let Ingo speak to that.

I've advised the ncurses project to use both `nf`+`EX` and `fi`+`EE` to
accommodate systems that don't implement the Ninth Edition Unix/groff
`EX`/`EE` extension to man(7).  By doing it, the example will format
comprehensibly even if it remains in the Times font on typesetters.

Another approach would be to define a page-local copy of `EX` and `EE`,
but not everyone finds that solution sanguine.

In the Linux man-pages project, I would not bother with this doubling up
at all.  In practical scenarios, everything that renders a Linux man
page is going to support `EX` and `EE`.[1]  Even Solaris 11 can handle
these macros.

Regards,
Branden

[1] groff_man(7):

     .EX
     .EE    Begin and end example.  After .EX, filling is disabled and a
            constant‐width (monospaced) font is selected.  Calling .EE
            enables filling and restores the previous font.

            .EX and .EE are extensions introduced in Ninth Edition Unix.
            Documenter’s Workbench, Heirloom Doctools, and Plan 9
            troffs, and mandoc (since 1.12.2) also support them.
            Solaris troff does not.  See subsection “Use of extensions”
            in groff_man_style(7).

[I do not contradict myself.  Solaris troff is Solaris's own derivation
of AT&T troff.  It remains in deployment on Solaris 10.  Solaris 11 uses
GNU troff (albeit a _really old_ version, which nevertheless supports
`EX` and `EE` man(7) macros).]

signature.asc
Description: PGP signature