Re: mandoc: -Tlint: spurious warning about empty IP macro

[Alejandro Colomar]

On 11/10/22 09:56, G. Branden Robinson wrote:
> At 2022-11-10T00:31:27+0100, Alejandro Colomar wrote:
> > mandoc: man2/mount_setattr.2:644:2: WARNING: skipping paragraph macro:
> > IP empty
>
> I suspect this warning did not anticipate that a paragraphing macro
> might be used solely for its spacing function, which is not redundant
> with an adjacent paragraphing macro if (1) the amount of inter-pargraph
> space has been changed (`PD`) or (2) the relative inset distance has
> been changes (`RS`, `RE`).  In your exhibit (below), you do both.

Heh!

And don't forget that a bulleting IP is preceeding.

> > Unless I'm very confused, that macro is necessary there.  First let's
> > see that part of the rendered page (using groff 1.23.0):
> >
> >         •  The   underlying  filesystem  must  support  ID‐mapped
> >            mounts.  Currently, the following filesystems  support
> >            ID‐mapped mounts:
> >
> >            •  xfs(5) (since Linux 5.12)
> >            •  ext4(5) (since Linux 5.12)
> >            •  FAT (since Linux 5.12)
> >            [...]
> >
> > That code is from when I made lists consistent, a few weeks ago.  The
> > code is:
> >
> > .IP \(bu
> > The underlying filesystem must support ID-mapped mounts.
> > Currently, the following filesystems support ID-mapped mounts:
> > .\" fs_flags = FS_ALLOW_IDMAP in kernel sources
> > .IP
> > .RS
> > .PD 0
> > .IP \(bu 3
> > .BR xfs (5)
> > (since Linux 5.12)
> > .IP \(bu
> > .BR ext4 (5)
> > (since Linux 5.12)
> > .IP \(bu
> > .B FAT
> > (since Linux 5.12)
> >
> > If I remove that .IP, the blank line between the inner list and the
> > outer list vanishes.
>
> Yes.  Almost any paragraphing macro would do the same here.  Have you
> tried simply 'P'?  Maybe mandoc(1) recognizes that as idiomatic for its
> spacing function.

Not really.  .P (or .PP, which I did try) would break the formatting.  Let's 
show a bit mre of the current page:

       •  The underlying filesystem must support ID‐mapped mounts.  Currently,
          the following filesystems support ID‐mapped mounts:

          •  xfs(5) (since Linux 5.12)
          •  ext4(5) (since Linux 5.12)
          •  FAT (since Linux 5.12)
          •  btrfs(5) (since Linux 5.15)
          •  ntfs3 (since Linux 5.15)
          •  f2fs (since Linux 5.18)
          •  erofs (since Linux 5.19)
          •  overlayfs (ID‐mapped lower and upper layers supported since Linux
             5.19)

       •  The mount must not already be ID‐mapped.  This also implies that the
          ID mapping of a mount cannot be altered.

And this is what happens with PP:

       •  The underlying filesystem must support ID‐mapped mounts.  Currently,
          the following filesystems support ID‐mapped mounts:

              •  xfs(5) (since Linux 5.12)
              •  ext4(5) (since Linux 5.12)
              •  FAT (since Linux 5.12)
              •  btrfs(5) (since Linux 5.15)
              •  ntfs3 (since Linux 5.15)
              •  f2fs (since Linux 5.18)
              •  erofs (since Linux 5.19)
              •  overlayfs  (ID‐mapped  lower and upper layers supported since
                 Linux 5.19)

       •  The mount must not already be ID‐mapped.  This also implies that the
          ID mapping of a mount cannot be altered.

So IP is necessary to let man(7) know that all what follows is still part of the 
bulleted item in the list.  Otherwise, I need to specify the indentation in RS, 
which I don't want.

> In the event you end up needing to retreat to raw roff for this, I would
> replace the "empty" `IP` call with a simple `sp` request.

This is for lists, which is a very common thing in the pages.  I don't want them 
to be filled with 'sp' requests, and even less contributors to have to think 
about it :)

> > Not that I think, let's try mandoc(1):
> >
> >         •  The underlying filesystem must support ID-mapped mounts.
> >            Currently, the following filesystems support ID-mapped
> >            mounts:
> >            •  xfs(5) (since Linux 5.12)
> >            •  ext4(5) (since Linux 5.12)
> >            •  FAT (since Linux 5.12)
> >
> > Hmm, the warning seems legit for mandoc(1): it's actually ignoring it.
> > But that seems like a bug in mandoc(1) to me.
>
> Indeed, I am not sure I agree with mandoc(1)'s rendering of this input.
>
> In groff man(7), we could solve this gracefully--that is, without
> messing with `PD`--with new list management macros `LS` and `LE`; it

Yep, I'm waiting for them.  They'll be for after 1.23.0, I guess, right?  It's 
definitely not in groff from git HEAD.

> composes in obvious ways with paragraphing macros before and after, and
> with relative insets.  This is cleaner, in my opinion, than mdoc(7)'s
> '-compact' and '-offset' options to its `Bl` macro.  This has come up
> before[1].  Maybe I'll take another run at the icy wall of conservatism
> that greets all such things after groff 1.23 is finalized.
Yeah, makes sense.  A month or so before releasing is not the best moment to add 
new features.

> Regards,
> Branden
>
> [1] https://lists.gnu.org/archive/html/groff/2022-05/msg00025.html

;)

Cheers,

Alex

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

OpenPGP_signature
Description: OpenPGP digital signature