mandoc: -Tlint: spurious warning about empty IP macro

[Alejandro Colomar]

[groff@ CCd since they may help]

Hi Ingo,

I had been ignoring the mandoc linter that I added to the Linux man-pages 
because it had a lot of spurious warnings, but I finally managed to do something 
with which I'm happy:


$(_LINT_man_mandoc): $(_LINTDIR)/%.lint-man.mandoc.touch: $(MANDIR)/% | $$(@D)/.
        $(info LINT (mandoc)    $@)
        ! ($(MANDOC) $(MANDOCFLAGS) $< 2>&1 \
           | $(GREP) -v 'WARNING: cannot parse date, using it verbatim: TH 
(date)' \
           | $(GREP) -v 'STYLE: lower case character in document title:' \
           | $(GREP) -v 'WARNING: empty block: UR' \
           | $(GREP) -v 'UNSUPP: ignoring macro in table:' \
           ||:; \
        ) \
        | $(GREP) '.' >&2
        touch $@


Now I ignore the warnings that you didn't let me ignore :)
It makes sense, not that I came up with this small script around mandoc(1).  It 
is certainly much safer and simpler than asking you to design an internal system 
for turning them off.

After being able to silence those spurious warnings (and a few more that I'm 
finding), I've been running mandoc seriously as a linter in the Linux an-pages 
repo, and found one that seems non-legit to me:


$ make lint-man-mandoc V=1
LINT (mandoc)   tmp/lint/man2/mount_setattr.2.lint-man.mandoc.touch
! (mandoc -man -Tlint  man2/mount_setattr.2 2>&1 \
   | grep -v 'WARNING: cannot parse date, using it verbatim: TH (date)' \
   | grep -v 'STYLE: lower case character in document title:' \
   | grep -v 'WARNING: empty block: UR' \
   | grep -v 'UNSUPP: ignoring macro in table:' \
   ||:; \
) \
| grep '.' >&2
mandoc: man2/mount_setattr.2:644:2: WARNING: skipping paragraph macro: IP empty


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

Cheers,

Alex


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

OpenPGP_signature
Description: OpenPGP digital signature