tftp: Improve documentation

Change-Id: Ie23a40e7159fe632cf5514ac617de17c5d5b5ce2

6 files changed, 103 insertions, 48 deletions

diff --git a/lib/tftp/doc/src/Makefile b/lib/tftp/doc/src/Makefile
index cd97bdf7ff..a2fdcf6325 100644
--- a/lib/tftp/doc/src/Makefile
+++ b/lib/tftp/doc/src/Makefile
@@ -40,13 +40,14 @@ XML_APPLICATION_FILES = ref_man.xml
 
 XML_CHAPTER_FILES = \
 	introduction.xml \
+	getting_started.xml \
 	notes.xml
 
 XML_REF3_FILES = \
 	tftp.xml
 
 XML_PART_FILES = \
-	part.xml
+	usersguide.xml
 
 BOOK_FILES = book.xml
 
diff --git a/lib/tftp/doc/src/book.xml b/lib/tftp/doc/src/book.xml
index cf8032a4e9..c0b551d517 100644
--- a/lib/tftp/doc/src/book.xml
+++ b/lib/tftp/doc/src/book.xml
@@ -36,7 +36,7 @@
     <contents level="2"></contents>
   </preamble>
   <parts lift="no">
-    <xi:include href="part.xml"/>
+    <xi:include href="usersguide.xml"/>
   </parts>
   <applications>
     <xi:include href="ref_man.xml"/>
diff --git a/lib/tftp/doc/src/getting_started.xml b/lib/tftp/doc/src/getting_started.xml
new file mode 100644
index 0000000000..9bce52dbe0
--- /dev/null
+++ b/lib/tftp/doc/src/getting_started.xml
@@ -0,0 +1,81 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year>
+      <year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>Getting Started</title>
+    <prepared></prepared>
+    <docno></docno>
+    <approved></approved>
+    <date></date>
+    <rev></rev>
+    <file>getting_started.xml</file>
+  </header>
+
+  <section>
+    <title>General Information</title>
+    <p>The <seealso marker="tftp#start/1">start/1</seealso> function starts
+      a daemon process listening for UDP packets on a port. When it
+      receives a request for read or write, it spawns a temporary server
+      process handling the transfer.</p>
+    <p>On the client side,
+      function <seealso marker="tftp#read_file/3">read_file/3</seealso>
+      and <seealso marker="tftp#write_file/3">write_file/3</seealso>
+      spawn a temporary client process establishing
+      contact with a TFTP daemon and perform the file transfer.</p>
+    <p><c>tftp</c> uses a callback module to handle the file
+      transfer. Two such callback modules are provided,
+      <c>tftp_binary</c> and <c>tftp_file</c>. See
+      <seealso marker="tftp#read_file/3">read_file/3</seealso> and
+      <seealso marker="tftp#write_file/3">write_file/3</seealso> for details.
+      You can also implement your own callback modules, see
+      <seealso marker="tftp#tftp_callback">CALLBACK FUNCTIONS</seealso>.
+      A callback module provided by
+      the user is registered using option <c>callback</c>, see
+    <seealso marker="tftp#options">DATA TYPES</seealso>.</p>
+  </section>
+
+  <section>
+    <title>Using the TFTP client and server</title>
+    <p>This is a simple example of starting the TFTP server and reading the content
+    of a sample file using the TFTP client.</p>
+
+    <p><em>Step 1.</em> Create a sample file to be used for the transfer:</p>
+    <code>
+      $ echo "Erlang/OTP 21" > file.txt
+    </code>
+
+    <p><em>Step 2.</em> Start the TFTP server:</p>
+    <code type="erl" >
+      1> {ok, Pid} = tftp:start([{port, 19999}]).
+      <![CDATA[{ok,<0.65.0>}]]>
+    </code>
+
+    <p><em>Step 3.</em> Start the TFTP client (in another shell):</p>
+    <code type="erl" >
+      1> tftp:read_file("file.txt", binary, [{port, 19999}]).
+      <![CDATA[{ok,<<"Erlang/OTP 21\n">>}]]>
+    </code>
+  </section>
+
+</chapter>
diff --git a/lib/tftp/doc/src/introduction.xml b/lib/tftp/doc/src/introduction.xml
index 949438ae92..70761db0dc 100644
--- a/lib/tftp/doc/src/introduction.xml
+++ b/lib/tftp/doc/src/introduction.xml
@@ -34,7 +34,23 @@
 
   <section>
     <title>Purpose</title>
-    <p>A <c>TFTP</c> client and server.</p>
+    <p>The Trivial File Transfer Protocol or TFTP is a very simple protocol
+    used to transfer files.</p>
+    <p>It has been implemented on top of the User Datagram protocol (UDP) so
+    it may be used to move files between machines on different networks
+    implementing UDP. It is designed to be small and easy to implement.
+    Therefore, it lacks most of the features of a regular FTP.  The only
+    thing it can do is read and write files (or mail) from/to a remote server.
+    It cannot list directories, and currently has no provisions for user
+    authentication.</p>
+    <p>The <c>tftp</c> application implements the following IETF standards:</p>
+    <list type="bulleted">
+      <item>RFC 1350, The TFTP Protocol (revision 2)</item>
+      <item>RFC 2347, TFTP Option Extension</item>
+      <item>RFC 2348, TFTP Blocksize Option</item>
+      <item>RFC 2349, TFTP Timeout Interval and Transfer Size Options</item>
+    </list>
+    <p>The only feature that not is implemented is the <c>netascii</c> transfer mode.</p>
   </section>
 
   <section>
diff --git a/lib/tftp/doc/src/tftp.xml b/lib/tftp/doc/src/tftp.xml
index c4d6a4e6d0..481e5446ad 100644
--- a/lib/tftp/doc/src/tftp.xml
+++ b/lib/tftp/doc/src/tftp.xml
@@ -31,53 +31,9 @@
   <module>tftp</module>
   <modulesummary>Trivial FTP.</modulesummary>
   <description>
-    <p>This is a complete implementation of the following IETF standards:</p>
-    <list type="bulleted">
-      <item>RFC 1350, The TFTP Protocol (revision 2)</item>
-      <item>RFC 2347, TFTP Option Extension</item>
-      <item>RFC 2348, TFTP Blocksize Option</item>
-      <item>RFC 2349, TFTP Timeout Interval and Transfer Size Options</item>
-    </list>
-    <p>The only feature that not is implemented is
-      the "netascii" transfer mode.</p>
-    <p>The <seealso marker="#start/1">start/1</seealso> function starts
-      a daemon process listening for UDP packets on a port. When it
-      receives a request for read or write, it spawns a temporary server
-      process handling the transfer.</p>
-    <p>On the client side,
-      function <seealso marker="#read_file/3">read_file/3</seealso>
-      and <seealso marker="#write_file/3">write_file/3</seealso>
-      spawn a temporary client process establishing
-      contact with a TFTP daemon and perform the file transfer.</p>
-    <p><c>tftp</c> uses a callback module to handle the file
-      transfer. Two such callback modules are provided,
-      <c>tftp_binary</c> and <c>tftp_file</c>. See
-      <seealso marker="#read_file/3">read_file/3</seealso> and
-      <seealso marker="#write_file/3">write_file/3</seealso> for details.
-      You can also implement your own callback modules, see 
-      <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>. 
-      A callback module provided by
-      the user is registered using option <c>callback</c>, see
-      <seealso marker="#options">DATA TYPES</seealso>.</p>
+    <p>Interface module for the <c>tftp</c> application.</p>
   </description>
-  
- <section>
-    <title>TFTP SERVER SERVICE START/STOP</title>
-    
-    <p>A TFTP server can be started dynamically
-      (when <c>tftp</c> is already started) by calling the <c>tftp</c> application 
-      API <c>tftp:start(ServiceConfig)</c>.
-      The <c>ServiceConfig</c> for TFTP is described in
-      the <seealso marker="#options">DATA TYPES</seealso>
-      section.</p>
-    
-    <p>The TFTP server can be stopped using <c>tftp:stop_service(Pid)</c>.</p>
 
-    <p>The TPFT client is of such a temporary nature that it is not
-      handled as a service in the <c>tftp</c> service framework.</p>
-    
-  </section>
-  
   <section>
     <marker id="options"></marker>
     <title>DATA TYPES</title>
diff --git a/lib/tftp/doc/src/part.xml b/lib/tftp/doc/src/usersguide.xml
index abbe0edcbf..eb7f7d17c3 100644
--- a/lib/tftp/doc/src/part.xml
+++ b/lib/tftp/doc/src/usersguide.xml
@@ -33,4 +33,5 @@
     <p>The <c>TFTP</c> application provides a TFTP client and server.</p>
   </description>
   <xi:include href="introduction.xml"/>
+  <xi:include href="getting_started.xml"/>
 </part>