Editorial updates

SSH application

12 files changed, 1128 insertions, 819 deletions

diff --git a/lib/ssh/doc/src/introduction.xml b/lib/ssh/doc/src/introduction.xml
index b42910cb34..70c6fb2ee1 100644
--- a/lib/ssh/doc/src/introduction.xml
+++ b/lib/ssh/doc/src/introduction.xml
@@ -25,31 +25,181 @@
 
     <title>Introduction</title>
     <prepared>OTP team</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
     <file>introduction.xml</file>
   </header>
-
+  <p>SSH is a protocol for secure remote logon and
+    other secure network services over an insecure network.</p>
   <section>
-    <title>Purpose</title>
+    <title>Scope and Purpose</title>
 
-    <p>Secure Shell (SSH) is a protocol for secure remote login and
-    other secure network services over an insecure network. SSH
-    provides a single, full-duplex, byte-oriented connection between
+    <p>SSH provides a single, full-duplex, and byte-oriented connection between
     client and server. The protocol also provides privacy, integrity,
-    server authentication and man-in-the-middle protection.</p>
-
-    <p>The Erlang SSH application is an implementation of the SSH
-    protocol in Erlang which offers API functions to write customized
-    SSH clients and servers as well as making the Erlang shell
-    available via SSH. Also included in the SSH application are an
-    SFTP (SSH File Transfer Protocol) client <seealso
-    marker="ssh_sftp">ssh_sftp</seealso> and server <seealso
-    marker="ssh_sftp">ssh_sftpd</seealso>.</p>
+    server authentication, and man-in-the-middle protection.</p>
+
+    <p>The <c>ssh</c> application is an implementation of the SSH Transport
+    Layer Protocol in Erlang. It provides the following:</p>
+    <list type="bulleted">
+      <item>API functions to write customized SSH clients and servers</item>
+      <item>The Erlang shell available through SSH</item>
+      <item>An SFTP client (<seealso marker="ssh_sftp">ssh_sftp</seealso>)
+      and server (<seealso marker="ssh_sftp">ssh_sftpd</seealso>)</item>
+    </list>
   </section>
 
   <section>
     <title>Prerequisites</title>
-    <p>It is assumed that the reader is familiar with the concepts of <seealso marker="doc/design_principles:des_princ">OTP</seealso>
-    and has a basic understanding of <url href="http://en.wikipedia.org/wiki/Public-key_cryptography">public keys</url>.</p>
+    <p>It is assumed that the reader is familiar with the Erlang programming language,
+    concepts of <em>OTP</em>, and has a basic understanding of <em>public keys</em>.</p>
+  </section>
+
+<section>
+    <title>SSH Protocol Overview</title>
+
+    <p>Conceptually, the SSH protocol can be partitioned into four
+    layers:</p>
+
+    <image file="SSH_protocols.png">
+      <icaption>SSH Protocol Architecture</icaption>
+    </image>
+
+    <section>
+      <title>Transport Protocol</title>
+
+      <p>The SSH Transport Protocol is a secure, low-level transport.
+      It provides strong encryption, cryptographic host
+      authentication, and integrity protection. A minimum of
+      Message Authentication Code (MAC) and encryption
+      algorithms are supported. For details, see the
+      <seealso marker="ssh">ssh(3)</seealso> manual page in <c>ssh</c>.</p>
+    </section>
+
+    <section>
+      <title>Authentication Protocol</title>
+
+      <p>The SSH Authentication Protocol is a general-purpose user
+      authentication protocol run over the SSH Transport Layer
+      Protocol. The <c>ssh</c> application supports user authentication as follows:
+      </p>
+      <list type="bulleted">
+	<item>
+	  Using public key technology. RSA and DSA, X509-certificates
+	  are not supported.
+	</item>
+	<item>
+	  Using keyboard-interactive authentication.
+	  This is suitable for interactive authentication methods
+	  that do not need any special software support on the client side.
+	  Instead, all authentication data is entered from the keyboard.
+	</item>
+	<item>
+	  Using a pure password-based authentication scheme.
+	  Here, the plain text password is encrypted before sent
+	  over the network.
+	</item>
+      </list>
+      <p>Several configuration options for
+      authentication handling are available in
+      <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso>
+      and <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso>.</p>
+      <p>
+      The public key handling can be customized by implementing
+      the following behaviours from <c>ssh</c>:</p>
+      <list type="bulleted">
+	<item>Module
+      <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>.
+	</item>
+	<item>Module
+      <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
+	</item>
+      </list>
+    </section>
+
+    <section>
+      <title>Connection Protocol</title>
+
+      <p>The SSH Connection Protocol provides application-support
+      services over the transport pipe, for example, channel multiplexing,
+      flow control, remote program execution, signal propagation, and
+      connection forwarding. Functions for handling the SSH
+      Connection Protocol can be found in the module <seealso
+      marker="ssh_connection">ssh_connection</seealso> in <c>ssh</c>.
+      </p>
+    </section>
+
+    <section>
+      <title>Channels</title>
+
+      <p>All terminal sessions, forwarded connections, and so on, are
+      channels. Multiple channels are multiplexed into a single
+      connection. All channels are flow-controlled. This means that no
+      data is sent to a channel peer until a message is received to
+      indicate that window space is available.
+      The <em>initial window size</em> specifies how many bytes of channel
+      data that can be sent to the channel peer without adjusting the
+      window. Typically, an SSH client opens a channel, sends data (commands),
+      receives data (control information), and then closes the channel.
+      The <seealso marker="ssh_channel">ssh_channel</seealso> behaviour
+      handles generic parts of SSH channel management. This makes it easy
+      to write your own SSH client/server processes that use flow-control
+      and thus opens for more focus on the application logic.
+      </p>
+
+      <p>Channels come in the following three flavors:</p>
+
+      <list type="bulleted">
+	<item><em>Subsystem</em> - Named services that can be run as
+	part of an SSH server, such as SFTP <seealso
+	marker="ssh_sftpd">(ssh_sftpd)</seealso>, that is built into the
+	SSH daemon (server) by default, but it can be disabled. The Erlang <c>ssh</c>
+	daemon can be configured to run any Erlang-
+	implemented SSH subsystem.
+	</item>
+	<item><em>Shell</em> - Interactive shell. By default the
+	Erlang daemon runs the Erlang shell. The shell can be customized by
+	providing your own read-eval-print loop. You can also provide your
+	own Command-Line Interface (CLI) implementation,
+	but that is much more work.
+	</item>
+	<item><em>Exec</em> - One-time remote execution of commands. See function
+	<seealso marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso>
+	for more information.</item>
+      </list>
+    </section>
+
+
+
   </section>
 
+  <section>
+    <title>Where to Find More Information</title>
+    <p>
+      For detailed information about the SSH protocol, refer to the
+      following Request for Comments(RFCs):
+    </p>
+
+    <list type="bulleted">
+      <item><url href="http://www.ietf.org/rfc/rfc4250.txt">RFC 4250</url> -
+      Protocol Assigned Numbers</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4251.txt">RFC 4251</url> -
+      Protocol Architecture</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4252.txt">RFC 4252</url> -
+      Authentication Protocol</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4253.txt">RFC 4253</url> -
+      Transport Layer Protocol</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> -
+      Connection Protocol</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4255.txt">RFC 4255</url> -
+      Key Fingerprints</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4344.txt">RFC 4344</url> -
+      Transport Layer Encryption Modes</item>
+      <item><url href="http://www.ietf.org/rfc/rfc4716.txt">RFC 4716</url> -
+      Public Key File Format</item>
+    </list>
+  </section>
 </chapter>
diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml
index 55339298e8..afe3f2ddf9 100644
--- a/lib/ssh/doc/src/ref_man.xml
+++ b/lib/ssh/doc/src/ref_man.xml
@@ -28,8 +28,8 @@
     <file>ref_man.xml</file>
   </header>
   <description>
-    <p>The SSH application is an erlang implementation of the
-      secure shell protocol (SSH) as defined by RFC 4250 - 4254</p>
+    <p>The <c>ssh</c> application is an Erlang implementation of the
+      Secure Shell Protocol (SSH) as defined by RFC 4250 - 4254.</p>
 
   </description>
   <xi:include href="ssh_app.xml"/>
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
index 0e7e3848ad..bb41a317e5 100644
--- a/lib/ssh/doc/src/ssh.xml
+++ b/lib/ssh/doc/src/ssh.xml
@@ -22,54 +22,71 @@
     </legalnotice>
     
     <title>ssh</title>
+    <prepared></prepared>
+    <docno></docno>
     <date>2007-10-06</date>
+    <rev></rev>
   </header>
   <module>ssh</module>
-  <modulesummary>Main API of the SSH application</modulesummary>
+  <modulesummary>Main API of the ssh application</modulesummary>
   <description>
-    <p>Interface module for the SSH application. </p>
+    <p>Interface module for the <c>ssh</c> application.</p>
   </description>
 
    <section>
     <title>SSH</title>
 
     <list type="bulleted">
-      <item>SSH requires the crypto and public_key applications.</item>
-      <item>Supported SSH version is 2.0 </item>
-      <item>Supported MAC algorithms: hmac-sha2-256 and hmac-sha1</item>
-      <item>Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc</item>
-      <item>Supports unicode filenames if the emulator and the underlaying OS supports it. See the DESCRIPTION section in <seealso marker="kernel:file">file</seealso> for information about this subject</item>
-      <item>Supports unicode in shell and cli</item>
+      <item>SSH requires the <c>crypto</c> and <c>public_key</c> applications.</item>
+      <item>Supported SSH version is 2.0.</item>
+      <item>Supported MAC algorithms: hmac-sha2-256 and hmac-sha1.</item>
+      <item>Supported encryption algorithms: aes128-ctr, aes128-cb and 3des-cbc.</item>
+      <item>Supports unicode filenames if the emulator and the underlaying OS support it.
+      See section DESCRIPTION in the
+      <seealso marker="kernel:file">file</seealso> manual page in <c>kernel</c>
+      for information about this subject.</item>
+      <item>Supports unicode in shell and CLI.</item>
     </list>
  
   </section>
   
   <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><c>boolean() = true | false </c></p>
-    <p><c>string() = [byte()]</c></p>
-    <p><c>ssh_daemon_ref() - opaque to the user
-    returned by ssh:daemon/[1,2,3]</c></p>
-    <p><c>ssh_connection_ref() - opaque to the user
-    returned by ssh:connect/3</c></p>
-    <p><c>ip_address() - inet::ip_address()</c></p>
-    <p><c>subsystem_spec() = {subsystem_name(),
-    {channel_callback(), channel_init_args()}} </c></p>
-    <p><c>subsystem_name() = string() </c></p>
-    <p><c>channel_callback() = atom() - Name of the erlang module
-    implementing the subsystem using the ssh_channel behavior see</c>
-    <seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
-    <p><c>channel_init_args() = list()</c></p>
- </section>
+    this module, or abstractions to indicate the intended use of the data
+    type, or both:</p>
+    <taglist>
+      <tag><c>boolean()</c></tag>
+      <item><p>= <c>true | false</c></p></item>
+      <tag><c>string()</c></tag>
+      <item><p>= <c>[byte()]</c></p></item>
+      <tag><c>ssh_daemon_ref()</c></tag>
+      <item><p>Opaque to the user,
+    returned by <c>ssh:daemon/[1,2,3]</c></p></item>
+      <tag><c>ssh_connection_ref()</c></tag>
+      <item><p>Opaque to the user,
+    returned by <c>ssh:connect/3</c></p></item>
+      <tag><c>ip_address()</c></tag>
+      <item><p><c>inet::ip_address</c></p></item>
+      <tag><c>subsystem_spec()</c></tag>
+      <item><p>= <c>{subsystem_name(),
+    {channel_callback(), channel_init_args()}}</c></p></item>
+      <tag><c>subsystem_name()</c></tag>
+      <item><p>= <c>string()</c></p></item>
+      <tag><c>channel_callback()</c></tag>
+      <item><p>= <c>atom()</c> - Name of the Erlang module
+    implementing the subsystem using the <c>ssh_channel</c> behavior, see
+    <seealso marker="ssh_channel">ssh_channel(3)</seealso></p></item>
+      <tag><c>channel_init_args()</c></tag>
+      <item><p>= <c>list()</c></p></item>
+     </taglist>
+</section>
 
  <funcs>
    
    <func>
      <name>close(ConnectionRef) -> ok </name>
-      <fsummary>Closes an SSH connection</fsummary>
+      <fsummary>Closes an SSH connection.</fsummary>
       <type>
 	<v>ConnectionRef = ssh_connection_ref()</v>
       </type>
@@ -81,135 +98,141 @@
       <name>connect(Host, Port, Options) -> </name>
       <name>connect(Host, Port, Options, Timeout) -> {ok,
       ssh_connection_ref()} | {error, Reason}</name>
-      <fsummary>Connect to an ssh server.</fsummary>
+      <fsummary>Connects to an SSH server.</fsummary>
       <type>
         <v>Host = string()</v>
 	<v>Port = integer()</v>
-	<d>The default is <c><![CDATA[22]]></c>, the assigned well known port
+	<d><c><![CDATA[22]]></c> is default, the assigned well-known port
 	number for SSH.</d>
 	<v>Options = [{Option, Value}]</v>
 	<v>Timeout = infinity | integer(milliseconds)</v>
-	<d>Negotiation timeout, for connection timeout use the option <c>{connect_timeout, timeout()}</c>.</d>
+	<d>Negotiation time-out. For connection time-out, use option
+	<c>{connect_timeout, timeout()}</c>.</d>
       </type>
       <desc>
 	<p>Connects to an SSH server. No channel is started. This is done
 	by calling
-	<seealso marker="ssh_connection#session_channel/2">ssh_connection:session_channel/[2, 4]</seealso>.</p>
-	<p>Options are:</p>
+	<seealso marker="ssh_connection#session_channel/2">
+	ssh_connection:session_channel/[2, 4]</seealso>.</p>
+	<p>Options:</p>
 	<taglist>
 	  <tag><c><![CDATA[{inet, inet | inet6}]]></c></tag>
-	  <item> IP version to use.</item>
+	  <item>
+	  <p>IP version to use.</p>
+	  </item>
           <tag><c><![CDATA[{user_dir, string()}]]></c></tag>
 	  <item>
-	    <p>Sets the user directory i.e. the directory containing
-	    ssh configuration files for the user such as
+	    <p>Sets the user directory, that is, the directory containing
+	    <c>ssh</c> configuration files for the user, such as
 	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
-	    id_dsa]]></c> and
+	    id_dsa]]></c>, and
 	    <c><![CDATA[authorized_key]]></c>. Defaults to the
 	    directory normally referred to as
-	    <c><![CDATA[~/.ssh]]></c> </p>
+	    <c><![CDATA[~/.ssh]]></c>.</p>
 	  </item>
 	  <tag><c><![CDATA[{dsa_pass_phrase, string()}]]></c></tag>
 	  <item>
-	    <p>If the user dsa key is protected by a passphrase it can be
+	    <p>If the user DSA key is protected by a passphrase, it can be
 	    supplied with this option.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{rsa_pass_phrase, string()}]]></c></tag>
 	  <item>
-	    <p>If the user rsa key is protected by a passphrase it can be
+	    <p>If the user RSA key is protected by a passphrase, it can be
 	    supplied with this option.
 	    </p>
 	  </item>
           <tag><c><![CDATA[{silently_accept_hosts, boolean()}]]></c></tag>
 	  <item>
-	    <p>When true hosts are added to the
+	    <p>When <c>true</c>, hosts are added to the
 	    file <c><![CDATA[known_hosts]]></c> without asking the user.
-	    Defaults to false.
+	    Defaults to <c>false</c>.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{user_interaction, boolean()}]]></c></tag>
 	  <item>
-	    <p>If false disables the client to connect to the server
-	    if any user interaction is needed such as accepting that
-	    the server will be added to the <c>known_hosts</c> file or
-	    supplying a password. Defaults to true.
+	    <p>If <c>false</c>, disables the client to connect to the server
+	    if any user interaction is needed, such as accepting
+	    the server to be added to the <c>known_hosts</c> file, or
+	    supplying a password. Defaults to <c>true</c>.
 	    Even if user interaction is allowed it can be
-	    suppressed by other options such as silently_accept_hosts and
-	    password. Do note that it may not always be desirable to use
-	    those options from a security point of view.</p>
+	    suppressed by other options, such as <c>silently_accept_hosts</c>
+	    and <c>password</c>. However, those optins are not always desirable
+	    to use from a security point of view.</p>
 	  </item>
 	  <tag><c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></tag>
 	  <item>
             <p>Sets the preferred public key algorithm to use for user
-	    authentication. If the the preferred algorithm fails for
-	    some reason, the other algorithm is tried. The  default is
+	    authentication. If the preferred algorithm fails,
+	    the other algorithm is tried. The default is
 	    to try <c><![CDATA['ssh-rsa']]></c> first.</p>
 	  </item>
 	  <tag><c><![CDATA[{pref_public_key_algs, list()}]]></c></tag>
 	  <item>
-            <p>List of public key algorithms to try to use, 'ssh-rsa' and 'ssh-dss' available. 
-	    Will override <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p>
+            <p>List of public key algorithms to try to use.
+	    <c>'ssh-rsa'</c> and <c>'ssh-dss'</c> are available.
+	    Overrides <c><![CDATA[{public_key_alg, 'ssh-rsa' | 'ssh-dss'}]]></c></p>
 	  </item>
 	  <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag>
 	  <item>
-	    <p>Sets a timeout on the transport layer
+	    <p>Sets a time-out on the transport layer
 	    connection. Defaults to <c>infinity</c>.</p>
 	  </item>
 	  <tag><c><![CDATA[{user, string()}]]></c></tag>
           <item>
-	    <p>Provides a user name. If this option is not given, ssh
+	    <p>Provides a username. If this option is not given, <c>ssh</c>
 	    reads from the environment (<c><![CDATA[LOGNAME]]></c> or
-	    <c><![CDATA[USER]]></c> on unix,
+	    <c><![CDATA[USER]]></c> on UNIX,
 	    <c><![CDATA[USERNAME]]></c> on Windows).</p>
           </item>
 	  <tag><c><![CDATA[{password, string()}]]></c></tag>
           <item>
-	    <p>Provide a password for password authentication.  If
-	    this option is not given, the user will be asked for a
-	    password if the password authentication method is
+	    <p>Provides a password for password authentication.
+	    If this option is not given, the user is asked for a
+	    password, if the password authentication method is
 	    attempted.</p>
           </item>
 	  <tag><c><![CDATA[{key_cb, atom()}]]></c></tag>
 	  <item>
-	    <p>Module implementing the behaviour <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>.
+	    <p>Module implementing the behaviour
+	    <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso>.
 	    Can be used to customize the handling of public keys.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{quiet_mode, atom() = boolean()}]]></c></tag>
 	  <item>
-	    <p>If true, the client will not print out anything on authorization.</p>
+	    <p>If <c>true</c>, the client does not print anything on authorization.</p>
 	  </item>
 	  <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
 	  <item>
-	    <p>Allow an existing file descriptor to be used
-	  (simply passed on to the transport protocol).</p></item>
+	    <p>Allows an existing file descriptor to be used
+	  (by passing it on to the transport protocol).</p></item>
 	  <tag><c><![CDATA[{rekey_limit, integer()}]]></c></tag>
 	  <item>
-	    <p>Provide, in bytes, when rekeying should be initiated, 
-	    defaults to one time each GB and one time per hour.</p>
+	    <p>Provides, in bytes, when rekeying is to be initiated.
+	    Defaults to once per each GB and once per hour.</p>
 	  </item>
 	  <tag><c><![CDATA[{idle_time, integer()}]]></c></tag>
 	  <item>
- 	  <p>Sets a timeout on connection when no channels are active, default is infinity</p></item>
+	  <p>Sets a time-out on a connection when no channels are active.
+	  Defaults to <c>infinity</c>.</p></item>
 	</taglist>
       </desc>   
     </func>
 
     <func>
       <name>connection_info(ConnectionRef, [Option]) ->[{Option,
-      Value}] </name>
-      <fsummary> Retrieves information about a connection. </fsummary>
+      Value}]</name>
+      <fsummary>Retrieves information about a connection.</fsummary>
       <type>
         <v>Option = client_version | server_version | user | peer | sockname </v>
 	<v>Value = [option_value()] </v>
-	<v>option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} | User::string() |
-	Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} |
+	<v>option_value() = {{Major::integer(), Minor::integer()}, VersionString::string()} |
+	User::string() |  Peer::{inet:hostname(), {inet::ip_adress(), inet::port_number()}} |
 	Sockname::{inet::ip_adress(), inet::port_number()} () </v>
       </type>
       <desc>
-        <p> Retrieves information about a connection. 
-	</p>
+        <p>Retrieves information about a connection.</p>
       </desc>
     </func>
     
@@ -230,111 +253,127 @@
       <desc>
         <p>Starts a server listening for SSH connections on the given
         port.</p>
-	<p>Options are:</p>
+	<p>Options:</p>
         <taglist>
 	  <tag><c><![CDATA[{inet, inet | inet6}]]></c></tag>
-	  <item> IP version to use when the host address is specified as <c>any</c>. </item>
+	  <item><p>IP version to use when the host address is specified as <c>any</c>.</p></item>
 	  <tag><c><![CDATA[{subsystems, [subsystem_spec()]}]]></c></tag>
 	  <item>
-	    Provides specifications for handling of subsystems. The
-	    "sftp" subsystem spec can be retrieved by calling
-	    ssh_sftpd:subsystem_spec/1. If the subsystems option is
-	    not present the value of
-	    <c>[ssh_sftpd:subsystem_spec([])]</c> will be used.  It is
-	    of course possible to set the option to the empty list if
-	    you do not want the daemon to run any subsystems at all.
+	    <p>Provides specifications for handling of subsystems. The
+	    "sftp" subsystem specification is retrieved by calling
+	    <c>ssh_sftpd:subsystem_spec/1</c>. If the subsystems option is
+	    not present, the value of
+	    <c>[ssh_sftpd:subsystem_spec([])]</c> is used.
+	    The option can be set to the empty list if
+	    you do not want the daemon to run any subsystems.</p>
 	  </item>
 	  <tag><c><![CDATA[{shell, {Module, Function, Args} |
 	  fun(string() = User) - > pid() | fun(string() = User,
 	  ip_address() = PeerAddr) -> pid()}]]></c></tag>
 	  <item>
-	    Defines the read-eval-print loop used when a shell is
-	    requested by the client. Default is to use the erlang shell:
-	    <c><![CDATA[{shell, start, []}]]></c>
+	    <p>Defines the read-eval-print loop used when a shell is
+	    requested by the client. The default is to use the Erlang shell:
+	    <c><![CDATA[{shell, start, []}]]></c></p>
 	  </item>
 	  <tag><c><![CDATA[{ssh_cli, {channel_callback(),
 	  channel_init_args()} | no_cli}]]></c></tag>
 	  <item>
-	    Provides your own CLI implementation, i.e. a channel callback
-	    module that implements a shell and command execution. Note
-	    that you may customize the shell read-eval-print loop using the
-	    option <c>shell</c> which is much less work than implementing
-	    your own CLI channel. If set to  <c>no_cli</c> you will disable
-	    CLI channels and only subsystem channels will be allowed.
+	    <p>Provides your own CLI implementation, that is, a channel callback
+	    module that implements a shell and command execution. The shell
+	    read-eval-print loop can be customized, using the
+	    option <c>shell</c>. This means less work than implementing
+	    an own CLI channel. If set to <c>no_cli</c>, the CLI channels
+	    are disabled and only subsystem channels are allowed.</p>
 	  </item>
 	  <tag><c><![CDATA[{user_dir, String}]]></c></tag>
 	  <item>
-	    <p>Sets the user directory i.e. the directory containing
-	    ssh configuration files for the user such as
+	    <p>Sets the user directory. That is, the directory containing
+	    <c>ssh</c> configuration files for the user, such as
 	    <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa,
-	    id_dsa]]></c> and
+	    id_dsa]]></c>, and
 	    <c><![CDATA[authorized_key]]></c>. Defaults to the
 	    directory normally referred to as
-	    <c><![CDATA[~/.ssh]]></c> </p>
+	    <c><![CDATA[~/.ssh]]></c>.</p>
 	  </item>
           <tag><c><![CDATA[{system_dir, string()}]]></c></tag>
           <item>
             <p>Sets the system directory, containing the host key files
-            that identifies the host keys for ssh. The default is
-            <c><![CDATA[/etc/ssh]]></c>, note that for security reasons
-            this directory is normally only accessible by the root user.</p>
+            that identify the host keys for <c>ssh</c>. Defaults to
+            <c><![CDATA[/etc/ssh]]></c>. For security reasons,
+            this directory is normally accessible only to the root user.</p>
 	  </item>
 	  <tag><c><![CDATA[{auth_methods, string()}]]></c></tag>
 	  <item>
-	    <p>Comma separated string that determines which
-	    authentication methodes that the server should support and
-	    in what order they will be tried. Defaults to
+	    <p>Comma-separated string that determines which
+	    authentication methods that the server is to support and
+	    in what order they are tried. Defaults to
 	    <c><![CDATA["publickey,keyboard-interactive,password"]]></c></p>
           </item>
 	  <tag><c><![CDATA[{user_passwords, [{string() = User,
 	  string() = Password}]}]]></c></tag>
 	  <item>
-            <p>Provide passwords for password authentication.They will
-	    be used when someone tries to connect to the server and
-	    public key user authentication fails. The option provides
-	    a list of valid user names and the corresponding password.
+            <p>Provides passwords for password authentication. The passwords
+	    are used when someone tries to connect to the server and
+	    public key user-authentication fails. The option provides
+	    a list of valid usernames and the corresponding passwords.
 	    </p>
           </item>
           <tag><c><![CDATA[{password, string()}]]></c></tag>
           <item>
-            <p>Provide a global password that will authenticate any
+            <p>Provides a global password that authenticates any
               user. From a security perspective this option makes
 	      the server very vulnerable.</p>
 	  </item>
 	  <tag><c><![CDATA[{pwdfun, fun(User::string(), password::string()) -> boolean()}]]></c></tag>
 	  <item>
-	    <p>Provide a function for password validation. This is called
-	      with user and password as strings, and should return
+	    <p>Provides a function for password validation. This function is called
+	      with user and password as strings, and returns
 	      <c><![CDATA[true]]></c> if the password is valid and
 	      <c><![CDATA[false]]></c> otherwise.</p>
 	  </item>
 
 	  <tag><c><![CDATA[{negotiation_timeout, integer()}]]></c></tag>
 	  <item>
-	    <p>Max time in milliseconds for the authentication negotiation.  The default value is 2 minutes. If the client fails to login within this time, the connection is closed.
+	    <p>Maximum time in milliseconds for the authentication negotiation.
+	    Defaults to 120000 (2 minutes). If the client fails to log in within this time,
+	    the connection is closed.
 	    </p>
 	  </item>
 
 	  <tag><c><![CDATA[{max_sessions, pos_integer()}]]></c></tag>
 	  <item>
-	    <p>The maximum number of simultaneous sessions that are accepted at any time for this daemon.  This includes sessions that are being authorized.  So if set to <c>N</c>, and <c>N</c> clients have connected but not started the login process, the <c>N+1</c> connection attempt will be aborted.  If <c>N</c> connections are authenticated and still logged in, no more loggins will be accepted until one of the existing ones log out.
+	    <p>The maximum number of simultaneous sessions that are accepted at any time
+	    for this daemon. This includes sessions that are being authorized.
+	    Thus, if set to <c>N</c>, and <c>N</c> clients have connected but not started
+	    the login process, connection attempt <c>N+1</c> is aborted.
+	    If <c>N</c> connections are authenticated and still logged in, no more logins
+	    are accepted until one of the existing ones log out.
 	    </p>
-	    <p>The counter is per listening port, so if two daemons are started, one with <c>{max_sessions,N}</c> and the other with <c>{max_sessions,M}</c> there will be in total <c>N+M</c> connections accepted for the whole ssh application.
+	    <p>The counter is per listening port. Thus, if two daemons are started, one with
+	    <c>{max_sessions,N}</c> and the other with <c>{max_sessions,M}</c>, in total
+	    <c>N+M</c> connections are accepted for the whole <c>ssh</c> application.
 	    </p>
-	    <p>Note that if <c>parallel_login</c> is <c>false</c>, only one client at a time may be in the authentication phase.
+	    <p>Notice that if <c>parallel_login</c> is <c>false</c>, only one client
+	    at a time can be in the authentication phase.
 	    </p>
-	    <p>As default, the option is not set. This means that the number is not limited.
+	    <p>By default, this option is not set. This means that the number is not limited.
 	    </p>
 	  </item>
 
 	  <tag><c><![CDATA[{parallel_login, boolean()}]]></c></tag>
 	  <item>
-	    <p>If set to false (the default value), only one login is handled a time.  If set to true, an unlimited number of login attempts will be allowed simultanously.
+	    <p>If set to false (the default value), only one login is handled at a time.
+	    If set to true, an unlimited number of login attempts are allowed simultaneously.
 	    </p>
-	    <p>If the <c>max_sessions</c> option is set to <c>N</c> and <c>parallel_login</c> is set to <c>true</c>, the max number of simultaneous login attempts at any time is limited to <c>N-K</c> where <c>K</c> is the number of authenticated connections present at this daemon.
+	    <p>If the <c>max_sessions</c> option is set to <c>N</c> and <c>parallel_login</c>
+	    is set to <c>true</c>, the maximum number of simultaneous login attempts at any time is
+	    limited to <c>N-K</c>, where <c>K</c> is the number of authenticated connections present
+	    at this daemon.
 	    </p>
 	    <warning>
-	      <p>Do not enable <c>parallel_logins</c> without protecting the server by other means, for example the <c>max_sessions</c> option or a firewall configuration. If set to <c>true</c>, there is no protection against DOS attacks.</p>
+	      <p>Do not enable <c>parallel_logins</c> without protecting the server by other means,
+	      for example, by the <c>max_sessions</c> option or a firewall configuration. If set to
+	      <c>true</c>, there is no protection against DOS attacks.</p>
 	    </warning>
 	  </item>
 
@@ -346,25 +385,28 @@
 
 	  <tag><c><![CDATA[{key_cb, atom()}]]></c></tag>
 	  <item>
-	    <p>Module implementing the behaviour <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
+	    <p>Module implementing the behaviour
+	    <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
 	    Can be used to customize the handling of public keys.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
 	  <item>
-	    <p>Allow an existing file-descriptor to be used
-	  (simply passed on to the transport protocol).</p></item>
-	  <tag><c><![CDATA[{failfun, fun(User::string(), PeerAddress::ip_address(), Reason::term()) -> _}]]></c></tag>
+	    <p>Allows an existing file-descriptor to be used
+	  (passed on to the transport protocol).</p></item>
+	  <tag><c><![CDATA[{failfun, fun(User::string(),
+	  PeerAddress::ip_address(), Reason::term()) -> _}]]></c></tag>
 	  <item>
-	    <p>Provide a fun to implement your own logging when a user fails to authenticate.</p>
+	    <p>Provides a fun to implement your own logging when a user fails to authenticate.</p>
 	  </item>
-	  <tag><c><![CDATA[{connectfun, fun(User::string(), PeerAddress::ip_address(), Method::string()) ->_}]]></c></tag>
+	  <tag><c><![CDATA[{connectfun, fun(User::string(), PeerAddress::ip_address(),
+	  Method::string()) ->_}]]></c></tag>
 	  <item>
-	    <p>Provide a fun to implement your own logging when a user authenticates to the server.</p>
+	    <p>Provides a fun to implement your own logging when a user authenticates to the server.</p>
 	  </item>
 	  <tag><c><![CDATA[{disconnectfun, fun(Reason:term()) -> _}]]></c></tag>
 	  <item>
-	    <p>Provide a fun to implement your own logging when a user disconnects from the server.</p>
+	    <p>Provides a fun to implement your own logging when a user disconnects from the server.</p>
 	  </item>
         </taglist>
       </desc>
@@ -375,16 +417,16 @@
       <name>shell(Host) -> </name>
       <name>shell(Host, Option) -> </name>
       <name>shell(Host, Port, Option) -> _</name>
-      <fsummary> </fsummary>
+      <fsummary>Starts an interactive shell over an SSH server.</fsummary>
       <type>
-        <v> Host = string()</v>
-	<v> Port = integer()</v>
-	<v> Options - see ssh:connect/3</v>
+        <v>Host = string()</v>
+	<v>Port = integer()</v>
+	<v>Options - see ssh:connect/3</v>
       </type>
       <desc>
-        <p>Starts an interactive shell via an SSH server on the
+        <p>Starts an interactive shell over an SSH server on the
 	given <c>Host</c>. The function waits for user input,
-	and will not return until the remote shell is ended (i.e.
+	and does not return until the remote shell is ended (that is,
 	exit from the shell).
 	</p>
       </desc>
@@ -393,28 +435,29 @@
     <func>
       <name>start() -> </name>
       <name>start(Type) -> ok | {error, Reason}</name>
-      <fsummary>Starts the SSH application. </fsummary>
+      <fsummary>Starts the SSH application.</fsummary>
       <type>
         <v>Type =  permanent | transient | temporary</v>
 	<v>Reason = term() </v>
       </type>
       <desc>
-        <p>Utility function that starts crypto, public_key and the SSH
-	application. Defult type is temporary.
-	See also <seealso marker="kernel:application">application(3)</seealso>
-	</p>
+        <p>Utility function that starts the applications <c>crypto</c>, <c>public_key</c>,
+	and <c>ssh</c>. Default type is <c>temporary</c>.
+	For more information, see the <seealso marker="kernel:application">application(3)</seealso>
+	manual page in <c>kernel</c>.</p>
       </desc>
     </func>
 
     <func>
       <name>stop() -> ok | {error, Reason}</name>
-      <fsummary>Stops the SSH application.</fsummary>
+      <fsummary>Stops the <c>ssh</c> application.</fsummary>
       <type>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Stops the SSH application. See also
-          <seealso marker="kernel:application">application(3)</seealso></p>
+        <p>Stops the <c>ssh</c> application.
+	For more information, see the <seealso marker="kernel:application">application(3)</seealso>
+	manual page in <c>kernel</c>.</p>
       </desc>
     </func>
     
@@ -438,7 +481,7 @@
       <name>stop_listener(DaemonRef) -> </name>
       <name>stop_listener(Address, Port) -> ok </name>
       <fsummary>Stops the listener, but leaves existing connections started
-	by the listener up and running.</fsummary>
+	by the listener operational.</fsummary>
       <type>
 	<v>DaemonRef = ssh_daemon_ref()</v>
         <v>Address = ip_address()</v>
@@ -446,7 +489,7 @@
       </type>
       <desc>
 	<p>Stops the listener, but leaves existing connections started
-	by the listener up and running.</p>
+	by the listener operational.</p>
       </desc>
     </func>
 
diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml
index a1d2402790..498565057f 100644
--- a/lib/ssh/doc/src/ssh_app.xml
+++ b/lib/ssh/doc/src/ssh_app.xml
@@ -18,78 +18,98 @@
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-
     </legalnotice>
 
     <title>SSH</title>
+    <prepared></prepared>
+    <docno></docno>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
     <file>ssh_app.xml</file>
   </header>
   <app>SSH</app>
-  <appsummary>The ssh application implements the SSH (Secure Shell) protocol and
-  provides an SFTP (SSH File Transfer Protocol) client and server. </appsummary>
+  <appsummary>The ssh application implements the Secure Shell (SSH) protocol and
+  provides an SSH File Transfer Protocol (SFTP) client and server.</appsummary>
+  <description>
+    <p>The <c>ssh</c> application is an implementation of the SSH protocol in Erlang.
+    <c>ssh</c> offers API functions to write customized SSH clients and servers as well as
+    making the Erlang shell available over SSH. An SFTP client, <c>ssh_sftp</c>, and server,
+    <c>ssh_sftpd</c>, are also included.</p>
+  </description>
 
-  <section>
+   <section>
     <title>DEPENDENCIES</title>
-    <p>The ssh application uses the Erlang applications public_key and
-    crypto to handle public keys and encryption, hence these
-    applications needs to be loaded for the ssh application to work. In
-    an embedded environment that means they need to be started with
-    application:start/[1,2] before the ssh application is started.
+    <p>The <c>ssh</c> application uses the applications <c>public_key</c> and
+    <c>crypto</c> to handle public keys and encryption. Hence, these
+    applications must be loaded for the <c>ssh</c> application to work. In
+    an embedded environment this means that they must be started with
+    <c>application:start/[1,2]</c> before the <c>ssh</c> application is started.
     </p>
   </section>
 
   <section>
     <title>CONFIGURATION</title>
 
-    <p>The ssh application does not currently have an application
-    specific configuration file as described in application(3),
-    however it will by default use the following configuration files
-    from openssh: known_hosts, authorized_keys, authorized_keys2,
-    id_dsa and id_rsa, ssh_host_dsa_key and ssh_host_rsa_key.  By
-    default Erlang SSH will look for id_dsa, id_rsa, known_hosts
-    and authorized_keys in ~/.ssh, and the host key files in /etc/ssh
-    . These locations may be changed by the options user_dir and
-    system_dir.  Public key handling may also be customized by
-    providing a callback module implementing the behaviors
-    <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and
-    <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
-    </p>
+    <p>The <c>ssh</c> application does not have an application-
+    specific configuration file, as described in application(3).
+    However, by default it use the following configuration files
+    from OpenSSH:</p>
+    <list type="bulleted">
+      <item><c>known_hosts</c></item>
+      <item><c>authorized_keys</c></item>
+      <item><c>authorized_keys2</c></item>
+      <item><c>id_dsa</c></item>
+      <item><c>id_rsa</c></item>
+      <item><c>ssh_host_dsa_key</c></item>
+      <item><c>ssh_host_rsa_key</c></item>
+    </list>
+      <p>By default, <c>ssh</c> looks for <c>id_dsa</c>, <c>id_rsa</c>,
+      <c>known_hosts</c>, and <c>authorized_keys</c> in ~/.ssh,
+      and for the host key files in <c>/etc/ssh</c>. These locations can be changed
+      by the options <c>user_dir</c> and <c>system_dir</c>.
+      </p>
+      <p>Public key handling can also be customized through a callback module that
+      implements the behaviors
+      <seealso marker="ssh_client_key_api">ssh_client_key_api</seealso> and
+      <seealso marker="ssh_server_key_api">ssh_server_key_api</seealso>.
+      </p>
 
-    <section>
-      <title>PUBLIC KEYS</title>
-      <p>
-	id_dsa and id_rsa are the users private key files, note that
-	the public key is part of the private key so the ssh
-	application will not use the id_&lt;*>.pub files. These are
-	for the users convenience when he/she needs to convey their
+  </section>
+  <section>
+    <title>Public Keys</title>
+    <p><c>id_dsa</c> and <c>id_rsa</c> are the users private key files.
+	Notice that the public key is part of the private key so the <c>ssh</c>
+	application does not use the <c>id_&lt;*>.pub</c> files. These are
+	for the user's convenience when it is needed to convey the user's
 	public key.
       </p>
-    </section>
-
-    <section>
-      <title>KNOW HOSTS</title>
-      <p>The known_hosts file contains a list of approved servers and
-      their public keys.  Once a server is listed, it can be verified
+  </section>
+ <section>
+    <title>Known Hosts</title>
+    <p>The <c>known_hosts</c> file contains a list of approved servers and
+      their public keys. Once a server is listed, it can be verified
       without user interaction.
       </p>
-     </section>
-
-     <section>
-      <title>AUTHORIZED KEYS</title>
-      <p>The authorized key file keeps track of the user's authorized
+  </section>
+ <section>
+    <title>Authorized Keys</title>
+    <p>The <c>authorized_key</c> file keeps track of the user's authorized
       public keys. The most common use of this file is to let users
-      log in without entering their password which is supported by the
-      Erlang SSH daemon.
+      log in without entering their password, which is supported by the
+      Erlang <c>ssh</c> daemon.
       </p>
-     </section>
-
-     <section>
-       <title>HOST KEYS</title>
-       <p>Currently rsa and dsa host keys are supported and are
-       expected to be found in files named ssh_host_rsa_key and
-       ssh_host_dsa_key.
+  </section>
+ <section>
+    <title>Host Keys</title>
+    <p>RSA and DSA host keys are supported and are
+       expected to be found in files named <c>ssh_host_rsa_key</c> and
+       <c>ssh_host_dsa_key</c>.
        </p>
-     </section>
+  </section>
+  <section>
+    <title>ERROR LOGGER AND EVENT HANDLERS</title>
+    <p>The <c>ssh</c> application has no error logger or event handlers.</p>
   </section>
 
   <section>
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>
diff --git a/lib/ssh/doc/src/ssh_client_key_api.xml b/lib/ssh/doc/src/ssh_client_key_api.xml
index f3d05a8980..c3c005c58c 100644
--- a/lib/ssh/doc/src/ssh_client_key_api.xml
+++ b/lib/ssh/doc/src/ssh_client_key_api.xml
@@ -23,102 +23,112 @@
       The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
     <title>ssh_client_key_api</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
   </header>
   <module>ssh_client_key_api</module>
   <modulesummary>
      -behaviour(ssh_client_key_api).
   </modulesummary>
   <description>
-    <p> Behavior describing the API for an SSH client's public key handling.
-      By implementing the callbacks defined.
-    in this behavior it is possible to customize the SSH client's public key
-    handling. By default the SSH application implements this behavior
-    with help of the standard openssh files, see <seealso marker="SSH_app"> ssh(6)</seealso>. </p>
+    <p>Behavior describing the API for public key handling of an SSH client. By implementing
+    the callbacks defined in this behavior, the public key handling of an SSH client can
+    be customized. By default the <c>ssh</c> application implements this behavior
+    with help of the standard OpenSSH files,
+    see the <seealso marker="SSH_app"> ssh(6)</seealso> application.</p>
   </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. For more details on public key data types 
-    see the <seealso marker="public_key:public_key_records"> public_key user's guide.</seealso>
+    <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. For more details on public key data types,
+    refer to Section 2 Public Key Records in the
+    <seealso marker="public_key:public_key_records"> public_key user's guide:</seealso>
     </p>
-
-    <p> boolean() = true | false</p>
-    <p> string() =  [byte()] </p>
-    <p> public_key() =  #'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</p>
-    <p> private_key() =  #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</p>
-    <p> public_key_algorithm() =  'ssh-rsa'| 'ssh-dss' | atom()</p>
-
+    <taglist>
+      <tag><c>boolean()</c></tag>
+      <item><p>= <c>true | false</c></p></item>
+      <tag><c>string()</c></tag>
+      <item><p>= <c>[byte()]</c></p></item>
+      <tag><c>public_key()</c></tag>
+      <item><p>= <c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item>
+      <tag><c>private_key()</c></tag>
+      <item><p>= <c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item>
+      <tag><c>public_key_algorithm()</c></tag>
+      <item><p>= <c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item>
+    </taglist>
   </section>
 
   <funcs>
     <func>
       <name>Module:add_host_key(HostNames, Key, ConnectOptions) -> ok | {error, Reason}</name>
-      <fsummary>Adds a host key to the set of trusted host keys</fsummary>
+      <fsummary>Adds a host key to the set of trusted host keys.</fsummary>
       <type>
       <v>HostNames = string()</v>
-      <d>Description of the host that owns the <c>PublicKey</c></d>
+      <d>Description of the host that owns the <c>PublicKey</c>.</d>
 
-      <v>Key = public_key() </v>
-      <d> Normally an RSA or DSA public key but handling of other public keys can be added</d>
+      <v>Key = public_key()</v>
+      <d>Normally an RSA or DSA public key, but handling of other public keys can be added.</d>
 
-      <v>ConnectOptions = proplists:proplist() </v>
-      <d>Options provided to  <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso></d>
-      <v>Reason = term() </v>
+      <v>ConnectOptions = proplists:proplist()</v>
+      <d>Options provided to <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso></d>
+      <v>Reason = term().</v>
       </type>
       <desc>
-	 <p> Adds a host key to the set of trusted host keys</p>
+	 <p>Adds a host key to the set of trusted host keys.</p>
       </desc>
     </func>
 
     <func>
       <name>Module:is_host_key(Key, Host, Algorithm, ConnectOptions) -> Result</name>
-      <fsummary>Checks if a host key is trusted</fsummary>
+      <fsummary>Checks if a host key is trusted.</fsummary>
       <type>
 	<v>Key = public_key() </v>
-	<d> Normally an RSA or DSA public key but handling of other public keys can be added</d>
+	<d>Normally an RSA or DSA public key, but handling of other public keys can be added.</d>
 
 	<v>Host = string()</v>
-	<d>Description of the host</d>
+	<d>Description of the host.</d>
 
 	<v>Algorithm = public_key_algorithm()</v>
-	<d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms
+	<d>Host key algorithm. Is to support <c>'ssh-rsa'| 'ssh-dss'</c>, but more algorithms
 	can be handled.</d>
 
-	<v> ConnectOptions = proplists:proplist() </v>
-	<d>Options provided to  <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso></d>
+	<v>ConnectOptions = proplists:proplist() </v>
+	<d>Options provided to <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso>.</d>
 
-	<v> Result = boolean()</v>
+	<v>Result = boolean()</v>
       </type>
       <desc>
-	<p>Checks if a host key is trusted</p>
+	<p>Checks if a host key is trusted.</p>
       </desc>
     </func>
 
     <func>
       <name>Module:user_key(Algorithm, ConnectOptions) ->
       {ok,  PrivateKey}  | {error, Reason}</name>
-      <fsummary>Fetches the users "public key" matching the <c>Algorithm</c>.</fsummary>
+      <fsummary>Fetches the users <em>public key</em> matching the <c>Algorithm</c>.</fsummary>
       <type>
 	<v>Algorithm = public_key_algorithm()</v>
-	<d> Host key algorithm. Should support 'ssh-rsa'| 'ssh-dss' but additional algorithms
+	<d>Host key algorithm. Is to support <c>'ssh-rsa'| 'ssh-dss'</c> but more algorithms
 	can be handled.</d>
 
-	<v> ConnectOptions = proplists:proplist() </v>
-	<d>Options provided to  <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso></d>
+	<v>ConnectOptions = proplists:proplist()</v>
+	<d>Options provided to <seealso marker="ssh#connect-3">ssh:connect/[3,4]</seealso></d>
 
-	<v> PrivateKey = private_key()</v>
-	<d> The private key of the user matching the <c>Algorithm</c></d>
+	<v>PrivateKey = private_key()</v>
+	<d>Private key of the user matching the <c>Algorithm</c>.</d>
 
-	<v>Reason = term() </v>
+	<v>Reason = term()</v>
       </type>
 
       <desc>
-	<p>Fetches the users "public key" matching the <c>Algorithm</c>.
-	<note><p>The private key contains the public key</p></note>
-	</p>
+	<p>Fetches the users <em>public key</em> matching the <c>Algorithm</c>.</p>
+	<note><p>The private key contains the public key.</p></note>
+
       </desc>
     </func>
 
diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
index 5e2926dfa6..2ca1060e9e 100644
--- a/lib/ssh/doc/src/ssh_connection.xml
+++ b/lib/ssh/doc/src/ssh_connection.xml
@@ -24,156 +24,174 @@
     </legalnotice>
 
     <title>ssh_connection</title>
+    <prepared></prepared>
+    <docno></docno>
     <date></date>
+    <rev></rev>
   </header>
   <module>ssh_connection</module>
-  <modulesummary>This module provides API functions to send <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH Connection Protocol </url>
+  <modulesummary>This module provides API functions to send
+  <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH Connection Protocol </url>
   events to the other side of an SSH channel.
   </modulesummary>
 
   <description>
-    <p>The SSH Connection Protocol is used by clients and servers
-    (i.e. SSH channels) to communicate over the SSH connection. The
-    API functions in this module sends SSH Connection Protocol events
-    that are received as messages by the remote channel.
-    In the case that the receiving channel is an Erlang process the
-    message will be on the following format
-    <c><![CDATA[{ssh_cm, ssh_connection_ref(), ssh_event_msg()}]]></c>. If the <seealso
-    marker="ssh_channel">ssh_channel</seealso> behavior is used to
-    implement the channel process these will be handled by
-    <seealso
-	marker="ssh_channel#Module:handle_ssh_msg-2">handle_ssh_msg/2 </seealso>.</p>
+    <p>The SSH Connection Protocol is used by clients and servers,
+    that is, SSH channels, to communicate over the SSH connection. The
+    API functions in this module send SSH Connection Protocol events,
+    which are received as messages by the remote channel.
+    If the receiving channel is an Erlang process, the
+    messages have the format
+    <c><![CDATA[{ssh_cm, ssh_connection_ref(), ssh_event_msg()}]]></c>.
+    If the <seealso marker="ssh_channel">ssh_channel</seealso> behavior is used to
+    implement the channel process, these messages are handled by
+    <seealso marker="ssh_channel#Module:handle_ssh_msg-2">handle_ssh_msg/2</seealso>.</p>
   </description>
 
   <section>
-    <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><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 processes</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</c> <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254  </url> section 5.2.</p>
-    <p><c>ssh_request_status() = success | failure</c></p>
-    <p><c>event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()} </c></p>
-    <p><c>ssh_event_msg()  = data_events() | status_events() | terminal_events() </c></p>
-    <p><c>reason() = timeout | closed  </c></p>
+    <title>DATA TYPES</title>
+
+    <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>
+
+    <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 processes</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
+      valid values, see
+      <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> Section 5.2.</p></item>
+      <tag><c>ssh_request_status() ssh_request_status()</c></tag>
+      <item><p>= <c>success | failure</c></p></item>
+      <tag><c>event()</c></tag>
+      <item><p>= <c>{ssh_cm, ssh_connection_ref(), ssh_event_msg()}</c></p></item>
+      <tag><c>ssh_event_msg()</c></tag>
+      <item><p>= <c>data_events() | status_events() | terminal_events()</c></p></item>
+      <tag><c>reason()</c></tag>
+      <item><p>= <c>timeout | closed</c></p></item>
+    </taglist>
 
     <taglist>
-      <tag><b>data_events()</b></tag>
+      <tag><em>data_events()</em></tag>
        <item>
 	 <taglist>
 	   <tag><c><![CDATA[{data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}]]></c></tag>
-	   <item> Data has arrived on the channel. This event is sent as
-	   result of calling <seealso marker="ssh_connection#send-3"> ssh_connection:send/[3,4,5] </seealso></item>
+	   <item><p>Data has arrived on the channel. This event is sent as a
+	   result of calling <seealso marker="ssh_connection#send-3">
+	   ssh_connection:send/[3,4,5]</seealso>.</p></item>
 
 	   <tag><c><![CDATA[{eof, ssh_channel_id()}]]></c></tag>
-	   <item>Indicates that the other side will not send any more
-	   data. This event is sent as result of calling <seealso
-	   marker="ssh_connection#send_eof-2"> ssh_connection:send_eof/2</seealso>
-	   </item>
+	   <item><p>Indicates that the other side sends no more data.
+	   This event is sent as a result of calling <seealso
+	   marker="ssh_connection#send_eof-2"> ssh_connection:send_eof/2</seealso>.
+	   </p></item>
 	 </taglist>
        </item>
 
-       <tag><b>status_events()</b></tag>
+       <tag><em>status_events()</em></tag>
        <item>
 
       <taglist>
 	<tag><c><![CDATA[{signal, ssh_channel_id(), ssh_signal()}]]></c></tag>
-	<item>A signal can be delivered to the remote process/service
-	using the following message. Some systems will not support
-	signals, in which case they should ignore this message. There is
-	currently no funtion to generate this event as the signals
-	refered to are on OS-level and not something generated by an
-	Erlang program.</item>
+	<item><p>A signal can be delivered to the remote process/service
+	using the following message. Some systems do not support
+	signals, in which case they are to ignore this message. There is
+	currently no function to generate this event as the signals
+	referred to are on OS-level and not something generated by an
+	Erlang program.</p></item>
 
 	<tag><c><![CDATA[{exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg,
 	string() = LanguageString}]]></c></tag>
 
-	<item>A remote execution may terminate violently due to a signal
-	then this message may be received. For details on valid string
-	values see  <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url> section 6.10. Special case of the signals
-	mentioned above.</item>
+	<item><p>A remote execution can terminate violently because of a signal.
+	Then this message can be received. For details on valid string
+	values, see <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>
+	Section 6.10, which shows a special case of these signals.</p></item>
 
 	<tag><c><![CDATA[{exit_status, ssh_channel_id(), integer() = ExitStatus}]]></c></tag>
-	<item> When the command running at the other end terminates, the
+	<item><p>When the command running at the other end terminates, the
 	following message can be sent to return the exit status of the
-	command. A zero 'exit_status' usually means that the command
-	terminated successfully. This event is sent as result of calling
+	command. A zero <c>exit_status</c> usually means that the command
+	terminated successfully. This event is sent as a result of calling
 	<seealso marker="ssh_connection#exit_status-3">
-	ssh_connection:exit_status/3</seealso></item>
+	ssh_connection:exit_status/3</seealso>.</p></item>
 
 	<tag><c><![CDATA[{closed, ssh_channel_id()}]]></c></tag>
-	<item> This event is sent as result of calling
-	<seealso marker="ssh_connection#close-2">ssh_connection:close/2</seealso> Both the handling of this
-	event and sending of it will be taken care of by the
-	<seealso marker="ssh_channel">ssh_channel</seealso> behavior.</item>
+	<item><p>This event is sent as a result of calling
+	<seealso marker="ssh_connection#close-2">ssh_connection:close/2</seealso>.
+	Both the handling of this event and sending it are taken care of by the
+	<seealso marker="ssh_channel">ssh_channel</seealso> behavior.</p></item>
 
       </taglist>
      </item>
 
-     <tag><b>terminal_events()</b></tag>
+     <tag><em>terminal_events()</em></tag>
 
      <item>
-       <p> Channels implementing a shell and command execution on the
-       server side should handle the following messages that may be sent by client channel processes. </p>
+       <p>Channels implementing a shell and command execution on the
+       server side are to handle the following messages that can be sent by client-
+       channel processes.</p>
 
-      <note> <p>Events that includes a  <c> WantReply</c> expects the event handling
-       process to call <seealso marker="ssh_connection#reply_request-4">ssh_connection:reply_request/4</seealso>
-       with the boolean value of <c> WantReply</c> as the second
-       argument.  </p></note>
+      <p>Events that include a <c>WantReply</c> expect the event handling
+       process to call <seealso marker="ssh_connection#reply_request-4">
+       ssh_connection:reply_request/4</seealso>
+       with the boolean value of <c>WantReply</c> as the second argument.</p>
 
        <taglist>
 	 <tag><c><![CDATA[{env, ssh_channel_id(), boolean() = WantReply,
 	 string() = Var, string() = Value}]]></c></tag>
-	 <item> Environment variables may be passed to the shell/command
-	 to be started later. This event is sent as result of calling <seealso
-	 marker="ssh_connection#setenv-5"> ssh_connection:setenv/5</seealso>
-	 </item>
+	 <item><p>Environment variables can be passed to the shell/command
+	 to be started later. This event is sent as a result of calling <seealso
+	 marker="ssh_connection#setenv-5"> ssh_connection:setenv/5</seealso>.
+	 </p></item>
 
 	 <tag><c><![CDATA[{pty, ssh_channel_id(),
 	 boolean() = WantReply, {string() = Terminal, integer() = CharWidth,
 	 integer() = RowHeight, integer() = PixelWidth, integer() = PixelHeight,
 	 [{atom() | integer() = Opcode,
 	 integer() = Value}] = TerminalModes}}]]></c></tag>
-	 <item>A pseudo-terminal has been requested for the
-	 session. Terminal is the value of the TERM environment
-	 variable value (e.g., vt100). Zero dimension parameters must
-	 be ignored.  The character/row dimensions override the pixel
-	 dimensions (when nonzero).  Pixel dimensions refer to the
-	 drawable area of the window. The <c>Opcode</c> in the
+	 <item><p>A pseudo-terminal has been requested for the
+	 session. <c>Terminal</c> is the value of the TERM environment
+	 variable value, that is, <c>vt100</c>. Zero dimension parameters must
+	 be ignored. The character/row dimensions override the pixel
+	 dimensions (when non-zero). Pixel dimensions refer to the
+	 drawable area of the window. <c>Opcode</c> in the
 	 <c>TerminalModes</c> list is the mnemonic name, represented
-	 as an lowercase erlang atom, defined in
-	 <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254  </url> section 8.
-	 It may also be an opcode if the mnemonic name is not listed in the
-	 RFC. Example <c>OP code: 53, mnemonic name ECHO erlang atom:
-	 echo</c>.This event is sent as result of calling <seealso
-	 marker="ssh_connection#ptty_alloc/4">ssh_connection:ptty_alloc/4</seealso></item>
+	 as a lowercase Erlang atom, defined in
+	 <url href="http://www.ietf.org/rfc/rfc4254.txt">RFC 4254</url>, Section 8.
+	 It can also be an <c>Opcode</c> if the mnemonic name is not listed in the
+	 RFC. Example: <c>OP code: 53, mnemonic name ECHO erlang atom:
+	 echo</c>. This event is sent as a result of calling <seealso
+	 marker="ssh_connection#ptty_alloc/4">ssh_connection:ptty_alloc/4</seealso>.</p></item>
 
 	 <tag><c><![CDATA[{shell, boolean() = WantReply}]]></c></tag>
-	 <item> This message will request that the user's default shell
-	 be started at the other end. This event is sent as result of calling <seealso
-	 marker="ssh_connection#shell-2"> ssh_connection:shell/2</seealso>
-	 </item>
+	 <item><p>This message requests that the user default shell
+	 is started at the other end. This event is sent as a result of calling
+	 <seealso marker="ssh_connection#shell-2"> ssh_connection:shell/2</seealso>.
+	 </p></item>
 
 	 <tag><c><![CDATA[{window_change, ssh_channel_id(), integer() = CharWidth,
 	 integer() = RowHeight, integer() = PixWidth, integer() = PixHeight}]]></c></tag>
-	 <item> When the window (terminal) size changes on the client
-	 side, it MAY send a message to the server side to inform it of
-	 the new dimensions. There is currently no API function to generate this
-	 event.</item>
+	 <item><p>When the window (terminal) size changes on the client
+	 side, it <em>can</em> send a message to the server side to inform it of
+	 the new dimensions. No API function generates this event.</p></item>
      
 	 <tag><c><![CDATA[{exec, ssh_channel_id(),
 	 boolean() = WantReply, string() = Cmd}]]></c></tag>
-	 <item> This message will request that the server starts
-	 execution of the given command. This event is sent as result of calling <seealso
-	 marker="ssh_connection#exec-4">ssh_connection:exec/4 </seealso>
-	 </item>
+	 <item><p>This message requests that the server starts
+	 execution of the given command. This event is sent as a result of calling <seealso
+	 marker="ssh_connection#exec-4">ssh_connection:exec/4 </seealso>.
+	 </p></item>
        </taglist>
      </item>
    </taglist>
@@ -183,80 +201,83 @@
    
    <func>
      <name>adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok</name>
-     <fsummary>Adjusts the SSH flowcontrol window. </fsummary>
+     <fsummary>Adjusts the SSH flow control window.</fsummary>
      <type>
-       <v> ConnectionRef = ssh_connection_ref() </v>
-       <v> ChannelId = ssh_channel_id() </v>
-       <v> NumOfBytes = integer()</v>
+       <v>ConnectionRef = ssh_connection_ref()</v>
+       <v>ChannelId = ssh_channel_id()</v>
+       <v>NumOfBytes = integer()</v>
      </type>
       <desc>
-	<p>Adjusts the SSH flowcontrol window. This shall be done by both client and server side channel processes.</p>
+	<p>Adjusts the SSH flow control window. This is to be done by both the
+	client- and server-side channel processes.</p>
 	
-	<note><p>Channels implemented with the <seealso marker="ssh_channel"> ssh_channel
-	behavior</seealso> will normaly not need to call this function as flow control
-	will be handled by the behavior. The behavior will adjust the window every time
+	<note><p>Channels implemented with the <seealso marker="ssh_channel"> ssh_channel</seealso>
+	behavior do not normally need to call this function as flow control
+	is handled by the behavior. The behavior adjusts the window every time
 	the callback <seealso marker="ssh_channel#Module:handle_ssh_msg-2">
-	handle_ssh_msg/2 </seealso> has returned after processing channel data</p> </note>
+	handle_ssh_msg/2</seealso> returns after processing channel data.</p></note>
       </desc>
    </func>
    
    <func>
      <name>close(ConnectionRef, ChannelId) -> ok</name>
-     <fsummary>Sends a close message on the channel <c>ChannelId</c>. </fsummary>
+     <fsummary>Sends a close message on the channel <c>ChannelId</c>.</fsummary>
      <type>
-       <v> ConnectionRef = ssh_connection_ref() </v>
-       <v> ChannelId = ssh_channel_id()</v>
+       <v>ConnectionRef = ssh_connection_ref()</v>
+       <v>ChannelId = ssh_channel_id()</v>
      </type>
      <desc>
-       <p>A server or client channel process can choose to close their session by sending a close event.
+       <p>A server- or client-channel process can choose to close their session by
+       sending a close event.
        </p>
 
-       <note><p>This function will be called by the ssh_channel
-       behavior when the channel is terminated see <seealso
-       marker="ssh_channel"> ssh_channel(3) </seealso> so channels implemented with the
-       behavior should not call this function explicitly.</p></note>
+       <note><p>This function is called by the <c>ssh_channel</c>
+       behavior when the channel is terminated, see <seealso
+       marker="ssh_channel"> ssh_channel(3) </seealso>. Thus, channels implemented
+       with the behavior are not to call this function explicitly.</p></note>
      </desc>
    </func>
    
    <func>
-     <name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | {error, reason()} </name>
-     <fsummary>Request that the server start the execution of the given command.  </fsummary>
+     <name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() |
+     {error, reason()}</name>
+     <fsummary>Requests that the server starts the execution of the given command.</fsummary>
      <type>
-       <v> ConnectionRef = ssh_connection_ref() </v>
-       <v> ChannelId = ssh_channel_id()</v>
-       <v> Command = string()</v>
-       <v>Timeout = timeout() </v>
+       <v>ConnectionRef = ssh_connection_ref()</v>
+       <v>ChannelId = ssh_channel_id()</v>
+       <v>Command = string()</v>
+       <v>Timeout = timeout()</v>
      </type>
      <desc>
-       <p>Should be called by a client channel process to request that the server starts execution of the
-       given command, the result will be several messages according to the following pattern. Note
-       that the last message will be a channel close message, as the exec request is a one time
-       execution that closes the channel when it is done.</p>
+       <p>Is to be called by a client-channel process to request that the server starts
+       executing the given command. The result is several messages according to the
+       following pattern. The last message is a channel close message, as the <c>exec</c>
+       request is a one-time execution that closes the channel when it is done.</p>
 
        <taglist>
-	 <tag><c> N x {ssh_cm, ssh_connection_ref(),
-	 {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} </c></tag>
-	 <item>The result of executing the command may be only one line
-	 or thousands of lines depending on the command.</item>
+	 <tag><c>N x {ssh_cm, ssh_connection_ref(),
+	 {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}}</c></tag>
+	 <item><p>The result of executing the command can be only one line
+	 or thousands of lines depending on the command.</p></item>
 
 	 <tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
-	 <item>Indicates that no more data will be sent.</item>
+	 <item><p>Indicates that no more data is to be sent.</p></item>
 
 	 <tag><c>0 or 1 x {ssh_cm,
 	 ssh_connection_ref(), {exit_signal,
 	 ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}</c></tag>
-	 <item>Not all systems send signals. For details on valid string
-	 values see RFC 4254 section 6.10 </item>
+	 <item><p>Not all systems send signals. For details on valid string
+	 values, see RFC 4254, Section 6.10</p></item>
 	 
 	  <tag><c>0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status,
 	  ssh_channel_id(), integer() = ExitStatus}}</c></tag>
-	  <item>It is recommended by the <c>ssh connection protocol</c> that this
-	  message shall be sent, but that may not always be the case.</item>
+	  <item><p>It is recommended by the SSH Connection Protocol to send this
+	  message, but that is not always the case.</p></item>
 
-	  <tag><c> 1 x {ssh_cm, ssh_connection_ref(),
+	  <tag><c>1 x {ssh_cm, ssh_connection_ref(),
 	  {closed, ssh_channel_id()}}</c></tag>
-	  <item>Indicates that the ssh channel started for the
-	  execution of the command has now been shutdown.</item>
+	  <item><p>Indicates that the <c>ssh_channel</c> started for the
+	  execution of the command has now been shut down.</p></item>
        </taglist>
      </desc>
    </func>
@@ -265,78 +286,72 @@
      <name>exit_status(ConnectionRef, ChannelId, Status) -> ok</name>
      <fsummary>Sends the exit status of a command to the client.</fsummary>
      <type>
-       <v> ConnectionRef = ssh_connection_ref() </v>
-       <v> ChannelId = ssh_channel_id()</v>
-       <v> Status = integer()</v>
+       <v>ConnectionRef = ssh_connection_ref() </v>
+       <v>ChannelId = ssh_channel_id()</v>
+       <v>Status = integer()</v>
      </type>
      <desc>
-       <p>Should be called by a server channel process to sends the exit status of a command to the client.</p>
+       <p>Is to be called by a server-channel process to send the exit status of a command
+       to the client.</p>
      </desc>
    </func>
    
    <func>
-     <name>ptty_alloc(ConnectionRef, ChannelId, Options) ->  </name>
-     <name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) ->  > ssh_request_status() | {error, reason()}  </name>
-       <fsummary>Send status replies to requests that want such replies. </fsummary>
+     <name>ptty_alloc(ConnectionRef, ChannelId, Options) -></name>
+     <name>ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) ->  > ssh_request_status() |
+     {error, reason()}</name>
+       <fsummary>Sends an SSH Connection Protocol <c>pty_req</c>,
+       to allocate a pseudo-terminal.</fsummary>
       <type>
-	<v> ConnectionRef = ssh_connection_ref() </v>
-	<v> ChannelId = ssh_channel_id()</v>
-	<v> Options = proplists:proplist()</v>
+	<v>ConnectionRef = ssh_connection_ref()</v>
+	<v>ChannelId = ssh_channel_id()</v>
+	<v>Options = proplists:proplist()</v>
       </type>
       <desc>
-	<p> Sends a SSH Connection Protocol pty_req, to allocate a pseudo tty.
-	Should be called by a SSH client process.
-	Options are:
-	</p>
+	<p>Sends an SSH Connection Protocol <c>pty_req</c>, to allocate a pseudo-terminal.
+	Is to be called by an SSH client process.</p>
+	<p>Options:</p>
 
 	<taglist>
 	  <tag>{term, string()}</tag>
-	  <item>
-	    Defaults to os:getenv("TERM") or "vt100" if it is undefined. 
-	  </item>
+	  <item><p>Defaults to <em>os:getenv("TERM")</em> or <em>vt100</em>
+	  if it is undefined.</p></item>
+
 	  <tag>{width, integer()}</tag>
-	  <item>
-	    Defaults to 80 if pixel_width is not defined.
-	  </item>
+	  <item><p>Defaults to 80 if <c>pixel_width</c> is not defined.</p></item>
+
 	  <tag>{height, integer()}</tag>
-	  <item>
-	    Defaults to 24 if pixel_height is not defined.
-	  </item>
+	  <item><p>Defaults to 24 if <c>pixel_height</c> is not defined.</p></item>
+
 	  <tag>{pixel_width, integer()}</tag>
-	  <item>
-	    Is disregarded if width is defined.
-	  </item>
+	  <item><p>Is disregarded if <c>width</c> is defined.</p></item>
+
 	  <tag>{pixel_height, integer()}</tag>
-	  <item>
-	    Is disregarded if height is defined.
-	  </item>
+	  <item><p>Is disregarded if <c>height</c> is defined.</p></item>
+
 	  <tag>{pty_opts, [{posix_atom(), integer()}]}</tag>
-	  <item>
-	    Option may be an empty list, otherwise
-	    see possible POSIX names in section 8 in <url href="http://www.ietf.org/rfc/rfc4254.txt"> RFC 4254</url>.
+	  <item><p>Option can be an empty list. Otherwise, see possible <em>POSIX</em> names
+	  in Section 8 in <url href="http://www.ietf.org/rfc/rfc4254.txt"> RFC 4254</url>.</p>
 	  </item>
 	 </taglist>
-
       </desc>
      </func>
 
-   <func>
+     <func>
        <name>reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok</name>
-       <fsummary>Send status replies to requests that want such replies. </fsummary>
+       <fsummary>Sends status replies to requests that want such replies.</fsummary>
       <type>
-	<v> ConnectionRef = ssh_connection_ref() </v>
-	<v> WantReply =  boolean()</v>
-	<v> Status = ssh_request_status() </v>
-	<v> ChannelId = ssh_channel_id()</v>
+	<v>ConnectionRef = ssh_connection_ref()</v>
+	<v>WantReply =  boolean()</v>
+	<v>Status = ssh_request_status()</v>
+	<v>ChannelId = ssh_channel_id()</v>
       </type>
       <desc>
 	<p>Sends status replies to requests where the requester has
-	stated that they want a status report e.i .<c> WantReply = true</c>,
-	if <c> WantReply</c> is false calling this function will be a
-	"noop". Should be called while handling an ssh connection
-	protocol message containing a <c>WantReply</c> boolean
-	value.
-	</p>
+	stated that it wants a status report, that is, <c>WantReply = true</c>.
+	If <c>WantReply</c> is <c>false</c>, calling this function becomes a
+	"noop". Is to be called while handling an SSH Connection
+	Protocol message containing a <c>WantReply</c> boolean value.</p>
       </desc>
      </func>
     
@@ -346,98 +361,97 @@
        <name>send(ConnectionRef, ChannelId, Type, Data) -></name>
        <name>send(ConnectionRef, ChannelId, Type, Data, TimeOut) ->
        ok | {error, timeout} | {error, closed}</name>
-       <fsummary>Sends channel data </fsummary>
+       <fsummary>Sends channel data.</fsummary>
        <type>
-	<v> ConnectionRef = ssh_connection_ref() </v>
-	<v> ChannelId = ssh_channel_id()</v>
-	<v> Data = binary()</v>
-	<v> Type = ssh_data_type_code()</v>
-	<v> Timeout = timeout()</v>
+	<v>ConnectionRef = ssh_connection_ref()</v>
+	<v>ChannelId = ssh_channel_id()</v>
+	<v>Data = binary()</v>
+	<v>Type = ssh_data_type_code()</v>
+	<v>Timeout = timeout()</v>
        </type>
        <desc>
-	 <p>Should be called by client- and server channel processes to send data to each other.
+	 <p>Is to be called by client- and server-channel processes to send data to each other.
 	 </p>
        </desc>
      </func>
      
      <func>
        <name>send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}</name>
-       <fsummary>Sends eof on the channel <c>ChannelId</c>.  </fsummary>
+       <fsummary>Sends EOF on channel <c>ChannelId</c>.</fsummary>
        <type>
-	<v> ConnectionRef = ssh_connection_ref() </v>
-	<v> ChannelId = ssh_channel_id()</v>
+	<v>ConnectionRef = ssh_connection_ref()</v>
+	<v>ChannelId = ssh_channel_id()</v>
        </type>
        <desc>
-	 <p>Sends eof on the channel <c>ChannelId</c>.
-	 </p>
+	 <p>Sends EOF on channel <c>ChannelId</c>.</p>
        </desc>
      </func>
 
      <func>
-       <name>session_channel(ConnectionRef, Timeout) -> </name>
+       <name>session_channel(ConnectionRef, Timeout) -></name>
        <name>session_channel(ConnectionRef, InitialWindowSize,
        MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()}</name>
-       <fsummary>Opens a channel for a ssh session. </fsummary>
+       <fsummary>Opens a channel for an SSH session.</fsummary>
        <type>
-	 <v> ConnectionRef = ssh_connection_ref()</v>
-	 <v> InitialWindowSize = integer() </v>
-	 <v> MaxPacketSize = integer() </v>
-	 <v> Timeout = timeout()</v>
-	 <v> Reason = term() </v>
+	 <v>ConnectionRef = ssh_connection_ref()</v>
+	 <v>InitialWindowSize = integer()</v>
+	 <v>MaxPacketSize = integer()</v>
+	 <v>Timeout = timeout()</v>
+	 <v>Reason = term()</v>
        </type>
        <desc>
 	 <p>Opens a channel for an SSH session. The channel id returned from this function
-	 is the id used as input to the other funtions in this module.
-	</p>
+	 is the id used as input to the other functions in this module.</p>
        </desc>
      </func>
 
     <func>
-      <name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | {error, reason()} </name>
-      <fsummary> Environment variables may be passed to the
+      <name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() |
+      {error, reason()}</name>
+      <fsummary>Environment variables can be passed to the
       shell/command to be started later.</fsummary>
       <type>
-	<v> ConnectionRef = ssh_connection_ref() </v>
-	<v> ChannelId = ssh_channel_id()</v>
-	<v> Var = string()</v>
-	<v> Value = string()</v>
-	<v> Timeout = timeout()</v>
+	<v>ConnectionRef = ssh_connection_ref()</v>
+	<v>ChannelId = ssh_channel_id()</v>
+	<v>Var = string()</v>
+	<v>Value = string()</v>
+	<v>Timeout = timeout()</v>
       </type>
       <desc>
-	<p> Environment variables may be passed before starting the
-	shell/command. Should be called by a client channel processes.
-	</p>
+	<p>Environment variables can be passed before starting the
+	shell/command. Is to be called by a client channel processes.</p>
       </desc>
     </func>
     
     <func>
       <name>shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed}
       </name>
-      <fsummary> Requests that the user's default shell (typically
-      defined in /etc/passwd in UNIX systems) shall be executed at the server
-      end. </fsummary>
+      <fsummary>Requests that the user default shell (typically defined in
+      /etc/passwd in Unix systems) is to be executed at the server end.</fsummary>
        <type>
-	 <v> ConnectionRef = ssh_connection_ref() </v>
-	 <v> ChannelId = ssh_channel_id()</v>
+	 <v>ConnectionRef = ssh_connection_ref()</v>
+	 <v>ChannelId = ssh_channel_id()</v>
        </type>
        <desc>
-	 <p> Should be called by a client channel process to request that the user's default shell (typically
-	 defined in /etc/passwd in UNIX systems) shall be executed at the server end.
-	 </p>
+	 <p>Is to be called by a client channel process to request that the user default
+	 shell (typically defined in /etc/passwd in Unix systems) is executed
+	 at the server end.</p>
        </desc>
     </func>
 
     <func>
-      <name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | {error, reason()} </name>
-      <fsummary>  </fsummary>
+      <name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() |
+      {error, reason()}</name>
+      <fsummary>Requests to execute a predefined subsystem on the server.</fsummary>
        <type>
-	 <v> ConnectionRef = ssh_connection_ref() </v>
-	 <v> ChannelId = ssh_channel_id()</v>
-	 <v> Subsystem = string()</v>
-	 <v> Timeout = timeout()</v>
+	 <v>ConnectionRef = ssh_connection_ref()</v>
+	 <v>ChannelId = ssh_channel_id()</v>
+	 <v>Subsystem = string()</v>
+	 <v>Timeout = timeout()</v>
        </type>
        <desc>
-	 <p> Should be called by a client channel process for requesting to execute a predefined subsystem on the server.
+	 <p>Is to be called by a client-channel process for requesting to execute a predefined
+	 subsystem on the server.
 	 </p>
        </desc>
     </func>
diff --git a/lib/ssh/doc/src/ssh_server_key_api.xml b/lib/ssh/doc/src/ssh_server_key_api.xml
index f7133e4ba5..9e1f4e908d 100644
--- a/lib/ssh/doc/src/ssh_server_key_api.xml
+++ b/lib/ssh/doc/src/ssh_server_key_api.xml
@@ -23,68 +23,81 @@
       The Initial Developer of the Original Code is Ericsson AB.
     </legalnotice>
     <title>ssh_server_key_api</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
   </header>
   <module>ssh_server_key_api</module>
   <modulesummary>
     -behaviour(ssh_server_key_api).
   </modulesummary>
   <description>
-    <p>  Behaviour describing the API for an SSH server's public key handling. By implementing the callbacks defined
-    in this behavior it is possible to customize the SSH server's public key
-    handling. By default the SSH application implements this behavior
-    with help of the standard openssh files, see <seealso marker="SSH_app"> ssh(6)</seealso>.</p>
+    <p>Behaviour describing the API for public key handling of an SSH server. By implementing
+    the callbacks defined in this behavior, the public key handling of an SSH server can
+    be customized. By default the SSH application implements this behavior
+    with help of the standard OpenSSH files,
+    see the <seealso marker="SSH_app"> ssh(6)</seealso> application.</p>
   </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. For more details on public key data types 
-    see the <seealso marker="public_key:public_key_records"> public_key user's guide.</seealso>
+    <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. For more details on public key data types,
+    refer to Section 2 Public Key Records in the
+    <seealso marker="public_key:public_key_records"> public_key user's guide</seealso>.
     </p>
 
-    <p> boolean() = true | false</p>
-    <p> string() = [byte()]</p>
-    <p> public_key() =  #'RSAPublicKey'{} | {integer(),  #'Dss-Parms'{}} | term()</p>
-    <p> private_key() =  #'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</p>
-    <p> public_key_algorithm() =  'ssh-rsa' | 'ssh-dss' | atom()</p>
+<taglist>
+      <tag><c>boolean()</c></tag>
+      <item><p>= <c>true | false</c></p></item>
+      <tag><c>string()</c></tag>
+      <item><p>= <c>[byte()]</c></p></item>
+      <tag><c>public_key()</c></tag>
+      <item><p>= <c>#'RSAPublicKey'{}| {integer(),  #'Dss-Parms'{}}| term()</c></p></item>
+      <tag><c>private_key()</c></tag>
+      <item><p>= <c>#'RSAPrivateKey'{} | #'DSAPrivateKey'{} | term()</c></p></item>
+      <tag><c>public_key_algorithm()</c></tag>
+      <item><p>= <c>'ssh-rsa'| 'ssh-dss' | atom()</c></p></item>
+    </taglist>
   </section>
 
   <funcs>
     <func>
       <name>Module:host_key(Algorithm, DaemonOptions) ->
       {ok, Key} | {error, Reason}</name>
-      <fsummary>Fetches the hosts private key </fsummary>
+      <fsummary>Fetches the host’s private key.</fsummary>
       <type>
 	<v>Algorithm = public_key_algorithm()</v>
-	<d> Host key algorithm. Should support 'ssh-rsa' | 'ssh-dss' but additional algorithms
+	<d>Host key algorithm. Is to support <c>'ssh-rsa' | 'ssh-dss'</c>, but more algorithms
 	can be handled.</d>
-	<v> DaemonOptions = proplists:proplist() </v>
-	<d>Options provided to  <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso></d>
-	<v> Key = private_key()</v>
-	<d> The private key of the host matching the <c>Algorithm</c></d>
-	<v>Reason = term() </v>
+	<v>DaemonOptions = proplists:proplist()</v>
+	<d>Options provided to  <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso>.</d>
+	<v>Key = private_key()</v>
+	<d>Private key of the host matching the <c>Algorithm</c>.</d>
+	<v>Reason = term()</v>
       </type>
       <desc>
-	  <p>Fetches the hosts private key</p>
+	  <p>Fetches the private key of the host.</p>
       </desc>
     </func>
 
     <func>
       <name>Module:is_auth_key(Key, User, DaemonOptions) -> Result</name>
-      <fsummary> Checks if the user key is authorized</fsummary>
+      <fsummary>Checks if the user key is authorized.</fsummary>
       <type>
-	<v> Key = public_key() </v>
-	<d> Normally an RSA or DSA public key but handling of other public keys can be added</d>
-	<v> User = string()</v>
-	<d> The user owning the public key</d>
-	<v> DaemonOptions = proplists:proplist() </v>
-	<d> Options provided to  <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso></d>
-	<v> Result = boolean()</v>
+	<v>Key = public_key()</v>
+	<d>Normally an RSA or DSA public key, but handling of other public keys can be added</d>
+	<v>User = string()</v>
+	<d>User owning the public key.</d>
+	<v>DaemonOptions = proplists:proplist()</v>
+	<d>Options provided to  <seealso marker="ssh#daemon-2">ssh:daemon/[2,3]</seealso>.</d>
+	<v>Result = boolean()</v>
       </type>
       <desc>
-	 <p> Checks if the user key is authorized </p>
+	 <p>Checks if the user key is authorized.</p>
       </desc>
     </func>
 
diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index ab111562f9..95869befb8 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -23,43 +23,49 @@
 
     <title>ssh_sftp</title>
     <prepared>OTP</prepared>
+    <docno></docno>
     <date>2005-09-22</date>
+    <rev></rev>
     <file>ssh_sftp.sgml</file>
   </header>
   <module>ssh_sftp</module>
   <modulesummary>SFTP client.</modulesummary>
   <description>
-    <p>This module implements an SFTP (SSH FTP) client. SFTP is a
+    <p>This module implements an SSH FTP (SFTP) client. SFTP is a
     secure, encrypted file transfer service available for
     SSH.</p>
   </description>
   
  <section>
-    <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:
+    <title>DATA TYPES</title>
+    <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>ssh_connection_ref() - opaque to the user
-    returned by ssh:connect/3</c></p>
-    <p><c>timeout() =  infinity | integer() - in milliseconds.</c></p>    
+
+    <taglist>
+      <tag><c>ssh_connection_ref()</c></tag>
+      <item><p>Opaque to the user, returned by <c>ssh:connect/3</c></p></item>
+      <tag><c>timeout()</c></tag>
+      <item><p>= <c>infinity | integer() in milliseconds</c></p></item>
+    </taglist>
    </section>
 
  <section>
-    <title>TIMEOUTS </title>
-    <p>If the request functions for the SFTP channel return {error, timeout}
-    it does not guarantee that the request did not reach the server and was
-    not performed, it only means that we did not receive an answer from the
-    server within the time that was expected.</p>
+    <title>Time-outs</title>
+    <p>If the request functions for the SFTP channel return <c>{error, timeout}</c>,
+    it does not guarantee that the request never reached the server and was
+    not performed. It only means that no answer was received from the
+    server within the expected time.</p>
    </section>
 
   <funcs>
     <func>
-      <name>start_channel(ConnectionRef) -> </name>
-      <name>start_channel(ConnectionRef, Options) -> </name>
+      <name>start_channel(ConnectionRef) -></name>
+      <name>start_channel(ConnectionRef, Options) -></name>
       <name>start_channel(Host, Options) -></name>
       <name>start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} |
       {error, Reason}</name>
-      <fsummary>Starts a SFTP client</fsummary>
+      <fsummary>Starts an SFTP client.</fsummary>
       <type>
         <v>Host = string()</v>
         <v>ConnectionRef = ssh_connection_ref()</v>
@@ -69,33 +75,33 @@
       </type>
       <desc>
 	<p>If no connection reference is provided, a connection is set
-	up and the new connection is returned.  An SSH channel process
+	up, and the new connection is returned. An SSH channel process
 	is started to handle the communication with the SFTP server.
-	The returned pid for this process should be used as input to
+	The returned <c>pid</c> for this process is to be used as input to
 	all other API functions in this module.</p>
 
-	<p>Options are:</p>
+	<p>Options:</p>
 	<taglist>
           <tag><c><![CDATA[{timeout, timeout()}]]></c></tag>
 	  <item>
-	    <p>The timeout is passed to the ssh_channel start function,
-	    and defaults to infinity.</p>
+	    <p>The time-out is passed to the <c>ssh_channel</c> start function,
+	    and defaults to <c>infinity</c>.</p>
 	  </item>
 	  <tag>
-	    <p><c><![CDATA[{sftp_vsn, integer()}]]></c></p>
+	    <c><![CDATA[{sftp_vsn, integer()}]]></c>
 	  </tag>
 	  <item>
 	    <p>
 	      Desired SFTP protocol version.
-	      The actual version will be the minimum of
+	      The actual version is the minimum of
 	      the desired version and the maximum supported
 	      versions by the SFTP server.
 	    </p>
 	  </item>
 	</taglist>
-	<p>All other options are  directly passed to
+	<p>All other options are directly passed to
 	<seealso marker="ssh">ssh:connect/3</seealso> or ignored if a
-	connection is already provided. </p>
+	connection is already provided.</p>
       </desc>
     </func>
 
@@ -106,15 +112,15 @@
         <v>ChannelPid = pid()</v>
       </type>
       <desc>
-	<p>Stops an SFTP channel. Does not close the SSH connetion.
+	<p>Stops an SFTP channel. Does not close the SSH connection.
 	Use <seealso marker="ssh">ssh:close/1</seealso> to close it.</p>
       </desc>
     </func>
   
     <func>
-      <name>read_file(ChannelPid, File) -> </name>
+      <name>read_file(ChannelPid, File) -></name>
       <name>read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason}</name>
-      <fsummary>Read a file</fsummary>
+      <fsummary>Reads a file.</fsummary>
       <type>
 	<v>ChannelPid = pid()</v>
 	<v>File = string()</v>
@@ -128,9 +134,9 @@
       </desc>
     </func>
     <func>
-      <name>write_file(ChannelPid, File, Iolist) -> </name>
+      <name>write_file(ChannelPid, File, Iolist) -></name>
       <name>write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Write a file</fsummary>
+      <fsummary>Writes a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>File = string()</v>
@@ -140,14 +146,14 @@
       </type>
       <desc>
         <p>Writes a file to the server, like
-        <c><![CDATA[file:write_file/2]]></c>.  The file is created if
-        it does not exist or is owerwritten if it does.</p>
+        <c><![CDATA[file:write_file/2]]></c>. The file is created if
+        it does not exist. The file is overwritten if it exists.</p>
       </desc>
     </func>
     <func>
-      <name>list_dir(ChannelPid, Path) -> </name>
+      <name>list_dir(ChannelPid, Path) -></name>
       <name>list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason}</name>
-      <fsummary>List directory</fsummary>
+      <fsummary>Lists the directory.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
@@ -162,9 +168,9 @@
       </desc>
     </func>
     <func>
-      <name>open(ChannelPid, File, Mode) -> </name>
+      <name>open(ChannelPid, File, Mode) -></name>
       <name>open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Open a file and return a handle</fsummary>
+      <fsummary>Opens a file and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>File = string()</v>
@@ -175,14 +181,14 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a file on the server, and returns a handle that
+        <p>Opens a file on the server and returns a handle, which
           can be used for reading or writing.</p>
       </desc>
     </func>
     <func>
-      <name>opendir(ChannelPid, Path) -> </name>
+      <name>opendir(ChannelPid, Path) -></name>
       <name>opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Open a directory and return a handle</fsummary>
+      <fsummary>Opens a directory and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
@@ -190,7 +196,7 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a handle to a directory on the server, the handle
+        <p>Opens a handle to a directory on the server. The handle
           can be used for reading directory contents.</p>
       </desc>
     </func>
@@ -198,14 +204,15 @@
     <func>
       <name>open_tar(ChannelPid, Path, Mode) -></name>
       <name>open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Opens a tar file on the server to which <v>ChannelPid</v> is connected and returns a handle</fsummary>
+      <fsummary>Opens a tar file on the server to which <c>ChannelPid</c>
+      is connected and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
-	<v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt] </v>
+	<v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt]</v>
 	<v>EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}</v>
 	<v>DecryptOpt = {crypto,{InitFun,DecryptFun}}</v>
-	<v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize}) </v>
+	<v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize})</v>
 	<v>CryptoState = any()</v>
 	<v>ChunkSize = undefined | pos_integer()</v>
 	<v>EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)</v>
@@ -219,11 +226,11 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a handle to a tar file on the server associated with <c>ChannelPid</c>. The handle
-	can be used for remote tar creation and extraction as defined by the
+        <p>Opens a handle to a tar file on the server, associated with <c>ChannelPid</c>.
+	The handle can be used for remote tar creation and extraction, as defined by the
 	<seealso marker="stdlib:erl_tar#init/3">erl_tar:init/3</seealso> function.
 	</p>
-	<p>An example of writing and then reading a tar file:</p>
+	<p>Example of writing and then reading a tar file follows:</p>
         <code type="none">
           {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]),
           ok = erl_tar:add(HandleWrite, .... ),
@@ -238,25 +245,24 @@
           ok = erl_tar:close(HandleRead),
         </code>
 
-	<p>The <c>crypto</c> mode option is applied to the generated stream of bytes just prior to sending
-	them to the sftp server.  This is intended for encryption but could of course be used for other
+	<p>The <c>crypto</c> mode option is applied to the generated stream of bytes prior to sending
+	them to the SFTP server. This is intended for encryption but can be used for other
 	purposes.
 	</p>
 	<p>The <c>InitFun</c> is applied once
-	prior to any other crypto operation. The returned <c>CryptoState</c> is then folded into
-	repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>.  The binary returned
-	from those Funs are sent further to the remote sftp server. Finally - if doing encryption
-	- the <c>CloseFun</c> is applied to the last piece of data.  The <c>CloseFun</c> is
+	prior to any other <c>crypto</c> operation. The returned <c>CryptoState</c> is then folded into
+	repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>. The binary returned
+	from those funs are sent further to the remote SFTP server. Finally, if doing encryption,
+	the <c>CloseFun</c> is applied to the last piece of data. The <c>CloseFun</c> is
 	responsible for padding (if needed) and encryption of that last piece.
 	</p>
 	<p>The <c>ChunkSize</c> defines the size of the <c>PlainBin</c>s that <c>EncodeFun</c> is applied
-	to. If the <c>ChunkSize</c> is <c>undefined</c> the size of the <c>PlainBin</c>s varies because
-	this is	inteded for stream crypto while a fixed  <c>ChunkSize</c> is intended for block crypto. It
-	is possible to change the  <c>ChunkSize</c>s in the return from the <c>EncryptFun</c> or
-	<c>DecryptFun</c>. It is in fact possible to change the value between <c>pos_integer()</c> and
-	<c>undefined</c>.
+	to. If the <c>ChunkSize</c> is <c>undefined</c>, the size of the <c>PlainBin</c>s varies,
+	because this is	intended for stream crypto, whereas a fixed <c>ChunkSize</c> is intended for block crypto.
+	<c>ChunkSize</c>s can be changed in the return from the <c>EncryptFun</c> or
+	<c>DecryptFun</c>. The value can be changed between <c>pos_integer()</c> and <c>undefined</c>.
 	</p>
-	<p>The write and read example above can be extended with encryption and decryption:</p>
+	<p>The previous write and read example can be extended with encryption and decryption as follows:</p>
         <code type="none">
           %% First three parameters depending on which crypto type we select:
           Key = &lt;&lt;"This is a 256 bit key. abcdefghi">>,
@@ -307,9 +313,9 @@
     </func>
 
     <func>
-      <name>close(ChannelPid, Handle) -> </name>
+      <name>close(ChannelPid, Handle) -></name>
       <name>close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Close an open handle</fsummary>
+      <fsummary>Closes an open handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -321,11 +327,11 @@
       </desc>
     </func>
     <func>
-      <name>read(ChannelPid, Handle, Len) -> </name>
+      <name>read(ChannelPid, Handle, Len) -></name>
       <name>read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
-      <name>pread(ChannelPid, Handle, Position, Len) -> </name>
+      <name>pread(ChannelPid, Handle, Position, Len) -></name>
       <name>pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
-      <fsummary>Read from an open file</fsummary>
+      <fsummary>Reads from an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -340,8 +346,8 @@
           <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, <c><![CDATA[eof]]></c>, or
           <c><![CDATA[{error, Reason}]]></c>. If the file is opened with <c><![CDATA[binary]]></c>,
           <c><![CDATA[Data]]></c> is a binary, otherwise it is a string.</p>
-        <p>If the file is read past eof, only the remaining bytes
-          will be read and returned. If no bytes are read, <c><![CDATA[eof]]></c>
+        <p>If the file is read past <c>eof</c>, only the remaining bytes
+          are read and returned. If no bytes are read, <c><![CDATA[eof]]></c>
           is returned.</p>
         <p>The <c><![CDATA[pread]]></c> function reads from a specified position,
           combining the <c><![CDATA[position]]></c> and <c><![CDATA[read]]></c> functions.</p>
@@ -350,7 +356,7 @@
     <func>
       <name>aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error}</name>
       <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}</name>
-      <fsummary>Read asynchronously from an open file</fsummary>
+      <fsummary>Reads asynchronously from an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -361,12 +367,12 @@
       </type>
       <desc>
         <p>Reads from an open file, without waiting for the result. If the
-          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
+          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
           is a term guaranteed to be unique between calls of <c><![CDATA[aread]]></c>. 
           The actual data is sent as a message to the calling process. This
           message has the form <c><![CDATA[{async_reply, N, Result}]]></c>, where
           <c><![CDATA[Result]]></c> is the result from the read, either <c><![CDATA[{ok, Data}]]></c>,
-          or <c><![CDATA[eof]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
+          <c><![CDATA[eof]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
         <p>The <c><![CDATA[apread]]></c> function reads from a specified position,
           combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p>
       </desc>
@@ -374,9 +380,9 @@
     <func>
       <name>write(ChannelPid, Handle, Data) -></name>
       <name>write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error}</name>
-      <name>pwrite(ChannelPid, Handle, Position, Data) -> ok </name>
+      <name>pwrite(ChannelPid, Handle, Position, Data) -> ok</name>
       <name>pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error}</name>
-      <fsummary>Write to an open file</fsummary>
+      <fsummary>Writes to an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -386,27 +392,27 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes<c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
-          The file should be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
-          flag. Returns <c><![CDATA[ok]]></c> if successful or S<c><![CDATA[{error, Reason}]]></c>
+        <p>Writes <c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
+          The file is to be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
+          flag. Returns <c><![CDATA[ok]]></c> if successful or <c><![CDATA[{error, Reason}]]></c>
           otherwise.</p>
-        <p>Typical error reasons are:</p>
+        <p>Typical error reasons:</p>
         <taglist>
           <tag><c><![CDATA[ebadf]]></c></tag>
           <item>
-            <p>The file is not opened for writing.</p>
+            <p>File is not opened for writing.</p>
           </item>
           <tag><c><![CDATA[enospc]]></c></tag>
           <item>
-            <p>There is a no space left on the device.</p>
+            <p>No space is left on the device.</p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} </name>
+      <name>awrite(ChannelPid, Handle, Data) -> ok | {error, Reason}</name>
       <name>apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}</name>
-      <fsummary>Write asynchronously to an open file</fsummary>
+      <fsummary>Writes asynchronously to an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -418,24 +424,25 @@
       </type>
       <desc>
         <p>Writes to an open file, without waiting for the result. If the
-          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
+          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
           is a term guaranteed to be unique between calls of
           <c><![CDATA[awrite]]></c>. The result of the <c><![CDATA[write]]></c> operation is sent
           as a message to the calling process. This message has the form
           <c><![CDATA[{async_reply, N, Result}]]></c>, where <c><![CDATA[Result]]></c> is the result
           from the write, either <c><![CDATA[ok]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
-        <p>The <c><![CDATA[apwrite]]></c> writes on a specified position, combining
+        <p><c><![CDATA[apwrite]]></c> writes on a specified position, combining
           the <c><![CDATA[position]]></c> and <c><![CDATA[awrite]]></c> operations.</p>
       </desc>
     </func>
     <func>
-      <name>position(ChannelPid, Handle, Location) -> </name>
+      <name>position(ChannelPid, Handle, Location) -></name>
       <name>position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error}</name>
-      <fsummary>Seek position in open file</fsummary>
+      <fsummary>Sets the file position of a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
-        <v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
+        <v>Location = Offset
+ | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
         <v>Offset = integer()</v>
 	<v>Timeout = timeout()</v>
         <v>NewPosition = integer()</v>
@@ -465,15 +472,17 @@
           </item>
           <tag><c><![CDATA[bof | cur | eof]]></c></tag>
           <item>
-            <p>The same as above with <c><![CDATA[Offset]]></c> 0.</p>
+            <p>The same as eariler with <c><![CDATA[Offset]]></c> 0,
+	    that is, <c><![CDATA[{bof, 0} | {cur, 0} | {eof, 0}]]></c>.
+	    </p>
           </item>
         </taglist>
       </desc>
     </func>
     <func>
-      <name>read_file_info(ChannelPid, Name) -> </name>
+      <name>read_file_info(ChannelPid, Name) -></name>
       <name>read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
-      <fsummary>Get information about a file</fsummary>
+      <fsummary>Gets information about a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -484,13 +493,14 @@
       </type>
       <desc>
         <p>Returns a <c><![CDATA[file_info]]></c> record from the file specified by
-          <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like <c><![CDATA[file:read_file_info/2]]></c>.</p>
+          <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>,
+	like <c><![CDATA[file:read_file_info/2]]></c>.</p>
       </desc>
     </func>
     <func>
       <name>read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason}</name>
       <name>read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
-      <fsummary>Get information about a symbolic link</fsummary>
+      <fsummary>Gets information about a symbolic link.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -506,9 +516,9 @@
       </desc>
     </func>
     <func>
-      <name>write_file_info(ChannelPid, Name, Info) -> </name>
+      <name>write_file_info(ChannelPid, Name, Info) -></name>
       <name>write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Write information for a file</fsummary>
+      <fsummary>Writes information for a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -522,9 +532,9 @@
       </desc>
     </func>
     <func>
-      <name>read_link(ChannelPid, Name) -> </name>
+      <name>read_link(ChannelPid, Name) -></name>
       <name>read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason}</name>
-      <fsummary>Read symbolic link</fsummary>
+      <fsummary>Reads symbolic link.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -537,9 +547,9 @@
       </desc>
     </func>
     <func>
-      <name>make_symlink(ChannelPid, Name, Target) -> </name>
+      <name>make_symlink(ChannelPid, Name, Target) -></name>
       <name>make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Create symbolic link</fsummary>
+      <fsummary>Creates a symbolic link.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -552,9 +562,9 @@
       </desc>
     </func>
     <func>
-      <name>rename(ChannelPid, OldName, NewName) ->  </name>
+      <name>rename(ChannelPid, OldName, NewName) -> </name>
       <name>rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Rename a file</fsummary>
+      <fsummary>Renames a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>OldName = string()</v>
@@ -563,14 +573,14 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Renames a file named <c><![CDATA[OldName]]></c>, and gives it the name
-          <c><![CDATA[NewName]]></c>, like <c><![CDATA[file:rename/2]]></c></p>
+        <p>Renames a file named <c><![CDATA[OldName]]></c> and gives it the name
+          <c><![CDATA[NewName]]></c>, like <c><![CDATA[file:rename/2]]></c>.</p>
       </desc>
     </func>
     <func>
-      <name>delete(ChannelPid, Name) -> </name>
+      <name>delete(ChannelPid, Name) -></name>
       <name>delete(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Delete a file</fsummary>
+      <fsummary>Deletes a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -579,13 +589,13 @@
       </type>
       <desc>
         <p>Deletes the file specified by <c><![CDATA[Name]]></c>, like
-          <c><![CDATA[file:delete/1]]></c></p>
+          <c><![CDATA[file:delete/1]]></c>.</p>
       </desc>
     </func>
     <func>
-      <name>make_dir(ChannelPid, Name) -> </name>
+      <name>make_dir(ChannelPid, Name) -></name>
       <name>make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Create a directory</fsummary>
+      <fsummary>Creates a directory.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -593,15 +603,15 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c> should
-          be a full path to a new directory. The directory can only be
+        <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c>
+          must be a full path to a new directory. The directory can only be
           created in an existing directory.</p>
       </desc>
     </func>
     <func>
-      <name>del_dir(ChannelPid, Name) -> </name>
+      <name>del_dir(ChannelPid, Name) -></name>
       <name>del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Delete an empty directory</fsummary>
+      <fsummary>Deletes an empty directory.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -610,7 +620,7 @@
       </type>
       <desc>
 	<p>Deletes a directory specified by <c><![CDATA[Name]]></c>.
-	Note that the directory must be empty before it can be successfully deleted
+	The directory must be empty before it can be successfully deleted.
 	</p>
       </desc>
     </func>
diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml
index 81c2acc575..bc2660f595 100644
--- a/lib/ssh/doc/src/ssh_sftpd.xml
+++ b/lib/ssh/doc/src/ssh_sftpd.xml
@@ -22,67 +22,73 @@
     </legalnotice>
 
     <title>ssh_sftpd</title>
+    <prepared></prepared>
+    <docno></docno>
     <date>2005-09-22</date>
+    <rev></rev>
     <file>ssh_sftpd.sgml</file>
   </header>
   <module>ssh_sftpd</module>
-  <modulesummary>Specifies the channel process to handle an sftp subsystem.</modulesummary>
+  <modulesummary>Specifies the channel process to handle an SFTP subsystem.</modulesummary>
   <description>
-    <p>Specifies a channel process to handle a sftp subsystem.</p>
+    <p>Specifies a channel process to handle an SFTP subsystem.</p>
   </description>
 
   <section>
-    <title>DATA TYPES </title>
-    <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>
-    <p><c>subsystem_name() =  "sftp"</c></p>
-    <p><c>channel_callback() = atom()</c> - Name of the erlang module implementing the
-    subsystem using the ssh_channel behavior see
-    <seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
-    <p><c> channel_init_args() = list() - The one given as argument to function
-    subsystem_spec/1.</c></p>  
+    <title>DATA TYPES</title>
+    <taglist>
+      <tag><c>subsystem_spec()</c></tag>
+      <item><p>= <c>{subsystem_name(), {channel_callback(), channel_init_args()}}</c></p></item>
+      <tag><c>subsystem_name()</c></tag>
+      <item><p>= <c>"sftp"</c></p></item>
+      <tag><c>channel_callback()</c></tag>
+      <item><p>= <c>atom()</c> - Name of the Erlang module implementing the subsystem using the
+      <c>ssh_channel</c> behavior, see the
+      <seealso marker="ssh_channel">ssh_channel(3)</seealso> manual page.</p></item>
+      <tag><c>channel_init_args()</c></tag>
+      <item><p>= <c>list()</c> - The one given as argument to function <c>subsystem_spec/1</c>.</p></item>
+    </taglist>
   </section>
   <funcs>
     <func>
       <name>subsystem_spec(Options) -> subsystem_spec()</name>
-      <fsummary>Returns the subsystem specification that allows an ssh daemon to handle the subsystem "sftp".</fsummary>
+      <fsummary>Returns the subsystem specification that allows an SSH daemon to handle the subsystem "sftp".</fsummary>
       <type>
 	<v>Options = [{Option, Value}]</v>
       </type>
       <desc>
-        <p>Should be used together with ssh:daemon/[1,2,3]</p>
-        <p>Options are:</p>
+        <p>Is to be used together with <c>ssh:daemon/[1,2,3]</c></p>
+        <p>Options:</p>
         <taglist>
           <tag><c><![CDATA[{cwd, String}]]></c></tag>
           <item>
-            <p>Sets the initial current working directory for the
-              server.</p>
+            <p>Sets the initial current working directory for the server.</p>
           </item>
           <tag><c><![CDATA[{file_handler, CallbackModule}]]></c></tag>
           <item>
 	    <p>Determines which module to call for accessing
-	    the file server. The default value is <c>ssh_sftpd_file</c> that uses the
-	    <seealso marker="kernel:file">file</seealso> and <seealso marker="stdlib:filelib">filelib</seealso> API:s to access the standard OTP file
-	    server. This option may be used to plug in
+	    the file server. The default value is <c>ssh_sftpd_file</c>, which uses the
+	    <seealso marker="kernel:file">file</seealso> and <seealso marker="stdlib:filelib">filelib</seealso>
+	    APIs to access the standard OTP file server. This option can be used to plug in
 	    other file servers.</p>
 	  </item>
 	  <tag><c><![CDATA[{max_files, Integer}]]></c></tag>
 	  <item>
 	    <p>The default value is <c>0</c>, which means that there is no upper limit.
-	    If supplied, the number of filenames returned to the sftp client per <c>READDIR</c>
+	    If supplied, the number of filenames returned to the SFTP client per <c>READDIR</c>
 	    request is limited to at most the given value.</p>
 	  </item>
 	  <tag><c><![CDATA[{root, String}]]></c></tag>
 	  <item>
-	    <p>Sets the sftp root directory. The user will then not be
-	    able to see any files above this root. If for instance
-	    the root is set to <c>/tmp</c> the user will see this
-	    directory as <c>/</c> and if the user does cd <c>/etc</c>
-	    the user will end up in <c>/tmp/etc</c>.
+	    <p>Sets the SFTP root directory. Then the user cannot see any files
+	    above this root. If, for example, the root directory is set to <c>/tmp</c>,
+	    then the user sees this directory as <c>/</c>. If the user then writes
+	    <c>cd /etc</c>, the user moves to <c>/tmp/etc</c>.
 	    </p>
 	  </item>
 	  <tag><c><![CDATA[{sftpd_vsn, integer()}]]></c></tag>
 	  <item>
-	    <p>Sets the sftp version to use, defaults to 5. Version 6 is under
+	    <p>Sets the SFTP version to use. Defaults to 5. Version 6 is under
 	    development and limited.</p>
 	  </item>
         </taglist>
diff --git a/lib/ssh/doc/src/usersguide.xml b/lib/ssh/doc/src/usersguide.xml
index 8ab14c2945..a9ed5fe21e 100644
--- a/lib/ssh/doc/src/usersguide.xml
+++ b/lib/ssh/doc/src/usersguide.xml
@@ -23,15 +23,16 @@
 
     <title>SSH User's Guide</title>
     <prepared>OTP Team</prepared>
+    <docno></docno>
     <date>2012-10-11</date>
+    <rev></rev>
     <file>usersguide.xml</file>
   </header>
   <description>
-    <p>The <em>SSH</em> application implements the SSH (Secure Shell) protocol and
-    provides an SFTP (Secret File Transfer Protocol) client and server.
+    <p>The Erlang Secure Shell (SSH) application, <c>ssh</c>, implements the SSH Transport Layer Protocol and
+    provides SSH File Transfer Protocol (SFTP) clients and servers.
     </p>
   </description>
   <xi:include href="introduction.xml"/>
-  <xi:include href="ssh_protocol.xml"/>
   <xi:include href="using_ssh.xml"/>
 </part>
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 46178d4018..5873e03f23 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -22,35 +22,40 @@
 
     </legalnotice>
 
-    <title>Getting started</title>
+    <title>Getting Started</title>
+    <prepared></prepared>
+    <docno></docno>
+    <approved></approved>
+    <date></date>
+    <rev></rev>
     <file>using_ssh.xml</file>
   </header>
 
   <section>
-    <title> General information</title>
-    <p>The examples in the following sections use the utility function
-    <seealso marker="ssh#start-0"> ssh:start/0 </seealso> that starts
-    all needed applications (crypto, public_key and ssh). All examples
-    are run in an Erlang shell, or in a bash shell using openssh to
-    illustrate how the erlang ssh application can be used.  The
-    examples are run as the user otptest on a local network where the
-    user is authorized to login in over ssh to the host "tarlop". If
-    nothing else is stated it is persumed that the otptest user has an
-    entry in tarlop's authorized_keys file (may log in via ssh without
-    entering a password).  Also tarlop is a known host in the user
-    otptest's known_hosts file so that host verification can be done
-    without user interaction.
+    <title>General Information</title>
+    <p>The following examples use the utility function
+    <seealso marker="ssh#start-0"> ssh:start/0</seealso> to start
+    all needed applications (<c>crypto</c>, <c>public_key</c>, and <c>ssh</c>).
+    All examples are run in an Erlang shell, or in a bash shell, using <em>openssh</em>
+    to illustrate how the <c>ssh</c> application can be used. The
+    examples are run as the user <c>otptest</c> on a local network where the
+    user is authorized to log in over <c>ssh</c> to the host <em>tarlop</em>.
+    </p>
+    <p>If nothing else is stated, it is presumed that the <c>otptest</c> user
+    has an entry in the <em>authorized_keys</em> file of <em>tarlop</em>
+    (allowed to log in over <c>ssh</c> without entering a password).
+    Also, <em>tarlop</em> is a known host in the <c>known_hosts</c>
+    file of the user <c>otptest</c>. This means that host-verification
+    can be done without user-interaction.
     </p>
   </section>
 
   <section>
-    <title>Using the Erlang SSH Terminal Client</title>
+    <title>Using the Erlang ssh Terminal Client</title>
 
-    <p>The user otptest, that has bash as default shell, uses the
-    ssh:shell/1 client to connect to the openssh daemon running on a
-    host called tarlop. Note that currently this client is very simple
-    and you should not be expected to be as fancy as the openssh
-    client.</p>
+    <p>The user <c>otptest</c>, which has bash as default shell, uses the
+    <c>ssh:shell/1</c> client to connect to the <em>openssh</em> daemon running on a
+    host called <em>tarlop</em>:</p>
 
     <code type="erl" >
       1>  ssh:start().
@@ -62,24 +67,27 @@
       logout
       3>
     </code>
+    <p>Notice that this is a simple client that is not expected to be as
+    fancy as the <em>openssh</em> client.</p>
   </section>
 
   <section>
-    <title>Running an Erlang SSH Daemon </title>
+    <marker id="Running an Erlang ssh Daemon"></marker>
+    <title>Running an Erlang ssh Daemon</title>
 
-    <p> The option system_dir must be a directory containing a host
-    key file and it defaults to /etc/ssh. For details see section
+    <p>The <c>system_dir</c> option must be a directory containing a host
+    key file and it defaults to <c>/etc/ssh</c>. For details, see Section
     Configuration Files in <seealso
     marker="SSH_app">ssh(6)</seealso>.
     </p>
 
-    <note><p>Normally the /etc/ssh directory is only readable by root. </p>
+    <note><p>Normally, the <c>/etc/ssh</c> directory is only readable by root.</p>
     </note>
 
-    <p> The option user_dir defaults to the users ~/.ssh  directory</p>
+    <p>The option <c>user_dir</c> defaults to directory <c>users ~/.ssh</c>.</p>
 
-    <p>In the following example we generate new keys and host keys as
-    to be able to run the example without having root privileges</p>
+    <p><em>Step 1.</em> To run the example without root privileges,
+    generate new keys and host keys:</p>
 
     <code>
       $bash> ssh-keygen -t rsa -f /tmp/ssh_daemon/ssh_host_rsa_key
@@ -88,8 +96,10 @@
       [...]
     </code>
 
-    <p>Create the file /tmp/otptest_user/.ssh/authorized_keys and add the content
-    of /tmp/otptest_user/.ssh/id_rsa.pub  Now we can do</p>
+    <p><em>Step 2.</em> Create the file <c>/tmp/otptest_user/.ssh/authorized_keys</c>
+    and add the content of <c>/tmp/otptest_user/.ssh/id_rsa.pub</c>.</p>
+
+    <p><em>Step 3.</em> Start the Erlang <c>ssh</c> daemon:</p>
 
     <code type="erl">
       1> ssh:start().
@@ -100,7 +110,8 @@
       3>
     </code>
 
-    <p>Use the openssh client from a shell to connect to the Erlang ssh daemon.</p>
+    <p><em>Step 4.</em> Use the <em>openssh</em> client from a shell to connect
+    to the Erlang <c>ssh</c> daemon:</p>
 
     <code>
       $bash> ssh tarlop -p 8989  -i /tmp/otptest_user/.ssh/id_rsa\
@@ -113,9 +124,12 @@
       1>
     </code>
 
-    <p>There are two ways of shutting down an SSH daemon</p>
+    <p>There are two ways of shutting down an <c>ssh</c> daemon,
+    see <em>Step 5a</em> and <em>Step 5b</em>.</p>
 
-    <p>1: Stops the listener, but leaves existing connections started by the listener up and running.</p>
+    <p><em>Step 5a.</em> Shut down the Erlang <c>ssh</c> daemon so that it
+    stops the listener but leaves existing connections, started by the listener,
+    operational:</p>
 
     <code type="erl">
       3> ssh:stop_listener(Sshd).
@@ -123,7 +137,8 @@
       4>
     </code>
 
-    <p>2: Stops the listener and all connections started by the listener.</p>
+    <p><em>Step 5b.</em> Shut down the Erlang <c>ssh</c> daemon so that it
+    stops the listener and all connections started by the listener:</p>
 
     <code type="erl">
       3> ssh:stop_daemon(Sshd)
@@ -134,16 +149,17 @@
   </section>
 
   <section>
-    <title>One Time Execution</title>
+    <title>One-Time Execution</title>
+
+    <p>In the following example, the Erlang shell is the client process
+    that receives the channel replies.</p>
 
-    <p>In the following example the Erlang shell is the client process
-    that receives the channel replies. </p>
+    <note><p>The number of received messages in this example depends on which OS
+    and which shell that is used on the machine running the <c>ssh</c> daemon.
+    See also <seealso marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso>
+    </p>.</note>
 
-    <note><p> If you run this example
-    in your environment you may get fewer or more messages back as
-    this depends on the OS and shell on the machine running the ssh
-    daemon. See also <seealso marker="ssh_connection#exec-4">ssh_connection:exec/4</seealso>
-    </p></note>
+    <p>Do a one-time execution of a remote command over <c>ssh</c>:</p>
 
     <code type="erl" >
       1>  ssh:start().
@@ -162,7 +178,8 @@
       6>
     </code>
 
-    <p>Note only the channel is closed the connection is still up and can handle other channels</p>
+    <p>Notice that only the channel is closed. The connection is still up and can
+    handle other channels:</p>
 
     <code type="erl" >
       6> {ok, NewChannelId} =  ssh_connection:session_channel(ConnectionRef, infinity).
@@ -172,7 +189,9 @@
   </section>
 
   <section>
-    <title>SFTP (SSH File Transport Protocol) server</title>
+    <title>SFTP Server</title>
+
+    <p>Start the Erlang <c>ssh</c> daemon with the SFTP subsystem:</p>
 
     <code type="erl" >
       1> ssh:start().
@@ -184,7 +203,7 @@
       3>
     </code>
 
-    <p> Run the openssh sftp client</p>
+    <p>Run the OpenSSH SFTP client:</p>
 
     <code type="erl">
       $bash> sftp -oPort=8989 -o IdentityFile=/tmp/otptest_user/.ssh/id_rsa\
@@ -197,7 +216,9 @@
   </section>
 
   <section>
-    <title>SFTP (SSH File Transport Protocol) client</title>
+    <title>SFTP Client</title>
+
+    <p>Fetch a file with the Erlang SFTP client:</p>
 
     <code type="erl" >
       1> ssh:start().
@@ -210,10 +231,10 @@
   </section>
 
   <section>
-    <title>Creating a subsystem</title>
+    <title>Creating a Subsystem</title>
 
-    <p>A very small SSH subsystem that echos N bytes could be implemented like this.
-    See also <seealso marker="ssh_channel"> ssh_channel(3)</seealso> </p>
+    <p>A small <c>ssh</c> subsystem that echoes N bytes can be implemented as shown
+    in the following example:</p>
 
     <code type="erl" >
 -module(ssh_echo_server).
@@ -267,7 +288,9 @@ terminate(_Reason, _State) ->
     ok.
  </code>
 
- <p>And run like this on the host tarlop with the keys generated in section 3.3</p>
+ <p>The subsystem can be run on the host <em>tarlop</em> with the generated keys,
+ as described in Section <seealso marker="#Running an Erlang ssh Daemon">
+ Running an Erlang ssh Daemon</seealso>:</p>
 
  <code type="erl" >
    1> ssh:start().
@@ -293,6 +316,7 @@ terminate(_Reason, _State) ->
    {ssh_msg, &lt;0.57.0>, {closed, 0}}
    7> {error, closed} = ssh_connection:send(ConnectionRef, ChannelId, "10", infinity).
  </code>
+<p>See also <seealso marker="ssh_channel"> ssh_channel(3)</seealso>.</p>
 
 </section>