Re: Comments in configuration files

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Thu, 2006-01-05 at 11:25 -0600, Tommy Reynolds wrote:
> Uttered Rahul Sundaram <sundaram@xxxxxxxxxx>, 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/

Attachment: signature.asc
Description: This is a digitally signed message part

-- 

fedora-docs-list@xxxxxxxxxx
To unsubscribe: 
https://www.redhat.com/mailman/listinfo/fedora-docs-list

[Index of Archives]     [Fedora Users]     [Fedora Desktop]     [Red Hat 9]     [Yosemite News]     [KDE Users]

  Powered by Linux