Re: [PATCH 4/9] man/clear.1: Migrate macro usage conventions.

[G. Branden Robinson]

[looping in mandoc(1) maintainer Ingo Schwarze]

At 2023-09-30T16:47:32-0400, Thomas Dickey wrote:
> On Mon, Sep 25, 2023 at 03:00:39PM -0500, G. Branden Robinson wrote:
> > * Drop page-local `NS` and `NE` macro definitions in favor of more
> >   widely used `EX` and `EE` macros.
> > 
> >   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.
> > 
> >               These macros are extensions introduced in Ninth Edition
> >               Unix.  Systems running that troff, or those from
> >               Documenter’s Workbench, Heirloom Doctools, or Plan 9 troff
> >               support them.  To be certain your page will be portable to
> >               systems that do not, copy their definitions from the
> >               an-ext.tmac file of a groff installation.
> > 
> >   Also use `PP` and `IP` to achieve the vertical separation formerly
> >   implied by `NS`, and `RS`/`RE` to manage horizontal position performed
> >   by `NS` and `NE`.
> > 
> > * Drop page-local `bP` macro in favor of ".IP \(bu 4" on the first
> >   occurrence, and ".IP \(bu" on subsequent ones.
> 
> actually I prefer the macro (makes it easier to check)

To check what?  There's no _harm_ in saying ".IP \bu 4" (or however much
indentation you want) without variation.  And it's more portable than
expecting a non-roff formatter to handle a macro definition, as we
unfortunately see below.

> > index bd561d88..5fc54a15 100644
> > --- a/man/clear.1
> > +++ b/man/clear.1
> > @@ -34,22 +34,36 @@
> >  .ie \n(.g .ds CW CR
> >  .el       .ds CW CW
> >  .\}
> > -.\" these would be fallbacks for DS/DE,
> > -.\" but groff changed the meaning of the macros.
> > -.de NS
> > -.ie n  .sp
> > -.el    .sp .5
> > -.ie n  .in +4
> > -.el    .in +2
> > -.nf
> > -.ft \*(CW
> > +.
> > +.nr mE 0 \" in an example (EX/EE)?
> > +.
> > +.\" Start example.
> > +.if !\n(.g \{\
> > +.de EX
> > +.  br
> > +.  if !\\n(mE \{\
> > +.    nr mF \\n(.f
> > +.    nr mP \\n(PD
> > +.    nr PD 1v
> > +.    nf
> > +.    ft \\*(CW
> > +.    nr mE 1
> > +.  \}
> >  ..
> > -.de NE
> > -.fi
> > -.ft R
> > -.ie n  .in -4
> > -.el    .in -2
> > +.\}
> > +.
> > +.\" End example.
> > +.if !\n(.g \{\
> > +.de EE
> > +.  br
> > +.  if \\n(mE \{\
> > +.    ft \\n(mF
> > +.    nr PD \\n(mP
> > +.    fi
> > +.    nr mE 0
> > +.  \}
> >  ..
> > +.\}
> 
> mandoc doesn't like this 
> 
> man/clear.1:52:2: ERROR: skipping end of block that is not open: ..
> man/clear.1:53:2: ERROR: skipping unknown macro: .\}
> man/clear.1:65:2: ERROR: skipping end of block that is not open: ..

Argh.  I didn't test with mandoc, and I guess I should have.  It's just
refusing to accept valid *roff syntax here.  I wonder if I can talk Ingo
into supporting it.

How about it, Ingo?  Will you support people defining macros inside
conditional block brace scopes?  ;-)

Regards,
Branden

signature.asc
Description: PGP signature