11195 Lint old man pages for errors with mandoc

Review Request #1974 — Created June 6, 2019 and submitted June 14, 2019, 6:44 a.m.

Information
Owner:	mno-hime
Repository:	illumos-gate
Branch:	master
Bugs:	11195
Depends On:	~~1973~~
Blocks:	1975
Commit:	0f2a0aa...
Reviewers
Groups:	general
People:

Description

With updated mandoc 1.14.5 update (#11190) some old man pages have errors resulting in display problems unless fixed.

Better to lint them for errors in the build. So far only one old man page does does not pass this lint: https://illumos.org/rb/r/1973/.

Testing Done

Full illumos-gate rebuild passed.

Log is bigger by 8k lines (old man pages which were not previously checked) of this sort:

checking syseventadm.1m

For my 50 minutes build it may be 1-2 minutes longer due to the checking.

Issues

0
0
1
0
All Issues: 1

Description	From	Last Updated
Rather than running mandoc lint on the same files should we break this ino two different commands. The first which ...	rm	June 9, 2019, 10:05 a.m.

Ship it!

Ship It!

mno-hime June 9, 2019, 10:06 a.m.

Andy, the check is now reworked completely, if you could review this again. Thanks!

usr/src/man/Makefile.man (Diff revision 1)

Show all issues

Rather than running mandoc lint on the same files should we break this ino two different commands. The first which is operating on those where the egrep passes and then those that the egrep fails, rather than checking all of the new pages twice? I assume in this case that -Wwarning includes those from -Werror, but perhaps that's incorrect?

mno-hime June 8, 2019, 9:58 a.m.

Your assumption about -Wwarning being a super-set of -Werror is correct.

However, I wonder if really the linting command is run twice in some cases.

I don't know much about makefiles, so I assumed mechanics of &&/|| is the same as in shell.

In this example true and false simulate $(EGREP)'s match, or, respectively, non-match:

all: old new

old:
        echo Old manpage: lint with error; \
        true && \
        echo MANDOC -Tlint -Werror || \
        echo MANDOC -Tlint -Wwarning ;
        echo

new:
        echo New manpage: lint with warning; \
        false && \
        echo MANDOC -Tlint -Werror || \
        echo MANDOC -Tlint -Wwarning ;
        echo

I get following results:

$ make -s
Old manpage: lint with error
MANDOC -Tlint -Werror

New manpage: lint with warning
MANDOC -Tlint -Wwarning

If my mock-up is correct, no man page is linted twice. Am I right in this?

rm June 8, 2019, 3:13 p.m.

I think you're right and that I was misreading this. But I think that if we're already misreading it, we should probably use more parenthesis to make what we want more explicit or use an if statement to make the grouping clearer rather than assuming we'll get the same order of operations right.

mno-hime June 9, 2019, 10:07 a.m.

Fair enough, re-worked this with if-else clauses. Hopefully it's more readable now.

mno-hime June 9, 2019, 10:08 a.m.

Forgot to mention that I also retested it via illumos rebuild.