[or-cvs] [tor/master 1/5] Clarify description of FEATURES in control-spec.

[nickm@xxxxxxxxxxxxxx]

Author: Poet (Tim Sally) <poet@xxxxxxxx>
Date: Wed, 1 Dec 2010 05:21:34 -0600
Subject: Clarify description of FEATURES in control-spec.
Commit: cff180f8b0e2066e566ba63ef4197e1463aa1fb1

(1) On by default is a bad way to describe features. Rather, they
are always on and should be viewed as a part of the control
protocol. Updated the wording in USEFEATURE to reflect this.

(2) Made descriptions of Tor versions consistant across all
features. There is the version in which a feature was introduced and
the version in which it became part of the protocol.

(3) Reworded the description of the VERBOSE_NAMES feature. The
previous wording describes the way things used to be first. Better to
lead with the current state of things and then describe how it differs
from old versions.
---
 doc/spec/control-spec.txt |   47 +++++++++++++++++++++++----------------------
 1 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index 1864666..3bc1c54 100644
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -770,46 +770,47 @@
 
 3.19. USEFEATURE
 
+  Adding additional features to the control protocol sometimes will break
+  backwards compatibility. Initially such features are added into Tor and
+  disabled by default. USEFEATURE can enable these additional features.
+
   The syntax is:
 
     "USEFEATURE" *(SP FeatureName) CRLF
     FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
 
-  Sometimes extensions to the controller protocol break compatibility with
-  older controllers.  In this case, whenever possible, the extensions are
-  first included in Tor disabled by default, and only enabled on a given
-  controller connection when the "USEFEATURE" command is given.  Once a
-  "USEFEATURE" command is given, it applies to all subsequent interactions on
-  the same connection; to disable an enabled feature, a new controller
-  connection must be opened.
+  Feature names are case-insensitive.
 
-  This is a forward-compatibility mechanism; each feature will eventually
-  become a regular part of the control protocol in some future version of Tor.
-  Tor will ignore a request to use any feature that is already on by default.
-  Tor will give a "552" error if any requested feature is not recognized.
+  Once enabled, a feature stays enabled for the duration of the connection
+  to the controller. A new connection to the controller must be opened to
+  disable an enabled feature.
 
-  Feature names are case-insensitive.
+  Features are a forward-compatibility mechanism; each feature will eventually
+  become a standard part of the control protocol. Once a feature becomes part
+  of the protocol, it is always-on. Each feature documents the version it was
+  introduced as a feature and the version in which it became part of the
+  protocol.
+
+  Tor will ignore a request to use any feature that is always-on. Tor will give
+  a 552 error in response to an unrecognized feature.
 
   EXTENDED_EVENTS
 
      Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
      request the extended event syntax.
 
-    This feature was first used in 0.1.2.3-alpha.  It is always-on in
-    Tor 0.2.2.1-alpha and later.
+     This feature was first introduced in 0.1.2.3-alpha.  It is always-on
+     and part of the protocol in Tor 0.2.2.1-alpha and later.
 
   VERBOSE_NAMES
 
-     Instead of ServerID as specified above, the controller should
-     identify ORs by LongName in events and GETINFO results.  This format is
-     strictly more informative: rather than including Nickname for
-     known Named routers and Fingerprint for unknown or unNamed routers, the
-     LongName format includes a Fingerprint, an indication of Named status,
-     and a Nickname (if one is known).
+     Replaces ServerID with LongName in events and GETINFO results. LongName
+     provides a Fingerprint for all routers, an indication of Named status,
+     and a Nickname if one is known. LongName is strictly more informative
+     than ServerID, which only provides either a Fingerprint or a Nickname.
 
-     This will not be always-enabled until at least two stable
-     releases after 0.1.2.2-alpha, the release where it was first
-     available.  It is always-on in Tor 0.2.2.1-alpha and later.
+     This feature was first introduced in 0.1.2.2-alpha. It is always-on and
+     part of the protocol in Tor 0.2.2.1-alpha and later.
 
 3.20. RESOLVE
 
-- 
1.7.1