Comments in configuration files

[Nicolas Mailhot]

Rahul Sundaram wrote:
> Stuart Ellis wrote:
> 
>> On Thu, 2006-01-05 at 18:47 +0530, Rahul Sundaram wrote:
>>  
>>
>>> Hi
>>>
>>> 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.  The crontab files could have 
>>> a initial commented line specifying the format or hosts file could 
>>> refer people to its man page for examples. Would the documentation 
>>> team be willing to file bug reports with comments/content as 
>>> appropriate?
>>>
>>> Do we need such guidelines as inclusion/release criteria?
>>>   
>>
>> I think that it would be a good policy for those configuration files
>> that are written by Red Hat or Fedora developers
>> (e.g. /etc/sysconfig/*, /etc/httpd/conf.d/*), even if it's just a bit of
>> boilerplate text that identifies the file as a custom item and provides
>> a reference for more information.
>>
>> Where configuration files are supplied by upstream as part of the
>> software, it may be that tweaking them would be felt to be against the
>> general use-upstream-defaults policy. That's probably something that
>> would need discussion on development or maintainer lists to work out.
>>  
>>
> (CCing fedora-devel list)
> Might patch these as appropriate and send these upstream as required if 
> agreed upon as a general policy.

+1

a textbook case is /etc/cpuspeed.conf

The shipped conf file is the only "documentation" of the package. The 
various options are not documented anywhere else. And the comments in 
the conf file itself are somehow lacking

Regards,

-- 
Nicolas Mailhot