Comments in configuration files

[Paul W. Frields]

On Thu, 2006-01-05 at 11:25 -0600, Tommy Reynolds wrote:
> 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.

I'm with you up to the last paragraph, and my only caveat there isthat I
don't like the idea of messing with canonical man pages, which are
duplicated so often across the net.  I think this need should be filled
by documents like the Administration Guide[1].  This seems like an issue
for that drafting process, IMHO.


[1]http://fedoraproject.org/wiki/Docs/Drafts/AdministrationGuide

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060105/1782c80e/attachment.sig>