"Chatty" config files in /etc

[Garance A Drosehn]

[perhaps this should be continued on freebsd-arch?]

At 1:27 PM +0200 8/30/06, Dag-Erling Smørgrav wrote:
>Ruslan Ermilov <ru at FreeBSD.org> writes:
>>    Modified files:
>>      etc                  hosts.allow
>>    Log:
>  >   Comment out lines that use example addresses and example.com
>  >   names so that local changes can be made more easily (without
>  >   having to comment these lines, and making the diff more
>  >   readable).
>
>That reminds me - /etc/hosts is another file that mergemaster often
>trips over.  The comments and examples it contains should be moved
>to the appropriate man page(s) if they aren't there already.  In
>fact, we should probably remove the file from the tree, and just
>have sysinstall create one at install time.

I'm sure Ruslan didn't mean to open up this whole can of worms,
but I also find files like /etc/hosts, /etc/hosts.allow, and
/etc/pf.conf to be annoying when it comes to system upgrades.
They're meant to be helpful, but they're so chatty with comments,
and they are files that I *always* have to localize with my own
changes.  It is annoying when it seems like one of these files
pop up in mergemaster every single time I upgrade, and it's
almost always due to a change in some line that does not actually
effect anything.  I mean, I can understand it's useful to correct
comments in the file, but my already-running system is not going
to run any differently with the correct comment than the incorrect
comment.

I do think those comments and examples are useful, but it might be
better to move those lines into separate files.  We could move them
into man pages, but then they won't be available on systems which
have NO_MAN set.  I also think that for these files, there is some
advantage in having the info as plain-text files, and not all
spruced up with nroff commands.  I wonder if it would be better to
have the comments and examples as files under /etc/defaults.  I
suppose they could also go under /usr/share/examples, but for these
files I think there is some advantage that the comments and examples
be on '/', and not on '/usr'.

Also, if the comment+example files are under /etc/defaults, then
changes to them *will* come up in mergemaster.  It's just that
now they will show up in a file that has no local changes, so
the user can just read the change, instead of having to "merge"
all their local changes with the new official version.

-- 
Garance Alistair Drosehn     =               drosehn at rpi.edu
Senior Systems Programmer               or   gad at FreeBSD.org
Rensselaer Polytechnic Institute;             Troy, NY;  USA