On Wed, Jan 06, 2016 at 04:41:13PM +0300, Vadim Zhukov wrote: > 2016-01-01 2:39 GMT+03:00 Amit Kulkarni <amitk...@gmail.com>: > > I just switched from sudo to doas and was stumped by this. > > > > The doas code expects doas.conf in /etc yet the manpage does not explicitly > > make that clear. I added a SYNOPSIS like in "man login.conf". > > While mdoc(7) says that section 5 manuals do not need SYNOPSIS usually, > we have 34 pages that do: > > lib/libedit/editrc.5 > lib/libkeynote/keynote.5 > libexec/getty/gettytab.5 > sbin/disklabel/disklabel.5 > sbin/mountd/exports.5 > share/man/man5/acct.5 > share/man/man5/ar.5 > share/man/man5/bsd.port.arch.mk.5 > share/man/man5/bsd.port.mk.5 > share/man/man5/bsd.regress.mk.5 > share/man/man5/changelist.5 > share/man/man5/core.5 > share/man/man5/defaultdomain.5 > share/man/man5/dir.5 > share/man/man5/disktab.5 > share/man/man5/elf.5 > share/man/man5/fs.5 > share/man/man5/fstab.5 > share/man/man5/login.conf.5 > share/man/man5/mk.conf.5 > share/man/man5/myname.5 > share/man/man5/netgroup.5 > share/man/man5/printcap.5 > share/man/man5/ranlib.5 > share/man/man5/spamd.conf.5 > share/man/man5/utmp.5 > share/termtypes/termcap.5 > usr.bin/doas/doas.conf.5 > usr.bin/ssh/ssh_config.5 > usr.bin/ssh/sshd_config.5 > usr.sbin/npppd/npppd/npppd-users.5 > usr.sbin/rpc.bootparamd/bootparams.5 > usr.sbin/smtpd/aliases.5 > usr.sbin/user/usermgmt.conf.5 > > Two of those contain some complicated stuff in SYNOPSIS: > > lib/libkeynote/keynote.5 > share/man/man5/bsd.port.arch.mk.5 > > I think this is okay, since this is the info you likely want to see, > except when opening manual page the first time. > > Then, many files do only mention .In or some equivalent in SYNOPSIS: > > sbin/disklabel/disklabel.5 > share/man/man5/acct.5 > share/man/man5/ar.5 > share/man/man5/bsd.port.mk.5 > share/man/man5/bsd.regress.mk.5 > share/man/man5/core.5 > share/man/man5/dir.5 > share/man/man5/disktab.5 > share/man/man5/elf.5 > share/man/man5/fs.5 > share/man/man5/fstab.5 > share/man/man5/mk.conf.5 > share/man/man5/ranlib.5 > share/man/man5/utmp.5 > > I'm not sure about those, but those are likely being useful. > > Then, we have following files showing their exact placement in SYNOPSIS: > > share/man/man5/bootparams.5 .Nm /etc/bootparams > share/man/man5/changelist.5 .Nm /etc/changelist > share/man/man5/defaultdomain.5 .Nm /etc/defaultdomain > share/man/man5/login.conf.5 .Nm /etc/login.conf > share/man/man5/mygate.5 .Nm /etc/myname > share/man/man5/myname.5 .Nm /etc/myname > share/man/man5/netgroup.5 .Nm /etc/netgroup > share/man/man5/spamd.conf.5 .Nm /etc/mail/spamd.conf > usr.bin/ssh/ssh_config.5 .Nm /etc/ssh/ssh_config > usr.bin/ssh/ssh_config.5 .Nm ~/.ssh/config > usr.bin/ssh/sshd_config.5 .Nm /etc/ssh/sshd_config > usr.sbin/npppd/npppd/npppd-users.5 .Nm /etc/npppd/npppd-users > > I'm not sure about these much more. I usually prefer looking at the > FILES section, but maybe this could be put in the first paragraph > of DESCRIPTION, or whatever. Any opinions? > > And some files contain totaly extraneous SYNOPSIS lines, either > just ".Nm", or ".Nm foo". Those are totally useless, and the patch > for those is below. Okay? > > -- > WBR, > Vadim Zhukov >
as you've found, nothing really fits well for files like these. i personally don;t mind SYNOPSIS being a bit scrappy, since a missing SYNOPSIS looks weird too. i don;t mind if you want to try and make things more consistent, but i don;t really want to get involved myself (as i said, i don;t really mind how they are now). jmc > > Index: lib/libedit/editrc.5 > =================================================================== > RCS file: /cvs/src/lib/libedit/editrc.5,v > retrieving revision 1.28 > diff -u -p -r1.28 editrc.5 > --- lib/libedit/editrc.5 15 Dec 2014 22:35:41 -0000 1.28 > +++ lib/libedit/editrc.5 6 Jan 2016 13:12:46 -0000 > @@ -33,8 +33,6 @@ > .Sh NAME > .Nm editrc > .Nd configuration file for editline library > -.Sh SYNOPSIS > -.Nm > .Sh DESCRIPTION > The > .Nm > Index: libexec/getty/gettytab.5 > =================================================================== > RCS file: /cvs/src/libexec/getty/gettytab.5,v > retrieving revision 1.26 > diff -u -p -r1.26 gettytab.5 > --- libexec/getty/gettytab.5 6 Nov 2015 16:42:30 -0000 1.26 > +++ libexec/getty/gettytab.5 6 Jan 2016 13:12:46 -0000 > @@ -34,8 +34,6 @@ > .Sh NAME > .Nm gettytab > .Nd terminal configuration database > -.Sh SYNOPSIS > -.Nm gettytab > .Sh DESCRIPTION > The > .Nm > Index: sbin/mountd/exports.5 > =================================================================== > RCS file: /cvs/src/sbin/mountd/exports.5,v > retrieving revision 1.22 > diff -u -p -r1.22 exports.5 > --- sbin/mountd/exports.5 15 Dec 2015 18:25:28 -0000 1.22 > +++ sbin/mountd/exports.5 6 Jan 2016 13:12:46 -0000 > @@ -36,8 +36,6 @@ > .Sh NAME > .Nm exports > .Nd define remote mount points for NFS mount requests > -.Sh SYNOPSIS > -.Nm exports > .Sh DESCRIPTION > The > .Nm > Index: share/man/man5/printcap.5 > =================================================================== > RCS file: /cvs/src/share/man/man5/printcap.5,v > retrieving revision 1.25 > diff -u -p -r1.25 printcap.5 > --- share/man/man5/printcap.5 17 Nov 2015 17:10:36 -0000 1.25 > +++ share/man/man5/printcap.5 6 Jan 2016 13:12:46 -0000 > @@ -36,8 +36,6 @@ > .Sh NAME > .Nm printcap > .Nd printer capability database > -.Sh SYNOPSIS > -.Nm printcap > .Sh DESCRIPTION > The > .Nm > Index: share/termtypes/termcap.5 > =================================================================== > RCS file: /cvs/src/share/termtypes/termcap.5,v > retrieving revision 1.28 > diff -u -p -r1.28 termcap.5 > --- share/termtypes/termcap.5 22 Jan 2014 19:37:47 -0000 1.28 > +++ share/termtypes/termcap.5 6 Jan 2016 13:12:46 -0000 > @@ -35,8 +35,6 @@ > .Sh NAME > .Nm termcap > .Nd terminal capability database > -.Sh SYNOPSIS > -.Nm termcap > .Sh DESCRIPTION > The > .Nm > Index: usr.sbin/smtpd/aliases.5 > =================================================================== > RCS file: /cvs/src/usr.sbin/smtpd/aliases.5,v > retrieving revision 1.11 > diff -u -p -r1.11 aliases.5 > --- usr.sbin/smtpd/aliases.5 28 Oct 2015 08:49:55 -0000 1.11 > +++ usr.sbin/smtpd/aliases.5 6 Jan 2016 13:12:46 -0000 > @@ -20,8 +20,6 @@ > .Sh NAME > .Nm aliases > .Nd aliases file for smtpd > -.Sh SYNOPSIS > -.Nm aliases > .Sh DESCRIPTION > This manual page describes the format of the > .Nm > Index: usr.sbin/user/usermgmt.conf.5 > =================================================================== > RCS file: /cvs/src/usr.sbin/user/usermgmt.conf.5,v > retrieving revision 1.11 > diff -u -p -r1.11 usermgmt.conf.5 > --- usr.sbin/user/usermgmt.conf.5 19 Sep 2010 21:59:23 -0000 1.11 > +++ usr.sbin/user/usermgmt.conf.5 6 Jan 2016 13:12:46 -0000 > @@ -36,8 +36,6 @@ > .Sh NAME > .Nm usermgmt.conf > .Nd user management tools configuration file > -.Sh SYNOPSIS > -.Nm usermgmt.conf > .Sh DESCRIPTION > The > .Nm usermgmt.conf >
