Editorial updates

SSH application

1 files changed, 73 insertions, 49 deletions

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>