Comments in configuration files

Tommy Reynolds Tommy.Reynolds at MegaCoder.com
Thu Jan 5 17:25:53 UTC 2006


Uttered Rahul Sundaram <sundaram at redhat.com>, spake thus:

> It seems that several configuration files in Fedora does not include 
> helpful comments as necessary to guide users on where to look for 
> information or which formats to follow.

Under FCn, most configuration files have system-config-* tools, or
similar, to allow newbies to painlessly access these files.  A user
sufficiently advanced to attack the raw files had better have enough
savy to know the file formats, or at least where to find them.  If
someone doesn't know they can "man fstab", is that a person who 
_should_ be editing "/etc/fstab"?  Not on my machines, they won't.

OTOH, I do describe the crontab field order using an embedded
comment but any more, such as trying to explain valid entries, giving
examples and the like do not belong here.

Also, some tools rewrite config files and do not preserve comments.
Frustration ensues.

So my position is this: "no" to newbie comments in the files
themselves, but "yes" to a cut-n-paste header comment in the man(1)
page.

HTH.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060105/b3a019fd/attachment.sig>


More information about the fedora-docs-list mailing list