[tor-bugs] #13158 [Tor]: Did we ever document +/ semantics for config files?

[Tor Bug Tracker & Wiki]

#13158: Did we ever document +/ semantics for config files?
---------------------------+--------------------------------
     Reporter:  Sebastian  |      Owner:
         Type:  defect     |     Status:  new
     Priority:  normal     |  Milestone:  Tor: 0.2.5.x-final
    Component:  Tor        |    Version:
   Resolution:             |   Keywords:
Actual Points:             |  Parent ID:
       Points:             |
---------------------------+--------------------------------

Comment (by nickm):

 Here is the relevant situation of doc/tor.1.txt:

 {{{
 THE CONFIGURATION FILE FORMAT
 -----------------------------

 All configuration options in a configuration are written on a single line
 by
 default.  They take the form of an option name and a value, or an option
 name
 and a quoted value (option value or option "value"). Anything after a #
 character is treated as a comment.  Options are
 case-insensitive. C-style escaped characters are allowed inside quoted
 values. To split one configuration entry into multiple lines, use a single
 backslash character (\) before the end of the line.  Comments can be used
 in
 such multiline entries, but they must start at the beginning of a line.

 By default, an option on the command line overrides an option found in the
 configuration file, and an option in a configuration file overrides one in
 the defaults file.

 This rule is simple for options that take a single value, but it can
 become
 complicated for options that are allowed to occur more than once: if you
 specify four SOCKSPorts in your configuration file, and one more SOCKSPort
 on
 the command line, the option on the command line will replace __all__ of
 the
 SOCKSPorts in the configuration file.  If this isn't what you want, prefix
 the option name with a plus sign, and it will be appended to the previous
 set
 of options instead.

 Alternatively, you might want to remove every instance of an option in the
 configuration file, and not replace it at all: you might want to say on
 the
 command line that you want no SOCKSPorts at all.  To do that, prefix the
 option name with a forward slash.
 }}}

 How should this be rewritten?  Where should it go instead?  I'd be happy
 to take a patch here.

 > Also, I admit that I'm not really sold on this new syntax -- so I've
 been trying to avoid situations where ordinary users actually need to use
 it or know about it.

 Going forward: please let me know early in the 0.2.6 series about
 situations where we're committing or about to commit stuff that you think
 you're going to be remain unsold on. :)

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/13158#comment:2>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online