Hi, clematis wrote on Fri, May 01, 2020 at 11:37:51AM +0200: > On Fri, May 01, 2020 at 06:52:27AM +0100, Jason McIntyre wrote:
>> i don;t understand your reference to 28 out of 41 files. i cannot see >> where we added any expanded FILES entries. can you provide a summary of >> these inconsistencies, please? > There's 41 example files in /etc/examples/. 28 of them are listed in the > FILES section of their respective manpage with a short description. > The patches I've sent were to do the same for the remaining 13 files. > Either adding them when there were missing and/or adding the short > description. I think there is value in having complete FILES sections, listing all the files (with full paths if possible) directly related to the topic of a manual page because it both allows to see at first glance with files are used by the command and where exactly they located (as a non-trivial example, consider /etc/mail/smtpd.conf), because it potentially support "apropos Pa=" searches, and because it costs almost nothing: exactly one line per file when it's obvious what the file is all about. Whether the file needs an explanation of more than one line should be decided on a case by case basis. Very often, it does not. In conclusion, i do support adding the missing FILES sections dhcpd.conf(5) and httpd.conf(5). I don't care about changes like these either way: .It Pa /etc/man.conf +Default +.Xr man 1 +configuration file. .It Pa /etc/examples/man.conf +Example configuration file. I think both contain exactly the same information. If jmc@ thinks either having or not having the trivial one-line explanation is better for some reason, or that there is value in doing this aspect consistently, i'm happy to have this made consistent. If jmc@ thinks both forms are equally legitimate and there is no value in consistency in this respect, that's fine with me, too. There is certainly ample historical precedent for both forms. I don't really like this particular change: .It Pa /etc/examples/man.conf +Example configuration file illustrating possible search path ordering and +output options. The paramount design goal of the new man.conf(5) file format was to keep it as simple as possible and i think that goal was reached: there are now exactly two directives, both with an extremely simple syntax, and the complete formatted manual page fits into 80 lines. I consider it detrimental to restate what the file is for in the FILES section because it is obvious and already concisely said right above, so it just adds gratuitious verbiage. Explanations longer than one line should be reserved for special, non-trivial cases where they really matter. Such cases do occasionally exist, in particular when a config file format is exceptionally complicated, the file can do many different things, among them quite unusual ones, it is not obvious which aspects are those that it is most commonly used for, and/or the examples file deliberately focusses on a specific aspect for specific reasons and it is non-trivial which aspect that is or why. I think Jason should just go ahead with whatever parts of the diff he likes and discard the rest. He is usually very good at deciding issues of style and consistency. Yours, Ingo
