I noticed some section 5 file format man pages for a configuration file
have a SYNOPSIS, but most do not.
For example, /usr/src/share/man/man5/passwd.conf.5 has
.Sh SYNOPSIS
.Nm
Well it is in the basic template.
mdoc(7) says SYNOPSIS is mandatory and that .Nm is required for section
5. But also it says the SYNOPSIS describes typical usage for config(1)
kernel compilation declaration, #include header, function types and
arguments, variables types, or command line arguments.
Why considered mandatory. I think it is noise like in example above.
Can we change this rule? Can we remove it from some files like the
following?
exports
gettytab
login.conf
mixerctl.conf
passwd.conf
printcap
rc (has multiple parts)
usermgmt.conf
wscons.conf
(maybe others too, but not very many)
By the way, maybe the better way is like netconfig.5:
.Sh SYNOPSIS
.Pa /etc/netconfig
So if you prefer not removing from above, but use .Pa instead with
pathname, let me know.
But the majority don't have it. (I am not listing them out here now.)
Here is the example that made me notice today:
t1:arm$ man rndc.conf | head -13
man: Formatting manual page...
RNDC.CONF(5) BIND9 RNDC.CONF(5)
NAME
rndc.conf - rndc configuration file
SYNOPSIS
rndc.conf
DESCRIPTION
rndc.conf is the configuration file for rndc, the BIND 9 name server
