[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [tor-talk] torrc consistency



On 03/09/2011 12:47 PM, bertagaz@xxxxxxxxxxxxxxxxxx wrote:
> On Wed, Mar 09, 2011 at 04:25:40PM +0100, Anders Andersson wrote:
>> On Wed, Mar 9, 2011 at 2:56 PM,  <bertagaz@xxxxxxxxxxxxxxxxxx> wrote:
>>> Seems that there are already kind of a convention in the way it is
>>> written :
>>>
>>> - Lines starting with '## ' are descriptions of a block of items
>>> - Lines starting with '#' are commented items.
>>> - Items are in the form of 'Item value'
>>> - Items sometimes have short descriptions/examples following them on the
>>>  same line, beginning by a #
>>>
>>> The last point is the one that lacks consistency. Sometimes items
>>> descriptions/examples are on top of the concerned item, sometimes on the
>>> same line, right after the item.
>>>
>>> That would make the job easier if there was a clear convention for this
>>> file, and if it was applied correctly everywhere.
>>>
>>> What do you think? What would be the best way to write this file?
>> Sounds to me that everything after a '#' is a comment, like in pretty
>> much every other config file or scripting language. How can this be a
>> problem?
>> Why should Config::Model even bother about comments?
> Config::Model probably not, but still I believe it's better if that kind
> of tools don't modify too much the config file and keep it closed from the
> one provided upstream.
Why?

A config tool need not even read the config as it stands, it could store
all configs in a database and just pump out text versions as needed. If
a person is using a config tool, I see no reason to expect all manner of
comments in the resulting file. The purpose of the tool is to configure
not to teach. Most, if not all, options are described in the man page
anyway....

Why not just have a sample config, and have 1 comment that points to
that...or points to the man page, which describes all of the options? If
I am reading a config in production, I find all the comments annoying. I
would rather the ONLY comments in a deployed file be "We set this
because...." or "Changed on this date by", and I wouldn't expect those
to be set by a 3rd party config tool.

A config file does not take the place of documentation. This stuff is
already well documented, so that isn't even a problem.

All that said, if you must read the file, well, its format is what it
is. Inline comments are already allowed, as long as they continue to be,
I think it does behoove you to support them. Its a pain but, not THAT hard.

-Steve
_______________________________________________
tor-talk mailing list
tor-talk@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-talk