Merge branch 'ia/ssh/improve_docs'

* ia/ssh/improve_docs:
  ssh: Move code example to Users Guide
  ssh: Keep dependency info in only one place
  ssh: Add links
  ssh: Align to alphabetic order
  ssh: Change wording to become accurate
  ssh: Remove extra whitespace
  ssh: Corrected information about error and event logging
  ssh: Remove legacy statement
  ssh: Technically correct description
  Editorial updates

1 files changed, 153 insertions, 135 deletions

diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml
index a52a6a115e..429ef3c849 100644
--- a/lib/ssh/doc/src/ssh_channel.xml
+++ b/lib/ssh/doc/src/ssh_channel.xml
@@ -23,69 +23,84 @@
       The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
     <title>ssh_channel</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
   </header>
   <module>ssh_channel</module>
   <modulesummary>-behaviour(ssh_channel).
   </modulesummary>
   <description>
     <p>SSH services (clients and servers) are implemented as channels
-    that are multiplexed over an SSH connection and communicates via
+    that are multiplexed over an SSH connection and communicates over
     the <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH
     Connection Protocol</url>. This module provides a callback API
-    that takes care of generic channel aspects such as flow control
-    and close messages and lets the callback functions take care of
+    that takes care of generic channel aspects, such as flow control
+    and close messages. It lets the callback functions take care of
     the service (application) specific parts. This behavior also ensures
     that the channel process honors the principal of an OTP-process so
     that it can be part of a supervisor tree. This is a requirement of
     channel processes implementing a subsystem that will be added to
-    the SSH applications supervisor tree.
+    the <c>ssh</c> applications supervisor tree.
     </p>
 
-    <note> <p>When implementing a SSH subsystem use the
-    <c>-behaviour(ssh_daemon_channel).</c> instead of  <c>-behaviour(ssh_channel).</c>
-    as the only relevant callback functions for subsystems are
-    init/1, handle_ssh_msg/2, handle_msg/2 and terminate/2, so the ssh_daemon_channel
-    behaviour is limited version of the ssh_channel behaviour.
-    </p> </note>
+    <note><p>When implementing an <c>ssh</c> subsystem, use
+    <c>-behaviour(ssh_daemon_channel)</c> instead of <c>-behaviour(ssh_channel)</c>.
+    The reason is that the only relevant callback functions for subsystems are
+    <c>init/1</c>, <c>handle_ssh_msg/2</c>, <c>handle_msg/2</c>, and <c>terminate/2</c>.
+    So, the <c>ssh_daemon_channel</c> behaviour is a limited version of the
+    <c>ssh_channel</c> behaviour.
+    </p></note>
   </description>
 
   <section>
-    <title>DATA TYPES </title>
+    <title>DATA TYPES</title>
 
-    <p>Type definitions that are used more than once in this module
-    and/or abstractions to indicate the intended use of the data
-    type:</p>
+    <p>Type definitions that are used more than once in this module,
+    or abstractions to indicate the intended use of the data
+    type, or both:</p>
     
-    <p><c>boolean() = true | false </c></p>
-    <p><c>string() = list of ASCII characters</c></p>
-    <p><c>timeout() =  infinity | integer() - in milliseconds.</c></p>
-    <p><c>ssh_connection_ref() - opaque to the user returned by
-    ssh:connect/3 or sent to an SSH channel process</c></p>
-    <p><c>ssh_channel_id() = integer() </c></p>
-    <p><c>ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are
-    currently valid values see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254  </url> section 5.2.</c></p>
+    <taglist>
+      <tag><c>boolean()</c></tag>
+      <item><p>= <c>true | false</c></p></item>
+      <tag><c>string()</c></tag>
+      <item><p>= list of ASCII characters</p></item>
+      <tag><c>timeout()</c></tag>
+      <item><p>= <c>infinity | integer()</c> in milliseconds</p></item>
+      <tag><c>ssh_connection_ref()</c></tag>
+      <item><p>Opaque to the user, returned by
+    <c>ssh:connect/3</c> or sent to an SSH channel process</p></item>
+      <tag><c>ssh_channel_id()</c></tag>
+      <item><p>= <c>integer()</c></p></item>
+      <tag><c>ssh_data_type_code()</c></tag>
+      <item><p>= <c>1</c> ("stderr") | <c>0</c> ("normal") are
+    the valid values,
+    see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>
+    Section 5.2</p></item>
+    </taglist>
   </section>
 
   <funcs>
     <func>
       <name>call(ChannelRef, Msg) -></name>
       <name>call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}</name>
-      <fsummary> Makes a synchronous call to a channel.</fsummary>
+      <fsummary>Makes a synchronous call to a channel.</fsummary>
       <type>
 	<v>ChannelRef = pid() </v>
-	<d>As returned by start_link/4 </d>
-	<v>Msg = term() </v>
-	<v>Timeout = timeout() </v>
-	<v>Reply = term() </v>
-	<v>Reason = closed | timeout </v>
+	<d>As returned by <c>start_link/4</c></d>
+	<v>Msg = term()</v>
+	<v>Timeout = timeout()</v>
+	<v>Reply = term()</v>
+	<v>Reason = closed | timeout</v>
 
       </type>
       <desc>
 	<p>Makes a synchronous call to the channel process by sending
-	a message and waiting until a reply arrives or a timeout
-	occurs. The channel will call <seealso marker =
+	a message and waiting until a reply arrives, or a time-out
+	occurs. The channel calls <seealso marker =
 	"#Module:handle_call-3">Module:handle_call/3</seealso>
-	to handle the message.  If the channel process does not exist
+	to handle the message. If the channel process does not exist,
 	<c>{error, closed}</c> is returned.
 	</p>
       </desc>
@@ -96,14 +111,14 @@
       <fsummary>Sends an asynchronous message to the channel
 	ChannelRef and returns ok.</fsummary>
       <type>
-	<v>ChannelRef = pid() </v>
-	<d>As returned by start_link/4 </d>
-	<v>Msg = term() </v>
+	<v>ChannelRef = pid()</v>
+	<d>As returned by <c>start_link/4</c></d>
+	<v>Msg = term()</v>
       </type>
       <desc>
 	<p>Sends an asynchronous message to the channel process and
 	returns ok immediately, ignoring if the destination node or
-	channel process does not exist. The channel will call
+	channel process does not exist. The channel calls
 	<seealso marker = "#Module:handle_cast-2">Module:handle_cast/2</seealso>
 	 to handle the message.
 	</p>
@@ -112,31 +127,32 @@
 
        <func>
       <name>enter_loop(State) -> _ </name>
-      <fsummary> Makes an existing process an ssh_channel process. </fsummary>
+      <fsummary>Makes an existing process an ssh_channel process.</fsummary>
       <type>
-	<v> State = term() - as returned by <seealso marker = "#init-1">ssh_channel:init/1</seealso></v>
+	<v>State = term() - as returned by
+	<seealso marker = "#init-1">ssh_channel:init/1</seealso></v>
       </type>
       <desc>
-	<p> Makes an existing process an <c>ssh_channel</c>
-	process. Does not return, instead the calling process will
-	enter the <c>ssh_channel</c> process receive loop and become an
-	<c>ssh_channel process.</c> The process must have been started using
-	one of the start functions in proc_lib, see <seealso
-	marker="stdlib:proc_lib">proc_lib(3)</seealso>. The
-	user is responsible for any initialization of the process
-	and needs to call <seealso marker = "#init-1">ssh_channel:init/1</seealso>
+	<p>Makes an existing process an <c>ssh_channel</c>
+	process. Does not return, instead the calling process
+	enters the <c>ssh_channel</c> process receive loop and become an
+	<c>ssh_channel process</c>. The process must have been started using
+	one of the start functions in <c>proc_lib</c>, see the <seealso
+	marker="stdlib:proc_lib">proc_lib(3)</seealso> manual page in <c>stdlib</c>.
+	The user is responsible for any initialization of the process
+	and must call <seealso marker = "#init-1">ssh_channel:init/1</seealso>.
 	</p>
       </desc>
     </func>
     
     <func>
       <name>init(Options) -> {ok, State} |  {ok, State, Timeout} | {stop, Reason} </name>
-      <fsummary> Initiates a ssh_channel process.</fsummary>
+      <fsummary>Initiates an <c>ssh_channel</c> process.</fsummary>
       <type>
 	<v>Options = [{Option, Value}]</v>
 	<v>State = term()</v>
-	<v>Timeout = timeout() </v>
-	<v>Reason = term() </v>
+	<v>Timeout = timeout()</v>
+	<v>Reason = term()</v>
       </type>
       <desc>
 	<p>
@@ -144,48 +160,47 @@
 	</p>
 	  <taglist>
 	  <tag><c><![CDATA[{channel_cb, atom()}]]></c></tag>
-	  <item>The module that implements the channel behaviour.</item>
+	  <item><p>The module that implements the channel behaviour.</p></item>
 	  
 	  <tag><c><![CDATA[{init_args(), list()}]]></c></tag>
-	  <item> The list of arguments to the callback module's
-	  init function.</item>
+	  <item><p>The list of arguments to the <c>init</c> function of the callback module.</p></item>
 
 	  <tag><c><![CDATA[{cm, connection_ref()}]]></c></tag>
-	  <item> Reference to the ssh connection as returned by  <seealso
-	  marker="ssh#connect-3">ssh:connect/3</seealso></item>
+	  <item><p>Reference to the <c>ssh</c> connection as returned by <seealso
+	  marker="ssh#connect-3">ssh:connect/3</seealso></p></item>
 	  
 	  <tag><c><![CDATA[{channel_id, channel_id()}]]></c></tag>
-	  <item> Id of the SSH channel.</item>
+	  <item><p>Id of the <c>ssh</c> channel.</p></item>
 	  
 	  </taglist>
 
 	  <note><p>This function is normally not called by the
-	  user. The user only needs to call if for some reason the
+	  user. The user only needs to call if the
 	  channel process needs to be started with help of
 	  <c>proc_lib</c> instead of calling
 	  <c>ssh_channel:start/4</c> or
-	  <c>ssh_channel:start_link/4</c> </p>
+	  <c>ssh_channel:start_link/4</c>.</p>
 	  </note>
       </desc>
     </func>
 
     <func>
       <name>reply(Client, Reply) -> _</name>
-      <fsummary>Send a reply to a client.</fsummary>
+      <fsummary>Sends a reply to a client.</fsummary>
       <type>
         <v>Client - opaque to the user, see explanation below</v>
         <v>Reply = term()</v>
       </type>
       <desc>
-        <p>This function can be used by a channel to explicitly send a
+        <p>This function can be used by a channel to send a
         reply to a client that called <c>call/[2,3]</c> when the reply
         cannot be defined in the return value of
 	<seealso marker ="#Module:handle_call-3">Module:handle_call/3</seealso>.</p>
         <p><c>Client</c> must be the <c>From</c> argument provided to
           the callback function <c>handle_call/3</c>.
 	  <c>Reply</c> is an arbitrary term,
-	  which will be given back to the client as the return value of
-          <seealso marker="#call-2">ssh_channel:call/[2,3].</seealso>></p>
+	  which is given back to the client as the return value of
+          <seealso marker="#call-2">ssh_channel:call/[2,3].</seealso></p>
       </desc>
     </func>
     
@@ -193,24 +208,25 @@
       <name>start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> </name>
       <name>start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) ->
       {ok, ChannelRef} | {error, Reason}</name>
-      <fsummary> Starts a processes that handles a SSH channel. </fsummary>
+      <fsummary>Starts a process that handles an SSH channel.</fsummary>
       <type>
 	<v>SshConnection = ssh_connection_ref()</v>
-	<v>ChannelId = ssh_channel_id() </v>
-	<d> As returned by cannot be defined in the return value of
-	<seealso marker ="ssh_connection#session_channel/2">ssh_connection:session_channel/[2,4]</seealso></d>
+	<v>ChannelId = ssh_channel_id()</v>
+	<d>As returned by
+	<seealso marker ="ssh_connection#session_channel/2">
+	ssh_connection:session_channel/[2,4]</seealso>.</d>
 	<v>ChannelCb = atom()</v>
-	<d> The name of the module implementing the service specific parts
+	<d>Name of the module implementing the service-specific parts
 	of the channel.</d>
 	<v>CbInitArgs = [term()]</v>
-	<d>Argument  list for the init function in the callback module. </d>
+	<d>Argument list for the <c>init</c> function in the callback module.</d>
 	<v>ChannelRef = pid()</v>
       </type>
       <desc>
-	<p>Starts a processes that handles an SSH channel. It will be
-	called internally by the SSH daemon or explicitly by the SSH
-	client implementations. The behavior will set the
-	<c>trap_exit</c> flag to true.
+	<p>Starts a process that handles an SSH channel. It is
+	called internally, by the <c>ssh</c> daemon, or explicitly by the <c>ssh</c>
+	client implementations. The behavior sets the
+	<c>trap_exit</c> flag to <c>true</c>.
 	</p>
       </desc>
     </func>
@@ -219,19 +235,19 @@
   
   <section>
     <marker id="cb_timeouts"></marker>
-    <title> CALLBACK TIMEOUTS</title>
+    <title>CALLBACK TIME-OUTS</title>
 
-    <p>The timeout values that may be returned by the callback functions
-    has the same semantics as in a <seealso marker="stdlib:gen_server">gen_server</seealso>
-    If the timeout occurs <seealso marker="#Module:handle_msg-2">handle_msg/2</seealso>
-    will be called as <c>handle_msg(timeout, State). </c></p>
+    <p>The time-out values that can be returned by the callback functions
+    have the same semantics as in a <seealso marker="stdlib:gen_server">gen_server</seealso>.
+    If the time-out occurs, <seealso marker="#Module:handle_msg-2">handle_msg/2</seealso>
+    is called as <c>handle_msg(timeout, State)</c>.</p>
   </section>
 
   <funcs>
     <func>
       <name>Module:code_change(OldVsn, State, Extra) -> {ok,
       NewState}</name>
-      <fsummary> Converts process state when code is changed.</fsummary>
+      <fsummary>Converts process state when code is changed.</fsummary>
       <type>
 	<v>OldVsn = term()</v>
 	<d>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
@@ -241,31 +257,31 @@
 	<c>Module</c>. If no such attribute is defined, the version is
 	the checksum of the BEAM file.</d>
 	<v>State = term()</v>
-	<d>The internal state of the channel.</d>
+	<d>Internal state of the channel.</d>
         <v>Extra = term()</v>
-	<d>Passed as-is from the <c>{advanced,Extra}</c>
+	<d>Passed “as-is” from the <c>{advanced,Extra}</c>
 	part of the update instruction.</d>
       </type>
       <desc>
-	<p> Converts process state when code is changed.</p>
+	<p>Converts process state when code is changed.</p>
 
-	<p>This function is called by a client side channel when it
-	should update its internal state during a release
-	upgrade/downgrade, i.e. when the instruction
-	<c>{update,Module,Change,...}</c> where
-	<c>Change={advanced,Extra}</c> is given in the <c>appup</c>
-	file. See <seealso marker="doc/design_principles:release_handling#instr">OTP
-	Design Principles</seealso> for more information.
+	<p>This function is called by a client-side channel when it
+	is to update its internal state during a release
+	upgrade or downgrade, that is, when the instruction
+	<c>{update,Module,Change,...}</c>, where
+	<c>Change={advanced,Extra}</c>, is given in the <c>appup</c>
+	file. For more information, refer to Section 9.11.6
+	Release Handling Instructions in the
+	<seealso marker="doc/design_principles:release_handling#instr">System Documentation</seealso>.
 	</p>
 
 	<note><p>Soft upgrade according to the OTP release concept
 	is not straight forward for the server side, as subsystem
-	channel processes are spawned by the SSH application and
-	hence added to its supervisor tree. It could be possible to
-	upgrade the subsystem channels, when upgrading the user
-	application, if the callback functions can handle two
-	versions of the state, but this function can not be used in
-	the normal way.</p>
+	channel processes are spawned by the <c>ssh</c> application and
+	hence added to its supervisor tree. The subsystem channels can
+	be upgraded when upgrading the user application, if the callback
+	functions can handle two versions of the state, but this function
+	cannot be used in the normal way.</p>
 	</note>
 	  
       </desc>
@@ -274,30 +290,30 @@
     <func>
       <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} |
       {stop, Reason}</name>
-      <fsummary> Makes necessary initializations and returns the
+      <fsummary>Makes necessary initializations and returns the
       initial channel state if the initializations succeed.</fsummary>
       <type>
-	<v> Args = term() </v>
-	<d> Last argument to ssh_channel:start_link/4.</d>
-	<v> State = term() </v>
-	<v> Reason = term() </v>
+	<v>Args = term()</v>
+	<d>Last argument to <c>ssh_channel:start_link/4</c>.</d>
+	<v>State = term()</v>
+	<v>Reason = term()</v>
       </type>
       <desc>
-	<p> Makes necessary initializations and returns the initial channel
+	<p>Makes necessary initializations and returns the initial channel
 	state if the initializations succeed.
 	</p>
-	<p>For more detailed information on timeouts see the section 
-	<seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+	<p>For more detailed information on time-outs, see Section
+	<seealso marker="#cb_timeouts">CALLBACK TIME-OUTS</seealso>. </p>
       </desc>
     </func>
    
     <func>
       <name>Module:handle_call(Msg, From, State) -> Result</name>
-      <fsummary> Handles messages sent by calling
-      <c>ssh_channel:call/[2,3]</c></fsummary>
+      <fsummary>Handles messages sent by calling
+      <c>ssh_channel:call/[2,3]</c>.</fsummary>
       <type>
 	<v>Msg = term()</v>
-	<v>From = opaque to the user should be used as argument to
+	<v>From = Opaque to the user, is to be used as argument to
 	ssh_channel:reply/2</v>
 	<v>State = term()</v>
 	<v>Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()}
@@ -311,15 +327,15 @@
 	<p>Handles messages sent by calling
 	<seealso marker="#call-2">ssh_channel:call/[2,3]</seealso>
 	</p>
-	<p>For more detailed information on timeouts see the section 
-	<seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+	<p>For more detailed information on time-outs,, see Section
+	<seealso marker="#cb_timeouts">CALLBACK TIME-OUTS</seealso>.</p>
       </desc>
     </func>
 
     <func>
       <name>Module:handle_cast(Msg, State) -> Result</name>
-      <fsummary> Handles messages sent by calling
-      <c>ssh_channel:cact/2</c></fsummary>
+      <fsummary>Handles messages sent by calling
+      <c>ssh_channel:cact/2</c>.</fsummary>
       <type>
 	<v>Msg = term()</v>
 	<v>State = term()</v>
@@ -329,11 +345,11 @@
 	<v>Reason = term()</v>
       </type>
       <desc>
-	<p> Handles messages sent by calling
-	<c>ssh_channel:cast/2</c>
+	<p>Handles messages sent by calling
+	<c>ssh_channel:cast/2</c>.
 	</p>
-	<p>For more detailed information on timeouts see the section 
-	<seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+	<p>For more detailed information on time-outs, see Section
+	<seealso marker="#cb_timeouts">CALLBACK TIME-OUTS</seealso>.</p>
       </desc>
     </func>
  
@@ -341,33 +357,33 @@
       <name>Module:handle_msg(Msg, State) -> {ok, State} |
       {stop, ChannelId, State}</name>
 
-      <fsummary> Handle other messages than SSH connection protocol,
-      call or cast messages sent to the channel.</fsummary>
+      <fsummary>Handles other messages than SSH connection protocol,
+      call, or cast messages sent to the channel.</fsummary>
       <type>
 	<v>Msg = timeout | term()</v>
 	<v>ChannelId = ssh_channel_id()</v>
 	<v>State = term() </v>
       </type>
       <desc>
-	<p>Handle other messages than ssh connection protocol, call or
+	<p>Handles other messages than SSH Connection Protocol, call, or
 	cast messages sent to the channel. 
 	</p>
 
-	<p> Possible erlang 'EXIT'-messages should be handled by this
-	function and all channels should handle the following message.</p>
+	<p>Possible Erlang 'EXIT' messages is to be handled by this
+	function and all channels are to handle the following message.</p>
 	
 	<taglist>
 	  <tag><c><![CDATA[{ssh_channel_up, ssh_channel_id(), 
 	  ssh_connection_ref()}]]></c></tag>
-	  <item>This is the first messages that will be received by
-	  the channel, it is sent just before the <seealso
+	  <item><p>This is the first message that the channel receives.
+	  It is sent just before the <seealso
 	  marker="#init-1">ssh_channel:init/1</seealso> function
-	  returns successfully.  This is especially useful if the
+	  returns successfully. This is especially useful if the
 	  server wants to send a message to the client without first
 	  receiving a message from it. If the message is not
-	  useful for your particular scenario just ignore it by
-	  immediately returning {ok, State}.
-	  </item>
+	  useful for your particular scenario, ignore it by
+	  immediately returning <c>{ok, State}</c>.
+	  </p></item>
 	</taglist>
       </desc>
     </func>
@@ -375,42 +391,44 @@
     <func>
       <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop,
       ChannelId, State}</name>
-      <fsummary> Handles ssh connection protocol messages. </fsummary>
+      <fsummary>Handles <c>ssh</c> connection protocol messages.</fsummary>
       <type>
-	<v>Msg = <seealso marker="ssh_connection"> ssh_connection:event() </seealso> </v>
+	<v>Msg = ssh_connection:event()</v>
 	<v>ChannelId = ssh_channel_id()</v>
 	<v>State = term()</v>
       </type>
       <desc>
-	<p> Handles SSH connection protocol messages that may need
-	service specific attention.
+	<p>Handles SSH Connection Protocol messages that may need
+	service-specific attention. For details,
+	see <seealso marker="ssh_connection"> ssh_connection:event()</seealso>.
 	</p>
 	
-	<p> The following message is completely taken care of by the
-	SSH channel behavior</p>
+	<p>The following message is taken care of by the
+	<c>ssh_channel</c> behavior.</p>
 	
 	<taglist>
 	  <tag><c><![CDATA[{closed, ssh_channel_id()}]]></c></tag>
-	  <item> The channel behavior will send a close message to the
-	  other side if such a message has not already been sent and
-	  then terminate the channel with reason normal.</item>
+	  <item><p>The channel behavior sends a close message to the
+	  other side, if such a message has not already been sent.
+	  Then it terminates the channel with reason <c>normal</c>.</p></item>
 	</taglist>
       </desc>
     </func>
 
     <func>
       <name>Module:terminate(Reason, State) -> _</name>
-      <fsummary> </fsummary>
+      <fsummary>Does cleaning up before channel process termination.
+</fsummary>
       <type>
 	<v>Reason = term()</v>
 	<v>State = term()</v>
       </type>
       <desc>
 	<p>This function is called by a channel process when it is
-	about to terminate. Before this function is called <seealso
+	about to terminate. Before this function is called, <seealso
 	marker="ssh_connection#close-2"> ssh_connection:close/2
-	</seealso> will be called if it has not been called earlier.
-	This function should do any necessary cleaning
+	</seealso> is called, if it has not been called earlier.
+	This function does any necessary cleaning
 	up. When it returns, the channel process terminates with
 	reason <c>Reason</c>. The return value is ignored.
 	</p>