Merge branch 'ia/ssh/improve_docs'

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

1 files changed, 71 insertions, 51 deletions

diff --git a/lib/ssh/doc/src/ssh_app.xml b/lib/ssh/doc/src/ssh_app.xml
index a1d2402790..1dfe68b17d 100644
--- a/lib/ssh/doc/src/ssh_app.xml
+++ b/lib/ssh/doc/src/ssh_app.xml
@@ -18,83 +18,103 @@
       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 <seealso marker="kernel:application">application(3)</seealso>.
+    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 uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors or print information about special events.</p>
   </section>
 
   <section>
     <title>SEE ALSO</title>
-    <p>application(3)</p>
+    <p><seealso marker="kernel:application">application(3)</seealso></p>
   </section>
 
 </appref>