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