[or-cvs] [tor/master 2/5] Several changes to the way tokens describing servers are documented.

[nickm at torproject.org]

Author: Poet (Tim Sally) <poet at stack.io>
Date: Wed, 1 Dec 2010 05:24:33 -0600
Subject: Several changes to the way tokens describing servers are documented.
Commit: 608bad6e3246d1bfbcb4e3009237f72d3292b747

(1) Made the wording of the comments consistant with token names.
Digest/Fingerprint and Name/Nickname were being used interchangeably.
Better to just use Fingerprint and Nickname becuase they are the names
of the tokens.

(2) Places the tokens currently in use before the tokens used in older
versions.  ServerSpec should be documented before ServerID.

(3) Added a note to the comments about ServerID that cross reference
the VERBOSE_FEATURE, allowing users to see when and why ServerID was
replaced with LongName.
---
 doc/spec/control-spec.txt |   39 +++++++++++++++++++++------------------
 1 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/doc/spec/control-spec.txt b/doc/spec/control-spec.txt
index 3bc1c54..1b9a692 100644
--- a/doc/spec/control-spec.txt
+++ b/doc/spec/control-spec.txt
@@ -96,32 +96,35 @@
   ; followed by the ASCII Linefeed character (decimal value 10)."
   CRLF = CR LF
 
-  ; Identifiers for servers.
-  ServerID = Nickname / Fingerprint
-
-  Nickname = 1*19 NicknameChar
-  NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
-  Fingerprint = "$" 40*HEXDIG
-
-  ; A "=" indicates that the given nickname is canonical; a "~" indicates
-  ; that the given nickname is not canonical.  If no nickname is given at
-  ; all, Tor does not even have a guess for what this router calls itself.
-  LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
-
   ; How a controller tells Tor about a particular OR.  There are four
   ; possible formats:
-  ;    $Digest -- The router whose identity key hashes to the given digest.
+  ;    $Fingerprint -- The router whose identity key hashes to the fingerprint.
   ;        This is the preferred way to refer to an OR.
-  ;    $Digest~Name -- The router whose identity key hashes to the given
-  ;        digest, but only if the router has the given nickname.
-  ;    $Digest=Name -- The router whose identity key hashes to the given
-  ;        digest, but only if the router is Named and has the given
+  ;    $Fingerprint~Nickname -- The router whose identity key hashes to the
+  ;        given fingerprint, but only if the router has the given nickname.
+  ;    $Fingerprint=Nickname -- The router whose identity key hashes to the
+  ;        given fingerprint, but only if the router is Named and has the given
   ;        nickname.
-  ;    Name -- The Named router with the given nickname, or, if no such
+  ;    Nickname -- The Named router with the given nickname, or, if no such
   ;        router exists, any router whose nickname matches the one given.
   ;        This is not a safe way to refer to routers, since Named status
   ;        could under some circumstances change over time.
+  ;
+  ; The tokens that implement the above follow:
+
   ServerSpec = LongName / Nickname
+  LongName   = Fingerprint [ ( "=" / "~" ) Nickname ]
+
+  Fingerprint = "$" 40*HEXDIG
+  NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
+  Nickname = 1*19 NicknameChar
+
+  ; What follows is an outdated way to refer to ORs.
+  ; Feature VERBOSE_NAMES replaces ServerID with LongName in events and
+  ; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version
+  ; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later.
+  ServerID = Nickname / Fingerprint
+
 
   ; Unique identifiers for streams or circuits.  Currently, Tor only
   ; uses digits, but this may change
-- 
1.7.1