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

[Alejandro Colomar]

On Tue, Jun 11, 2024 at 07:52:30AM GMT, G. Branden Robinson wrote:
> Hi Alex,

Hi Branden,

> 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.

It's not roman; it's bold.  Did you mean proportional?  Michael liked
proportional typeface for everything in the synopsis, and so I'm
following his tradition.  I'm only using EX/EE for structures, for
alignment reasons.  The actual synopsis that I'm formatting is:

SYNOPSIS
     #include <linux/fs.h>  /* Definition of PAGE* and PM_* constants */
     #include <sys/ioctl.h>

     int ioctl(int pagemap_fd, PAGEMAP_SCAN, struct pm_scan_arg *arg);

     #include <linux/fs.h>

     struct pm_scan_arg {
         __u64  size;
         __u64  flags;
         __u64  start;
         __u64  end;
         __u64  walk_end;
         __u64  vec;
         __u64  vec_len;
         __u64  max_pages;
         __u64  category_inverted;
         __u64  category_mask;
         __u64  category_anyof_mask;
         __u64  return_mask;
     };

     struct page_region {
         __u64  start;
         __u64  end;
         __u64  categories;
     };

where only the structures would be EX/EE.

> 
> I'd structure what you have like this:
> 
> .nf
> .EX
> ...
> .EE
> .fi

In this case, nf/fi is actually redundant, no?  Isn't EX/EE a strict
superset of nf/fi?  I think of it as being nf/fi + monospace.

> > 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.

Ahh, now I understad your rationale: a fallback in case EX/EE doesn't
exist.  I'll keep using just EX/EE for meaning EX/EE, and not workaround
its lack.

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

Nah, but those interested in systems that lack it could maybe press
those systems to add a system-wide definition of those, which would be
cheaper and better.

> 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.

Yup.

> 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).]

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

signature.asc
Description: PGP signature