Hi Jan, Jan Stary wrote on Wed, Nov 08, 2017 at 04:13:19PM +0100:
> this is a minimalized manpage that currently fails mandoc -Tlint: > > .Dd November 8, 2017 > .Dt AUDIO 3 > .Os > .Sh NAME > .Nm libaudio This is broken, .Dt/.Nm mismatch. Mandoc should probably warn, but doesn't. > .Nd manipulate digital audio formats and files > .Sh SYNOPSIS > .In audio.h > .Ft AUFILE* Missing blank, same problem reappears twice below. > .Fn au_open "const char* path" "AUMODE mode" "AUINFO* info" > .Ft int > .Fn au_close "AUFILE* file" > .Sh DESCRIPTION > .Nm > provides a simple uniform interface to manipulating > digital audio data in various formats and file types. > .Sh RETURN VALUES > .Fn au_open > returns a pointer to an initialized > .Ft AUFILE That ought to be .Vt. > structure, or NULL Missing .Dv. > if an error occurs. > .Fn au_close > returns 0 upon successfully closing the file, > or -1 if an error occurs. > > $ mandoc -Tlint /tmp/libaudio.3 > mandoc: /tmp/libaudio.3:1:5: STYLE: Mdocdate missing: Dd November (OpenBSD) > mandoc: /tmp/libaudio.3: STYLE: RCS id missing: (OpenBSD) > > I remember this was not the case. True, this feature is newish. > Is it considered bad style if > a manpage does not have "$Mdocdate: ... $" and a RCS id such as > .\" $OpenBSD: ls.1,v 1.79 2016/10/24 13:46:58 schwarze Exp $ ? No. Try $ mandoc -Tlint -Wstyle tmp.1 and you will see that it does not raise a STYLE message. > I tried looking for this -Tlint change in cvsweb but could not find it. RTFS is good, but RTFM first: https://man.openbsd.org/mandoc.1#base > This particular manpage is stored in git repo and does not have a RCS id. > In fact, it uses none of the $...$ constructs of CVS. For checking manual pages of portable software, mandoc -Tlint -Wstyle is recommended, and mandoc -Tlint -Wbase is excessive. > Is this enforced for base manpages, Exactly. > so that the OpenBSD mandoc requires it, while the portable mandoc > does not require it? No. OpenBSD and portable mandoc do not differ in functionality - oh well, with very few exceptions, for example portable mandoc honours .Lb while OpenBSD partially ignores it. Both do checking based on the -W and -Ios= arguments, and -Ios= defaults to what uname(3) returns. If you test on a different operating system, or if you run the OpenBSD version but test *for* a different system, you will see results that differ in just these tiny details: schwarze@isnote $ uname -a OpenBSD isnote.usta.de 6.2 GENERIC.MP#123 amd64 schwarze@isnote $ mandoc -Tlint tmp.1; echo $? mandoc: tmp.1:1:5: STYLE: Mdocdate missing: Dd November (OpenBSD) mandoc: tmp.1: STYLE: RCS id missing: (OpenBSD) 1 schwarze@isnote $ mandoc -Tlint -I os=Linux tmp.1; echo $? 0 schwarze@isnote $ mandoc -Tlint -Wnetbsd tmp.1; echo $? mandoc: tmp.1: STYLE: RCS id missing: (NetBSD) 1 > I don't find it bad style in general to not have a RCS id ... Everybody i talked to agrees with that, and so do i. But when i originally made the message mandoc: tmp.1:1:5: BASE: Mdocdate missing: Dd November (OpenBSD) people rightfully complained that BASE is not only hard to understand but also sounds much too scary, much too serious, as if something were fundamentally broken. So we agreed to print "STYLE:" in the message. Yours, Ingo
