SAM: Fix docs for STREAM ACCEPT when SILENT=true

Clarify that FORWARD works differently than ACCEPT and CONNECT when SILENT=true
cleanups

i2p2www/pages/site/docs/api/samv3.html

@@ -170,11 +170,11 @@ As of version 3.1 (I2P 0.9.14), the MIN and MAX parameters are optional.
 SAM will always return the highest version possible given the
 MIN and MAX constraints, or 3.1 if no constraints are given.
 
-If the SAM bridge cannot find a suitable version, it replies with :
+If the SAM bridge cannot find a suitable version, it replies with:
 <pre>
 &lt;- HELLO REPLY RESULT=NOVERSION
 </pre>
-If some error occurred, such as a bad request format, it replies with :
+If some error occurred, such as a bad request format, it replies with:
 <pre>
 &lt;- HELLO REPLY RESULT=I2P_ERROR MESSAGE=$message
 </pre>
@@ -191,7 +191,7 @@ Each registered I2P Destination is uniquely associated with a session ID
 (or nickname).
 
 </p><p>
-Each session is uniquely associated with :
+Each session is uniquely associated with:
 <ul><li>
 the socket from which the client creates the session
 </li><li>
@@ -247,7 +247,7 @@ After receiving the session create message, the SAM bridge will reply
 with a session status message, as follows:
 
 </p><p>
-If the creation was successful :
+If the creation was successful:
 <pre>
 &lt;-  SESSION STATUS RESULT=OK DESTINATION=$privkey
 </pre>
@@ -261,25 +261,25 @@ depending on signature type.
 The binary format is specified in <a href="http://docs.i2p-projekt.de/javadoc/net/i2p/data/PrivateKeyFile.html">Private Key File</a>.
 
 </p><p>
-If the nickname is already associated with a session :
+If the nickname is already associated with a session:
 <pre>
 &lt;-  SESSION STATUS RESULT=DUPLICATED_ID
 </pre>
 
 </p><p>
-If the destination is already in use :
+If the destination is already in use:
 <pre>
 &lt;-  SESSION STATUS RESULT=DUPLICATED_DEST
 </pre>
 
 </p><p>
-If the destination is not a valid private destination key :
+If the destination is not a valid private destination key:
 <pre>
 &lt;-  SESSION STATUS RESULT=INVALID_KEY
 </pre>
 
 </p><p>
-If some other error has occurred :
+If some other error has occurred:
 <pre>
 &lt;-  SESSION STATUS RESULT=I2P_ERROR MESSAGE=$message
 </pre>
@@ -313,13 +313,13 @@ he wants to listen to requests coming from other I2P destinations.
 
 <h3>SAM Virtual Streams : CONNECT</h3>
 <p>
-A client asks for a connection by :
+A client asks for a connection by:
 <ul><li>
 opening a new socket with the SAM bridge
 </li><li>
 passing the same HELLO handshake as above
 </li><li>
-sending the connection command :  
+sending the STREAM CONNECT command:  
 </li></ul>
 
 <pre>
@@ -340,7 +340,7 @@ depending on signature type.
 
 </p><p>
 If SILENT=true is passed, the SAM bridge won't issue any other message
-on the socket : if the connection fails, the socket will be closed.
+on the socket. If the connection fails, the socket will be closed.
 If the connection succeeds, all remaining data passing through the
 current socket is forwarded from and to the connected I2P destination
 peer.
@@ -348,7 +348,7 @@ peer.
 </p><p>
 If SILENT=false, which is the default value, the SAM bridge sends a
 last message to its client before forwarding or shutting down the
-socket :
+socket:
 
 <pre>
 &lt;-  STREAM STATUS 
@@ -379,13 +379,13 @@ socket.
 
 <h3>SAM Virtual Streams : ACCEPT</h3>
 <p>
-A client waits for an incoming connection request by :
+A client waits for an incoming connection request by:
 <ul><li>
 opening a new socket with the SAM bridge
 </li><li>
 passing the same HELLO handshake as above
 </li><li>
-sending the accept command :  
+sending the STREAM ACCEPT command:  
 </li></ul>
 
 <pre>
@@ -399,7 +399,18 @@ This makes the session ${nickname} listen for one incoming
 connection request from the I2P network.
 
 </p><p>
-The SAM bridge answers with :
+If SILENT=true is passed, the SAM bridge won't issue any other message
+on the socket. If the accept fails, the socket will be closed.
+If the accept succeeds, all remaining data passing through the
+current socket is forwarded from and to the connected I2P destination
+peer. 
+For reliability, and to receive the destination for incoming connections,
+SILENT=false is recommended.
+
+
+</p><p>
+If SILENT=false, which is the default value,
+the SAM bridge answers with:
 
 <pre>
 &lt;-  STREAM STATUS 
@@ -420,11 +431,11 @@ The RESULT value may be one of:
 If the result is not OK, the socket is closed immediately by the SAM
 bridge. If the result is OK, the SAM bridge starts waiting for an
 incoming connection request from another I2P peer. When a request
-arrives, the SAM bridge accepts it and :
+arrives, the SAM bridge accepts it and:
 
 </p><p>
 If SILENT=true was passed, the SAM bridge won't issue any other message
-on the client socket : all remaining data passing through the
+on the client socket. All remaining data passing through the
 current socket is forwarded from and to the connected I2P destination
 peer.
 
@@ -439,13 +450,13 @@ I2P destination peer, until one of the peer closes the socket.
 <h3>SAM Virtual Streams : FORWARD</h3>
 <p>
 A client can use a regular socket server and wait for connection requests
-coming from I2P. For that, the client has to :
+coming from I2P. For that, the client must:
 <ul><li>
 open a new socket with the SAM bridge
 </li><li>
 pass the same HELLO handshake as above
 </li><li>
-send the forward command :
+send the forward command:
 </ul></li>
 
 <pre>
@@ -461,7 +472,12 @@ This makes the session ${nickname} listen for incoming
 connection requests from the I2P network.
 
 </p><p>
-The SAM bridge answers with :
+SILENT defaults to false.
+Whether SILENT is true or false,
+the SAM bridge always answers with a STREAM STATUS message.
+Note that this is a different behavior from STREAM ACCEPT and STREAM CONNECT
+when SILENT=true.
+The STREAM STATUS message is:
 
 <pre>
 &lt;-  STREAM STATUS 
@@ -490,7 +506,7 @@ forward connection requests. It is mandatory.
 </p><p>
 When a connection request arrives from I2P, the SAM bridge requests a
 socket connection from $host:$port. If it is accepted after no more
-than 3 seconds, SAM will accept the connection from I2P, and then :
+than 3 seconds, SAM will accept the connection from I2P, and then:
 
 </p><p>
 If SILENT=true was passed, all data passing through the obtained
@@ -532,8 +548,8 @@ After establishing a SAM session with STYLE=DATAGRAM, the client can
 send datagrams through SAM's UDP port (7655).
 
 </p><p>
-The first line of a datagram sent through this port has to be in the
+The first line of a datagram sent through this port must be in the
-following format :
+following format:
 
 <p>
 3.0 $nickname $destination
@@ -553,7 +569,7 @@ following format :
 
 </p><p>
 The first line will be discarded by SAM before sending the remaining
-of the message to the specified destination.
+data of the message to the specified destination.
 
 </p><p>
 For an alternate method of sending repliable datagrams, see <a href="#dgsend">DATAGRAM SEND</a>.
@@ -567,7 +583,7 @@ command.
 
 </p><p>
 When a datagram arrives, the bridge delivers it to the client via the
-message :
+message:
 
 <pre>
 &lt;-  DATAGRAM RECEIVED
@@ -590,7 +606,7 @@ connection).
 <p>
 When creating a datagram session, the client can ask SAM to forward
 incoming messages to a specified ip:port. It does so by issuing the
-CREATE command with PORT and HOST options :
+CREATE command with PORT and HOST options:
 
 <pre>
 -&gt; SESSION CREATE 
@@ -628,7 +644,7 @@ outbound.length=0). These options <a href="#options">are documented below</a>..
 Forwarded datagrams are always prefixed with the destination
 (SILENT=false); SILENT=true is not honored.
 When a datagram arrives, the bridge sends to the specified host:port
-a UDP packet containing the following data :
+a UDP packet containing the following data:
 
 <pre>
 $destination\n$datagram_payload
@@ -673,7 +689,7 @@ the session,the bridge delivers it to the client via:
 </p><p>
 When anonymous datagrams are to be forwarded to some host:port,
 the bridge sends to the specified host:port a message containing 
-the following data :
+the following data:
 
 <pre>
 $datagram_payload