mandoc -Tlint requires Mdocdate and RCS id

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

mandoc -Tlint requires Mdocdate and RCS id

Jan Stary
Hi Ingo,

this is a minimalized manpage that currently fails mandoc -Tlint:

.Dd November 8, 2017
.Dt AUDIO 3
.Os
.Sh NAME
.Nm libaudio
.Nd manipulate digital audio formats and files
.Sh SYNOPSIS
.In audio.h
.Ft AUFILE*
.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
structure, or NULL 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. 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 $ ?
I tried looking for this -Tlint change in cvsweb but could not find it.

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.

Is this enforced for base manpages, so that the OpenBSD mandoc requires it,
while the portable mandoc does not require it? I don't find it bad style
in general to not have a RCS id ...

        Jan


Reply | Threaded
Open this post in threaded view
|

Re: mandoc -Tlint requires Mdocdate and RCS id

Ingo Schwarze
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