NetBSD-Users archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

man pages for section 5 config files with useless SYNOPSIS



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



Home | Main Index | Thread Index | Old Index