Hi Jason, Jason McIntyre wrote on Sun, Feb 09, 2020 at 07:49:10AM +0000:
> - bgpd.8 refers to /etc/bgpd.conf. that file doesn;t exist by default. I do not consider that a problem, not even a minor one. ENVIRONMENT says which variables are inspected if they exist. FILES says which files are used if they exists. If they don't, well, then they are not used. I don't see anything that needs to be explained in that respect. > - i'm not convinced bgpd.8 needs to refer to the example file. Fair enough, deleted from my tree. So we will usually point to the examples from the file format manuals, but not from the program manuals, unless there are special considerations for a specific program. > - only root can view the example file. i understand why, but in itself > it's not that helpful. I don't see a reasonable way to improve that. Besides, only root can configure the daemon, so it's not a very serious obstacle in practice. > - we've seen from this thread that people are missing the existence of > /etc/examples/bgpd.conf. that's a shame because it looks like a nicely > written file. > > the essential issue is we want people to find the examples. the least > amount of work to achieve that is just for bgpd.conf.5 to mention it. > adding extra stuff about what's in there is a lot of work and sets us up > for things going out of date in the future. and although it might work > well for bgpd - a big, complex, piece of software, it will probably make > less sense for most other software. leaving us with a divided strategy. > > it'd be good to have a clear idea of which pages we're planning to > change, and how, so that it's clear for other authors. > > for bgpd i propose: > > - no change to bgpd.8. i don;t have a solution to the fact that we moved > its config file to examples/ so there isn;t an /etc/bgpd.conf file. i > suppose everyone understands what is happening. > - for bgpd.conf.5, add an entry to FILES "example configuration file". > no more. For now, that's what i did, even though i like deraadt@'s idea, but we lack consensus, so i applied the minimum change that everybody agreed with. Whether to add additional information as part of a strategy to do this in several cases where it makes sense (but of course not everywhere), or merely in this individual case as an exception, or not at all - that can be decided separately. Theo has brought forward some very substantial arguments in favour, but i didn't want to summarily dismiss Jason's reservations that it increases the risk of information getting out of sync, either. > - i'm not the right person to judge the existence of individual example > files. ratchov already indicated he doesn;t see the point of > examples/mixerctl.conf. i guess individual devs get to judge this. That wouldn't result in a consistent user experience. For example, am i supposed to delete /etc/examples/man.conf because i don't like it? I'll refrain from that because deraadt@, espie@, and others made it clear that they value the concept in general. > - i think an addition to afterboot.8 totally makes sense. it's what it's > there for. I assume espie@ will commit that. > - i don;t think an addition to help.1 makes sense. that is just trying > to tell people how to use unix, and no one reads it anyway. Fair enough, i'll leave it alone. Yours, Ingo
