Add description of File|Import option.

svn path=/trunk/; revision=34983

3 files changed, 193 insertions, 1 deletions

diff --git a/docbook/wsug_graphics/ws-file-import.png b/docbook/wsug_graphics/ws-file-import.png
new file mode 100644
index 0000000000..178afc0915
--- /dev/null
+++ b/docbook/wsug_graphics/ws-file-import.png
diff --git a/docbook/wsug_src/WSUG_chapter_io.xml b/docbook/wsug_src/WSUG_chapter_io.xml
index 0d24fbe85b..ea78712127 100644
--- a/docbook/wsug_src/WSUG_chapter_io.xml
+++ b/docbook/wsug_src/WSUG_chapter_io.xml
@@ -681,7 +681,190 @@
 
 	</section>
   </section>
-  
+
+  <section id="ChIOImportSection"><title>Import text file</title>
+    <para>
+    Wireshark can read in an ASCII hex dump and write the data described 
+    into a temporary libpcap capture file. It can read hex dumps with multiple 
+    packets in them, and build a capture file of multiple packets. It is also 
+    capable of generating dummy Ethernet, IP and UDP, TCP, or SCTP headers, 
+    in order to build fully processable packet dumps from hexdumps of 
+    application-level data only.
+    </para>
+    <para>
+    Wireshark understands a hexdump of the form generated by 
+    <command>od -Ax -tx1 -v</command>.
+    In other words, each byte is individually displayed and surrounded with a space.
+    Each line begins with an offset describing the position in the file. The offset
+    is a hex number (can also be octal or decimal), of more than two hex
+    digits.  Here is a sample dump that can be imported:
+    </para>
+    <programlisting>
+           000000 00 e0 1e a7 05 6f 00 10 ........
+           000008 5a a0 b9 12 08 00 46 00 ........
+           000010 03 68 00 00 00 00 0a 2e ........
+           000018 ee 33 0f 19 08 7f 0f 19 ........
+           000020 03 80 94 04 00 00 10 01 ........
+           000028 16 a2 0a 00 03 50 00 0c ........
+           000030 01 01 0f 19 03 80 11 01 ........
+    </programlisting>
+    <para>
+    There is no limit on the width or number of bytes per line. Also the text dump at
+    the end of the line is ignored. Bytes/hex numbers can be uppercase or lowercase.
+    Any text before the offset is ignored, including email forwarding characters '>'.
+    Any lines of text between the bytestring lines is ignored. The offsets are used
+    to track the bytes, so offsets must be correct. Any line which has only bytes
+    without a leading offset is ignored. An offset is recognized as being a hex
+    number longer than two characters. Any text after the bytes is ignored (e.g. the
+    character dump). Any hex numbers in this text are also ignored. An offset of zero
+    is indicative of starting a new packet, so a single text file with a series of
+    hexdumps can be converted into a packet capture with multiple packets. Packets may
+    be preseded by a timestamp. These are interpreted according to the format
+    given. If not the first packet is timestamped with the current time the import
+    takes place. Multiple packets are read in with timestamps differing by one
+    microsecond each. In general, short of these restrictions, Wireshark is pretty
+    liberal about reading in hexdumps and has been tested with a variety of mangled
+    outputs (including being forwarded through email multiple times, with limited
+    line wrap etc.)
+    </para>
+    <para>
+    There are a couple of other special features to note. Any line where the first
+    non-whitespace character is '#' will be ignored as a comment. Any line beginning
+    with #TEXT2PCAP is a directive and options can be inserted after this command to
+    be processed by Wireshark. Currently there are no directives implemented; in the
+    future, these may be used to give more fine grained control on the dump and the
+    way it should be processed e.g. timestamps, encapsulation type etc.
+    Wireshark also allows the user to read in dumps of application-level data, by
+    inserting dummy L2, L3 and L4 headers before each packet. The user can elect to
+    insert Ethernet headers, Ethernet and IP, or Ethernet, IP and UDP/TCP/SCTP headers
+    before each packet. This allows Wireshark or any other full-packet decoder to
+    handle these dumps.
+    </para>
+  	<section id="ChIOImportDialog">
+	  <title>The "File import" dialog box</title>
+	  <para>
+	  This dialog box lets you select a file to be imported and set import parameters.
+	  </para>
+	  <para>
+    <figure id="ChIOFileImportDialog">
+      <title>The "File Import" dialog</title>
+      <graphic entityref="WiresharkFileImportDialog" format="PNG"/>
+    </figure>
+    </para>
+    <para>
+    Specific controls of this import dialog are split in two sections:
+        <variablelist>
+        <varlistentry>
+        <term>Input</term>
+        <listitem><para>Determine which input file has to be imported and 
+        how it is to be interpreted.
+        </para></listitem>
+        </varlistentry>
+        <varlistentry>
+        <term>Import</term>
+        <listitem><para>Determine how the data is to be imported.</para></listitem>
+        </varlistentry>
+        </variablelist>
+    </para>
+	  <para>
+	  The input parameters are as follows:
+	  </para>
+    <variablelist>
+    <varlistentry>
+      <term><command>Filename / Browse</command></term>
+      <listitem>
+      <para>
+      Enter the name of the text file to import. You can use 
+      <command>Browse</command> to browse for a file.
+      </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><command>Offsets</command></term>
+      <listitem>
+      <para>
+      Select the radix of the offsets given in the text file to import. 
+      This is usually hexadecimal, but decimal and octal are also supported.
+      </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><command>Date/Time</command></term>
+      <listitem>
+      <para>
+      Tick this checkbox if there are timestamps associated with the frames 
+      in the text file to import you would like to use. Otherwise the current time
+      is used for timestamping the frames.
+      </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><command>Format</command></term>
+      <listitem>
+      <para>
+      This is the format specifier used to parse the timestamps in the text file 
+      to import. It uses a simple syntax to describe the format of the timestamps,
+      using %H for hours, %M for minutes, %S for seconds, etc. The straightforward
+      HH:MM:SS format is covered by %T. For a full definition of the syntax look for 
+      <command>strftime(3)</command>.
+      </para>
+      </listitem>
+    </varlistentry>
+    </variablelist>
+	  <para>
+	  The import parameters are as follows:
+	  </para>
+    <variablelist>
+    <varlistentry>
+      <term><command>Encapsulation type</command></term>
+      <listitem>
+      <para>
+      Here you can select which type of frames you are importing. This all depends on
+      from what type of medium the dump to import was taken. It lists all types that 
+      Wirshark understands, so as to pass the capture file contents to the right dissector.
+      </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><command>Dummy header</command></term>
+      <listitem>
+      <para>
+      When Ethernet encapsulation is selected you have to option to prepend dummy
+      headers to the frames to import. These headers can provide artificial Ethernet, IP,
+      UDP or TCP or SCTP headers and SCTP data chunks. When selecting a type of dummy
+      header the applicable entries are enabled, others are grayed out and default values 
+      are used.
+      </para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><command>Max. frame length</command></term>
+      <listitem>
+      <para>
+      You may not be interested in the full frames from the text file, just the first part. 
+      Here you can define how much data from the start of the frame you want to import.
+      If you leave this open the maximum is set to 64000 bytes.
+      </para>
+      </listitem>
+    </varlistentry>
+    </variablelist>
+    <para>
+    Once all input and import parameters are setup click <command>OK</command>
+    to start the import.
+    </para>
+    <para>
+	  <note><title>You will be prompted for an unsaved file first!</title>
+	  <para>If your current data wasn't saved before, you will be asked to save 
+    it first, before this dialog box is shown.</para>
+    </note>
+    </para>
+    <para>
+    When completed there will be a new capture file loaded with the frames imported 
+    from the text file.
+    </para>
+  </section>
+  </section>
+
   <section id="ChIOFileSetSection"><title>File Sets</title>
     <para>
       When using the "Multiple Files" option while doing a capture
diff --git a/docbook/wsug_src/WSUG_chapter_use.xml b/docbook/wsug_src/WSUG_chapter_use.xml
index f124a90e0e..9e5ba0610f 100644
--- a/docbook/wsug_src/WSUG_chapter_use.xml
+++ b/docbook/wsug_src/WSUG_chapter_use.xml
@@ -425,6 +425,15 @@
 		  </para></entry>
 	      </row>
 	      <row>
+		<entry><command>Import...</command></entry>
+		<entry></entry>
+		<entry><para>
+		    This menu item brings up the import file dialog box that
+		    allows you to import a text file into a new temporary capture.
+			It is discussed in more detail in <xref linkend="ChIOImportSection"/>.
+		  </para></entry>
+	      </row>
+	      <row>
 		<entry><command>Close</command></entry>
 		<entry>Ctrl+W</entry>
 		<entry><para>