Re: Putting more consistency on SYNOPSIS in section 5
2016-01-07 19:12 GMT+03:00 Ingo Schwarze : > Hi Vadim, > > Vadim Zhukov wrote on Wed, Jan 06, 2016 at 04:41:13PM +0300: > >> While mdoc(7) says that section 5 manuals do not need SYNOPSIS usually, >> we have 34 pages that do: > [...] > >> 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. > > Agreed. Such cases could only be improved on a case-by-case basis, > and only if they need it. > >> 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. > > Agreed. I don't think these need to be changed, at least i can't > think of an improvement right now. > >> 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? > > I think these SYNOPSIS sections should be removed, making sure > the FILES sections are present, correct, and complete. FILES > should always be used when relevant. A section containing no > information whatsoever (like SYNOPSIS in these cases) is useless, > so it can be removed, improving conciseness. > >> 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? > > OK schwarze@. > > But please add FILES to gettytab(5) and printcap(5) when comitting. Ingo, thank you for responding! I've just comitted the "easy" part, and going to convert more SYNOPSIS to FILES, which you agreed upon, a bit later. I'll show the diff separately. -- WBR, Vadim Zhukov
Re: Putting more consistency on SYNOPSIS in section 5 (was: mention /etc/doas.conf instead of plain doas.conf)
On Wed, Jan 06, 2016 at 04:41:13PM +0300, Vadim Zhukov wrote: > 2016-01-01 2:39 GMT+03:00 Amit Kulkarni : > > 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 - 1.28 > +++ lib/libedit/editrc.5 6 Jan 2016 13:12:46 - > @@ -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 - 1.26 > +++ libexec/getty/gettytab.5 6 Jan 2016 13:12:46 - > @@ -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 - 1.22 > +++ sbin/mountd/exports.5 6 Jan 2016 13:12:46 - > @@ -36,8 +36,6 @@ > .Sh NAME > .N
Putting more consistency on SYNOPSIS in section 5 (was: mention /etc/doas.conf instead of plain doas.conf)
2016-01-01 2:39 GMT+03:00 Amit Kulkarni : > 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 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.515 Dec 2014 22:35:41 - 1.28 +++ lib/libedit/editrc.56 Jan 2016 13:12:46 - @@ -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.56 Nov 2015 16:42:30 - 1.26 +++ libexec/getty/gettytab.56 Jan 2016 13:12:46 - @@ -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 - 1.22 +++ sbin/mountd/exports.5 6 Jan 2016 13:12:46 - @@ -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 - 1.25 +++ share/man/man5/printcap.5 6 Jan 2016 13:12:46 - @@ -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
