mandoc: -Tlint: search /usr/local/man as well

[Klemens Nanni-2]

It has always bothered me that linting manuals complained about missing
manuals from packages despite their path being part of the default
MANPATH:

No local man(1) config:

        $ echo $MANPATH
        ksh: MANPATH: parameter not set
        $ cat /etc/man.conf
        cat: /etc/man.conf: No such file or directory

man(1) finds tog(1), but mandoc(1) does not:

        $ mandoc -T lint `man -w tog` | grep 'not found'
        mandoc: /usr/local/man/man1/tog.1:35:6: STYLE: referenced manual not found: Xr git-repository 5 (2 times)
        mandoc: /usr/local/man/man1/tog.1:188:6: STYLE: referenced manual not found: Xr got 1 (6 times)

Not having those STYLE "issues" also makes `mandoc -T lint' more useful
for automatic regression/pre-commit/etc. checks in ports using it since
even STYLE messages result in a non-zero exit status, i.e. `make test'
for a totally fine manual would fail.

Using `-W warning' to omit STYLE message entirely is undesired because
it silences other useful style hints as well and parsing output to work
around all this is hackish at best.

So let's lint manuals with the default MANPATH instead of the limited
base one.

Feedback? Objections? OK?


Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.256
diff -u -p -r1.256 main.c
--- main.c 19 Feb 2021 19:49:49 -0000 1.256
+++ main.c 3 Apr 2021 00:29:56 -0000
@@ -962,7 +962,7 @@ check_xr(void)
  size_t sz;
 
  if (paths.sz == 0)
- manpath_base(&paths);
+ manpath_default(&paths);
 
  for (xr = mandoc_xr_get(); xr != NULL; xr = xr->next) {
  if (xr->line == -1)
Index: manconf.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/manconf.h,v
retrieving revision 1.9
diff -u -p -r1.9 manconf.h
--- manconf.h 21 Jul 2020 15:08:49 -0000 1.9
+++ manconf.h 3 Apr 2021 00:29:57 -0000
@@ -55,4 +55,4 @@ struct manconf {
 void manconf_parse(struct manconf *, const char *, char *, char *);
 int manconf_output(struct manoutput *, const char *, int);
 void manconf_free(struct manconf *);
-void manpath_base(struct manpaths *);
+void manpath_default(struct manpaths *);
Index: manpath.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/manpath.c,v
retrieving revision 1.30
diff -u -p -r1.30 manpath.c
--- manpath.c 27 Aug 2020 14:59:42 -0000 1.30
+++ manpath.c 3 Apr 2021 00:30:46 -0000
@@ -93,10 +93,9 @@ manconf_parse(struct manconf *conf, cons
 }
 
 void
-manpath_base(struct manpaths *dirs)
+manpath_default(struct manpaths *dirs)
 {
- char path_base[] = MANPATH_BASE;
- manpath_parseline(dirs, path_base, '\0');
+ manpath_parseline(dirs, MANPATH_DEFAULT, '\0');
 }
 
 /*

[Klemens Nanni-2]

On Sat, Apr 03, 2021 at 02:33:05AM +0200, Klemens Nanni wrote:

> It has always bothered me that linting manuals complained about missing
> manuals from packages despite their path being part of the default
> MANPATH:
>
> No local man(1) config:
>
> $ echo $MANPATH
> ksh: MANPATH: parameter not set
> $ cat /etc/man.conf
> cat: /etc/man.conf: No such file or directory
>
> man(1) finds tog(1), but mandoc(1) does not:
>
> $ mandoc -T lint `man -w tog` | grep 'not found'
> mandoc: /usr/local/man/man1/tog.1:35:6: STYLE: referenced manual not found: Xr git-repository 5 (2 times)
> mandoc: /usr/local/man/man1/tog.1:188:6: STYLE: referenced manual not found: Xr got 1 (6 times)
>
> Not having those STYLE "issues" also makes `mandoc -T lint' more useful
> for automatic regression/pre-commit/etc. checks in ports using it since
> even STYLE messages result in a non-zero exit status, i.e. `make test'
> for a totally fine manual would fail.
>
> Using `-W warning' to omit STYLE message entirely is undesired because
> it silences other useful style hints as well and parsing output to work
> around all this is hackish at best.
>
> So let's lint manuals with the default MANPATH instead of the limited
> base one.
>
> Feedback? Objections? OK?

That was the wrong diff (again), sorry.

Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.256
diff -u -p -r1.256 main.c
--- main.c 19 Feb 2021 19:49:49 -0000 1.256
+++ main.c 3 Apr 2021 00:29:56 -0000
@@ -962,7 +962,7 @@ check_xr(void)
  size_t sz;
 
  if (paths.sz == 0)
- manpath_base(&paths);
+ manpath_default(&paths);
 
  for (xr = mandoc_xr_get(); xr != NULL; xr = xr->next) {
  if (xr->line == -1)
Index: manconf.h
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/manconf.h,v
retrieving revision 1.9
diff -u -p -r1.9 manconf.h
--- manconf.h 21 Jul 2020 15:08:49 -0000 1.9
+++ manconf.h 3 Apr 2021 00:29:57 -0000
@@ -55,4 +55,4 @@ struct manconf {
 void manconf_parse(struct manconf *, const char *, char *, char *);
 int manconf_output(struct manoutput *, const char *, int);
 void manconf_free(struct manconf *);
-void manpath_base(struct manpaths *);
+void manpath_default(struct manpaths *);
Index: manpath.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/manpath.c,v
retrieving revision 1.30
diff -u -p -r1.30 manpath.c
--- manpath.c 27 Aug 2020 14:59:42 -0000 1.30
+++ manpath.c 3 Apr 2021 00:33:53 -0000
@@ -93,10 +93,10 @@ manconf_parse(struct manconf *conf, cons
 }
 
 void
-manpath_base(struct manpaths *dirs)
+manpath_default(struct manpaths *dirs)
 {
- char path_base[] = MANPATH_BASE;
- manpath_parseline(dirs, path_base, '\0');
+ char path_default[] = MANPATH_DEFAULT;
+ manpath_parseline(dirs, path_default, '\0');
 }
 
 /*

[Jason McIntyre-2]

On Sat, Apr 03, 2021 at 02:33:05AM +0200, Klemens Nanni wrote:

> It has always bothered me that linting manuals complained about missing
> manuals from packages despite their path being part of the default
> MANPATH:
>
> No local man(1) config:
>
> $ echo $MANPATH
> ksh: MANPATH: parameter not set
> $ cat /etc/man.conf
> cat: /etc/man.conf: No such file or directory
>
> man(1) finds tog(1), but mandoc(1) does not:
>
> $ mandoc -T lint `man -w tog` | grep 'not found'
> mandoc: /usr/local/man/man1/tog.1:35:6: STYLE: referenced manual not found: Xr git-repository 5 (2 times)
> mandoc: /usr/local/man/man1/tog.1:188:6: STYLE: referenced manual not found: Xr got 1 (6 times)
>
> Not having those STYLE "issues" also makes `mandoc -T lint' more useful
> for automatic regression/pre-commit/etc. checks in ports using it since
> even STYLE messages result in a non-zero exit status, i.e. `make test'
> for a totally fine manual would fail.
>
> Using `-W warning' to omit STYLE message entirely is undesired because
> it silences other useful style hints as well and parsing output to work
> around all this is hackish at best.
>
> So let's lint manuals with the default MANPATH instead of the limited
> base one.
>
> Feedback? Objections? OK?
>

i think we need to hear from ingo on this one. it was done deliberately,
but i cannot remember why.

jmc

>
> Index: main.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/main.c,v
> retrieving revision 1.256
> diff -u -p -r1.256 main.c
> --- main.c 19 Feb 2021 19:49:49 -0000 1.256
> +++ main.c 3 Apr 2021 00:29:56 -0000
> @@ -962,7 +962,7 @@ check_xr(void)
>   size_t sz;
>  
>   if (paths.sz == 0)
> - manpath_base(&paths);
> + manpath_default(&paths);
>  
>   for (xr = mandoc_xr_get(); xr != NULL; xr = xr->next) {
>   if (xr->line == -1)
> Index: manconf.h
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/manconf.h,v
> retrieving revision 1.9
> diff -u -p -r1.9 manconf.h
> --- manconf.h 21 Jul 2020 15:08:49 -0000 1.9
> +++ manconf.h 3 Apr 2021 00:29:57 -0000
> @@ -55,4 +55,4 @@ struct manconf {
>  void manconf_parse(struct manconf *, const char *, char *, char *);
>  int manconf_output(struct manoutput *, const char *, int);
>  void manconf_free(struct manconf *);
> -void manpath_base(struct manpaths *);
> +void manpath_default(struct manpaths *);
> Index: manpath.c
> ===================================================================
> RCS file: /cvs/src/usr.bin/mandoc/manpath.c,v
> retrieving revision 1.30
> diff -u -p -r1.30 manpath.c
> --- manpath.c 27 Aug 2020 14:59:42 -0000 1.30
> +++ manpath.c 3 Apr 2021 00:30:46 -0000
> @@ -93,10 +93,9 @@ manconf_parse(struct manconf *conf, cons
>  }
>  
>  void
> -manpath_base(struct manpaths *dirs)
> +manpath_default(struct manpaths *dirs)
>  {
> - char path_base[] = MANPATH_BASE;
> - manpath_parseline(dirs, path_base, '\0');
> + manpath_parseline(dirs, MANPATH_DEFAULT, '\0');
>  }
>  
>  /*
>

[Tim van der Molen-4]

Klemens Nanni (2021-04-03 02:33 +0200):

> It has always bothered me that linting manuals complained about missing
> manuals from packages despite their path being part of the default
> MANPATH:
>
> No local man(1) config:
>
> $ echo $MANPATH
> ksh: MANPATH: parameter not set
> $ cat /etc/man.conf
> cat: /etc/man.conf: No such file or directory
>
> man(1) finds tog(1), but mandoc(1) does not:
>
> $ mandoc -T lint `man -w tog` | grep 'not found'
> mandoc: /usr/local/man/man1/tog.1:35:6: STYLE: referenced manual not found: Xr git-repository 5 (2 times)
> mandoc: /usr/local/man/man1/tog.1:188:6: STYLE: referenced manual not found: Xr got 1 (6 times)
>
> Not having those STYLE "issues" also makes `mandoc -T lint' more useful
> for automatic regression/pre-commit/etc. checks in ports using it since
> even STYLE messages result in a non-zero exit status, i.e. `make test'
> for a totally fine manual would fail.
>
> Using `-W warning' to omit STYLE message entirely is undesired because
> it silences other useful style hints as well and parsing output to work
> around all this is hackish at best.
>
> So let's lint manuals with the default MANPATH instead of the limited
> base one.
>
> Feedback? Objections? OK?

Doesn't mandoc -Tlint -Wstyle do what you want?

-Wstyle also suppresses other warnings that aren't interesting for manuals not
part of OpenBSD:

$ mandoc -Tlint /usr/local/man/man1/stagit.1
mandoc: /usr/local/man/man1/stagit.1:1:5: STYLE: Mdocdate missing: Dd March 5, 2021 (OpenBSD)
mandoc: /usr/local/man/man1/stagit.1: STYLE: RCS id missing: (OpenBSD)
mandoc: /usr/local/man/man1/stagit.1:113:6: STYLE: referenced manual not found: Xr stagit-index 1
$ mandoc -Tlint -Wstyle /usr/local/man/man1/stagit.1
$ echo $?
0

[Klemens Nanni-2]

On Sun, Apr 04, 2021 at 03:42:03PM +0200, Tim van der Molen wrote:
> Doesn't mandoc -Tlint -Wstyle do what you want?
I don't think so.  Oddly enough, `-Wstyle' does not do what I would
expect:  it omits STYLE messages instead of printing them.  From mandoc

    -W level
            Specify the minimum message level to be reported on the standard
            error output and to affect the exit status.  The level can be
            base, style, warning, error, or unsupp. [...]

That reads like `-Wstyle' should include STYLE.
>
> -Wstyle also suppresses other warnings that aren't interesting for manuals not
> part of OpenBSD:
But it would also suppress legitimate messages, e.g. `.Xr' macros with
misspelled manuals in the base MANPATH:

$ echo .Xr true 1 | mandoc -mdoc -Tlint                  
mandoc: <stdin>: WARNING: missing date, using ""
mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
mandoc: <stdin>: WARNING: missing Os macro, using ""
mandoc: <stdin>:1:2: WARNING: content before first section header: Xr
$ echo .Xr tru 1 | mandoc -mdoc -Tlint
mandoc: <stdin>: WARNING: missing date, using ""
mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
mandoc: <stdin>: WARNING: missing Os macro, using ""
mandoc: <stdin>:1:2: WARNING: content before first section header: Xr
mandoc: <stdin>:1:6: STYLE: referenced manual not found: Xr tru 1
$ echo .Xr tru 1 | mandoc -mdoc -Tlint -Wstyle
mandoc: <stdin>: WARNING: missing date, using ""
mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
mandoc: <stdin>: WARNING: missing Os macro, using ""
mandoc: <stdin>:1:2: WARNING: content before first section header: Xr

>
> $ mandoc -Tlint /usr/local/man/man1/stagit.1
> mandoc: /usr/local/man/man1/stagit.1:1:5: STYLE: Mdocdate missing: Dd March 5, 2021 (OpenBSD)
> mandoc: /usr/local/man/man1/stagit.1: STYLE: RCS id missing: (OpenBSD)
> mandoc: /usr/local/man/man1/stagit.1:113:6: STYLE: referenced manual not found: Xr stagit-index 1
> $ mandoc -Tlint -Wstyle /usr/local/man/man1/stagit.1
> $ echo $?
> 0
>

[Tim van der Molen-4]

(Sorry, now with reply all.)

Tim van der Molen (2021-04-04 17:08 +0200):

> Klemens Nanni (2021-04-04 15:54 +0200):
> > On Sun, Apr 04, 2021 at 03:42:03PM +0200, Tim van der Molen wrote:
> > > Doesn't mandoc -Tlint -Wstyle do what you want?
> > I don't think so.  Oddly enough, `-Wstyle' does not do what I would
> > expect:  it omits STYLE messages instead of printing them.  From mandoc
> >
> >     -W level
> >             Specify the minimum message level to be reported on the standard
> >             error output and to affect the exit status.  The level can be
> >             base, style, warning, error, or unsupp. [...]
> >
> > That reads like `-Wstyle' should include STYLE.
>
> AFAIK, -Wstyle does include style messages, but it leaves out the
> OpenBSD-specific ones. For example:
>
> $ echo '.Dd April 4, 2021\n.Os' | mandoc -Tlint
> mandoc: <stdin>:1:5: STYLE: Mdocdate missing: Dd April 4, 2021 (OpenBSD)
> mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> mandoc: <stdin>: STYLE: RCS id missing: (OpenBSD)
> mandoc: <stdin>: WARNING: no document body
>
> $ echo '.Dd April 4, 2021\n.Os' | mandoc -Tlint -Wstyle
> mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> mandoc: <stdin>: WARNING: no document body
>
> > > -Wstyle also suppresses other warnings that aren't interesting for manuals not
> > > part of OpenBSD:
> > But it would also suppress legitimate messages, e.g. `.Xr' macros with
> > misspelled manuals in the base MANPATH:
>
> On the other hand, I imagine there are manuals in ports that refer to
> manuals that don't exist on OpenBSD. This would still give you the false
> positives you wanted to avoid. But of course that might be an acceptable
> tradeoff; I can't say a priori.
>
> > $ echo .Xr true 1 | mandoc -mdoc -Tlint                  
> > mandoc: <stdin>: WARNING: missing date, using ""
> > mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> > mandoc: <stdin>: WARNING: missing Os macro, using ""
> > mandoc: <stdin>:1:2: WARNING: content before first section header: Xr
> > $ echo .Xr tru 1 | mandoc -mdoc -Tlint
> > mandoc: <stdin>: WARNING: missing date, using ""
> > mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> > mandoc: <stdin>: WARNING: missing Os macro, using ""
> > mandoc: <stdin>:1:2: WARNING: content before first section header: Xr
> > mandoc: <stdin>:1:6: STYLE: referenced manual not found: Xr tru 1
> > $ echo .Xr tru 1 | mandoc -mdoc -Tlint -Wstyle
> > mandoc: <stdin>: WARNING: missing date, using ""
> > mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> > mandoc: <stdin>: WARNING: missing Os macro, using ""
> > mandoc: <stdin>:1:2: WARNING: content before first section header: Xr
> >
> > >
> > > $ mandoc -Tlint /usr/local/man/man1/stagit.1
> > > mandoc: /usr/local/man/man1/stagit.1:1:5: STYLE: Mdocdate missing: Dd March 5, 2021 (OpenBSD)
> > > mandoc: /usr/local/man/man1/stagit.1: STYLE: RCS id missing: (OpenBSD)
> > > mandoc: /usr/local/man/man1/stagit.1:113:6: STYLE: referenced manual not found: Xr stagit-index 1
> > > $ mandoc -Tlint -Wstyle /usr/local/man/man1/stagit.1
> > > $ echo $?
> > > 0
> > >

[Tim van der Molen-4]

Tim van der Molen (2021-04-04 17:12 +0200):

> Tim van der Molen (2021-04-04 17:08 +0200):
> > AFAIK, -Wstyle does include style messages, but it leaves out the
> > OpenBSD-specific ones. For example:
> >
> > $ echo '.Dd April 4, 2021\n.Os' | mandoc -Tlint
> > mandoc: <stdin>:1:5: STYLE: Mdocdate missing: Dd April 4, 2021 (OpenBSD)
> > mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> > mandoc: <stdin>: STYLE: RCS id missing: (OpenBSD)
> > mandoc: <stdin>: WARNING: no document body
> >
> > $ echo '.Dd April 4, 2021\n.Os' | mandoc -Tlint -Wstyle
> > mandoc: <stdin>: WARNING: missing manual title, using UNTITLED: EOF
> > mandoc: <stdin>: WARNING: no document body

Stupid example, sorry. I meant something like this:

$ echo '.Dd 2021-04-04\n.Os' | mandoc -Tlint | grep STYLE
mandoc: <stdin>:1:5: STYLE: legacy man(7) date format: Dd 2021-04-04
mandoc: <stdin>:1:5: STYLE: Mdocdate missing: Dd 2021-04-04 (OpenBSD)
mandoc: <stdin>: STYLE: RCS id missing: (OpenBSD)

$ echo '.Dd 2021-04-04\n.Os' | mandoc -Tlint -Wstyle | grep STYLE
mandoc: <stdin>:1:5: STYLE: legacy man(7) date format: Dd 2021-04-04

[Ingo Schwarze]

Hi,

Klemens Nanni wrote on Sun, Apr 04, 2021 at 03:54:43PM +0200:
> On Sun, Apr 04, 2021 at 03:42:03PM +0200, Tim van der Molen wrote:

>> Doesn't mandoc -Tlint -Wstyle do what you want?

> I don't think so.  Oddly enough, `-Wstyle' does not do what I would
> expect:  it omits STYLE messages instead of printing them.

It does not.  It only omits BASE messages, which is the lowest message
level and the only one below STYLE.  See  `man -O tag=base mandoc`
what the purpose of BASE is.

When i inplemented the BASE level, i first printed these messages
with a BASE tag.  But other developers complained that "BASE" is
unclear and confusing and requested that STYLE be printed instead.
For that reason, both levels print STYLE.  I don't like that, it
is also confusing, just in a different way.  But unless you come
up with a name better than "BASE" that other developers will not
complain about, i don't know how to improve it.

You can still visually distinguish STYLE and BASE messages since the
latter have an (OpenBSD) or (NetBSD) tag at the end:

   $ man -clT lint /co/NetBSD/src/usr.bin/true/true.1  
  man: /co/NetBSD/src/usr.bin/true/true.1:34:4: STYLE: duplicate RCS id:
    $NetBSD: true.1,v 1.7 2003/08/07 11:16:48 agc Exp $
  man: /co/NetBSD/src/usr.bin/true/true.1:36:5: STYLE: Mdocdate missing:
    Dd June 27, 1991 (OpenBSD)
  man: /co/NetBSD/src/usr.bin/true/true.1: STYLE: RCS id missing: (OpenBSD)

   $ man -cT lint -W netbsd true
  man: /usr/share/man/man1/true.1:35:5: STYLE: Mdocdate found:
    Dd $Mdocdate: September 29 2010 $ (NetBSD)
  man: /usr/share/man/man1/true.1: STYLE: RCS id missing: (NetBSD)


>> -Wstyle also suppresses other warnings that aren't interesting for
>> manuals not part of OpenBSD:

Indeed, that's exactly what it was designed for.

> But it would also suppress legitimate messages, e.g. `.Xr' macros with
> misspelled manuals in the base MANPATH:

Yes, so far, checking of .Xr targets is only done on the BASE level,
not on the STYLE level because i regarded the requirement that .Xr targets
exist as a requirement of the OpenBSD base system.  For portable software
outside the OpenBSD base system, in the past, i didn't think checking .Xr
targets would be helpful.  It appears you now found a use case for that.

Your patch is not OK as it stands because mandoc would no longer help
developers working on the base system to find .Xr links pointing
outside the base system, and we have a policy that we don't want those.

I guess the right thing to do is to leave "-W all" unchanged (including
looking in the base system only) but change "-W style" to also do the .Xr
target check, but along the user's manpath.

Yours,
  Ingo

[Klemens Nanni-2]

On Mon, Apr 05, 2021 at 06:47:58PM +0200, Ingo Schwarze wrote:

> Hi,
>
> Klemens Nanni wrote on Sun, Apr 04, 2021 at 03:54:43PM +0200:
> > On Sun, Apr 04, 2021 at 03:42:03PM +0200, Tim van der Molen wrote:
>
> >> Doesn't mandoc -Tlint -Wstyle do what you want?
>
> > I don't think so.  Oddly enough, `-Wstyle' does not do what I would
> > expect:  it omits STYLE messages instead of printing them.
>
> It does not.  It only omits BASE messages, which is the lowest message
> level and the only one below STYLE.  See  `man -O tag=base mandoc`
> what the purpose of BASE is.
>
> When i inplemented the BASE level, i first printed these messages
> with a BASE tag.  But other developers complained that "BASE" is
> unclear and confusing and requested that STYLE be printed instead.
> For that reason, both levels print STYLE.  I don't like that, it
> is also confusing, just in a different way.  But unless you come
> up with a name better than "BASE" that other developers will not
> complain about, i don't know how to improve it.
>
> You can still visually distinguish STYLE and BASE messages since the
> latter have an (OpenBSD) or (NetBSD) tag at the end:
>
>    $ man -clT lint /co/NetBSD/src/usr.bin/true/true.1  
>   man: /co/NetBSD/src/usr.bin/true/true.1:34:4: STYLE: duplicate RCS id:
>     $NetBSD: true.1,v 1.7 2003/08/07 11:16:48 agc Exp $
>   man: /co/NetBSD/src/usr.bin/true/true.1:36:5: STYLE: Mdocdate missing:
>     Dd June 27, 1991 (OpenBSD)
>   man: /co/NetBSD/src/usr.bin/true/true.1: STYLE: RCS id missing: (OpenBSD)
>
>    $ man -cT lint -W netbsd true
>   man: /usr/share/man/man1/true.1:35:5: STYLE: Mdocdate found:
>     Dd $Mdocdate: September 29 2010 $ (NetBSD)
>   man: /usr/share/man/man1/true.1: STYLE: RCS id missing: (NetBSD)
>
>
> >> -Wstyle also suppresses other warnings that aren't interesting for
> >> manuals not part of OpenBSD:
>
> Indeed, that's exactly what it was designed for.
>
> > But it would also suppress legitimate messages, e.g. `.Xr' macros with
> > misspelled manuals in the base MANPATH:
>
> Yes, so far, checking of .Xr targets is only done on the BASE level,
> not on the STYLE level because i regarded the requirement that .Xr targets
> exist as a requirement of the OpenBSD base system.  For portable software
> outside the OpenBSD base system, in the past, i didn't think checking .Xr
> targets would be helpful.  It appears you now found a use case for that.

A use case, but not really a requirement, at least not for people
developing portable software on OpenBSD -- that's where I'm coming from:
messages telling me installed manuals cannot be found are annoying.

But I guess that turns into a valid use case as soon as mandoc is used
on and for another system with different manual paths.

> Your patch is not OK as it stands because mandoc would no longer help
> developers working on the base system to find .Xr links pointing
> outside the base system, and we have a policy that we don't want those.
Agreed.

> I guess the right thing to do is to leave "-W all" unchanged (including
> looking in the base system only) but change "-W style" to also do the .Xr
> target check, but along the user's manpath.
That makes sense and the diff below enables check_xr() to pick the right
manual paths.

HOWEVER it currently won't print anything because when `-Wstyle' is used
mandoc_msg(MANDOCERR_XR_BAD, ...) in check_xr() won't print anything as
MANDOC_XR_BAD is lower than MANDOCERR_STYLE.

I played swapping those two levels in the `enum mandocerr' but that
won't quite work (e.g. mandoc_msg() printing the wrong message)...

Ingo, perhaps you have an idea on how to fix that?


Index: main.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/main.c,v
retrieving revision 1.256
diff -u -p -r1.256 main.c
--- main.c 19 Feb 2021 19:49:49 -0000 1.256
+++ main.c 5 Apr 2021 19:20:22 -0000
@@ -949,7 +949,7 @@ parse(struct mparse *mp, int fd, const c
  if (outconf->tag != NULL && outconf->tag_found == 0 &&
     tag_exists(outconf->tag))
  outconf->tag_found = 1;
- if (mandoc_msg_getmin() < MANDOCERR_STYLE)
+ if (mandoc_msg_getmin() <= MANDOCERR_STYLE)
  check_xr();
 }
 
@@ -957,12 +957,22 @@ static void
 check_xr(void)
 {
  static struct manpaths paths;
+ static struct manconf conf;
  struct mansearch search;
  struct mandoc_xr *xr;
  size_t sz;
 
- if (paths.sz == 0)
- manpath_base(&paths);
+ if (paths.sz == 0) {
+ if (mandoc_msg_getmin() == MANDOCERR_BASE)
+ manpath_base(&paths);
+ else {
+ manconf_parse(&conf, NULL, NULL, NULL);
+ if (conf.manpath.sz != 0)
+ paths = conf.manpath;
+ else
+ manpath_base(&paths);
+ }
+ }
 
  for (xr = mandoc_xr_get(); xr != NULL; xr = xr->next) {
  if (xr->line == -1)