2016-01-07 19:12 GMT+03:00 Ingo Schwarze <schwa...@usta.de>: > 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
