first step to fix the file dialog "mess":

- use different screenshots for: GTK1, GTK2 and Win32
- rewrite the "File Open Dialog" section

svn path=/trunk/; revision=19239

13 files changed, 190 insertions, 67 deletions

diff --git a/docbook/Makefile b/docbook/Makefile
index 2029eeed9d..882677e58e 100644
--- a/docbook/Makefile
+++ b/docbook/Makefile
@@ -117,9 +117,13 @@ WSUG_GRAPHICS =	\
 	wsug_graphics/ws-list-pane.png			\
 	wsug_graphics/ws-main-toolbar.png		\
 	wsug_graphics/ws-menu.png			\
-	wsug_graphics/ws-merge.png			\
+	wsug_graphics/ws-merge-gtk1.png			\
+	wsug_graphics/ws-merge-gtk2.png			\
+	wsug_graphics/ws-merge-win32.png		\
 	wsug_graphics/ws-nameresolution-preferences.png	\
-	wsug_graphics/ws-open.png			\
+	wsug_graphics/ws-open-gtk1.png			\
+	wsug_graphics/ws-open-gtk2.png			\
+	wsug_graphics/ws-open-win32.png			\
 	wsug_graphics/ws-packet-format.png		\
 	wsug_graphics/ws-packet-pane-popup-menu.png	\
 	wsug_graphics/ws-packet-range.png		\
@@ -127,7 +131,9 @@ WSUG_GRAPHICS =	\
 	wsug_graphics/ws-packet-sep-win.png		\
 	wsug_graphics/ws-print.png			\
 	wsug_graphics/ws-printing-preferences.png	\
-	wsug_graphics/ws-save-as.png			\
+	wsug_graphics/ws-save-as-gtk1.png		\
+	wsug_graphics/ws-save-as-gtk2.png		\
+	wsug_graphics/ws-save-as-win32.png		\
 	wsug_graphics/ws-statistics-menu.png		\
 	wsug_graphics/ws-stats-conversations.png	\
 	wsug_graphics/ws-stats-endpoints.png		\
@@ -407,7 +413,7 @@ release-notes.html: $(RELEASE_NOTES_SOURCE)
 	@ echo --- RELEASE NOTES - HTML ---
 	$(XSLTPROC) --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< > $@
 
-# create txt single page file
+# create txt single page file (through HTML)
 release-notes.txt: $(RELEASE_NOTES_SOURCE)
 	@ echo --- RELEASE NOTES - TXT ---
 	$(XSLTPROC) --stringparam generate.toc "article nop" --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $< | $(HTML2TXT) > $@
diff --git a/docbook/user-guide.xml b/docbook/user-guide.xml
index f19065bac3..c9880c84b2 100644
--- a/docbook/user-guide.xml
+++ b/docbook/user-guide.xml
@@ -148,8 +148,6 @@ FILE SECTION
   <!ENTITY WiresharkStatusbarEmpty SYSTEM "./wsug_graphics/ws-statusbar-empty.png" NDATA PNG>
   <!ENTITY WiresharkStatusbarLoaded SYSTEM "./wsug_graphics/ws-statusbar-loaded.png" NDATA PNG>
   <!ENTITY WiresharkStatusbarSelected SYSTEM "./wsug_graphics/ws-statusbar-selected.png" NDATA PNG>
-  <!ENTITY WiresharkSaveAs SYSTEM "./wsug_graphics/ws-save-as.png" NDATA PNG>
-  <!ENTITY WiresharkOpen SYSTEM "./wsug_graphics/ws-open.png" NDATA PNG> 
   <!ENTITY WiresharkPacketSelected1 SYSTEM "./wsug_graphics/ws-packet-selected.png" NDATA PNG>
   <!ENTITY WiresharkPacketSepView SYSTEM "./wsug_graphics/ws-packet-sep-win.png" NDATA PNG>
   <!ENTITY WiresharkFilterTCP SYSTEM "./wsug_graphics/ws-display-filter-tcp.png" NDATA PNG>  
@@ -160,7 +158,6 @@ FILE SECTION
   <!ENTITY WiresharkFollowStream SYSTEM "./wsug_graphics/ws-follow-stream.png" NDATA PNG>
   <!ENTITY WiresharkFindPacket SYSTEM "./wsug_graphics/ws-find-packet.png" NDATA PNG>  
   <!ENTITY WiresharkGoToPacket SYSTEM "./wsug_graphics/ws-goto-packet.png" NDATA PNG>  
-  <!ENTITY WiresharkPrint SYSTEM "./wsug_graphics/ws-print.png" NDATA PNG>
   <!ENTITY WiresharkGUIPreferences SYSTEM "./wsug_graphics/ws-gui-preferences.png" NDATA PNG>
   <!ENTITY WiresharkGUILayoutPreferences SYSTEM "./wsug_graphics/ws-gui-layout-preferences.png" NDATA PNG>
   <!ENTITY WiresharkGUIColumnsPreferences SYSTEM "./wsug_graphics/ws-gui-columns-preferences.png" NDATA PNG>
@@ -183,22 +180,13 @@ FILE SECTION
   <!ENTITY WiresharkBytesPanePopupMenu SYSTEM "./wsug_graphics/ws-bytes-pane-popup-menu.png" NDATA PNG>
   <!ENTITY WiresharkFilterAddExpression SYSTEM "./wsug_graphics/ws-filter-add-expression.png" NDATA PNG>
   <!ENTITY WiresharkFilters2 SYSTEM "./wsug_graphics/ws-filters-2.png" NDATA PNG>
-  <!ENTITY WiresharkExportPlainDialog SYSTEM "./wsug_graphics/ws-export-plain.png" NDATA PNG>
-  <!ENTITY WiresharkExportPSDialog SYSTEM "./wsug_graphics/ws-export-ps.png" NDATA PNG>
-  <!ENTITY WiresharkExportPSMLDialog SYSTEM "./wsug_graphics/ws-export-psml.png" NDATA PNG>
-  <!ENTITY WiresharkExportPDMLDialog SYSTEM "./wsug_graphics/ws-export-pdml.png" NDATA PNG>
-  <!ENTITY WiresharkExportSelectedDialog SYSTEM "./wsug_graphics/ws-export-selected.png" NDATA PNG>
   <!ENTITY WiresharkCaptureInterfacesDialog SYSTEM "./wsug_graphics/ws-capture-interfaces.png" NDATA PNG>
   <!ENTITY WiresharkCaptureOptionsDialog SYSTEM "./wsug_graphics/ws-capture-options.png" NDATA PNG>
   <!ENTITY WiresharkCaptureInfoDialog SYSTEM "./wsug_graphics/ws-capture-info.png" NDATA PNG>
-  <!ENTITY WiresharkMergeDialog SYSTEM "./wsug_graphics/ws-merge.png" NDATA PNG>
-  <!ENTITY WiresharkPacketRangeFrame SYSTEM "./wsug_graphics/ws-packet-range.png" NDATA PNG>
-  <!ENTITY WiresharkPacketFormatFrame SYSTEM "./wsug_graphics/ws-packet-format.png" NDATA PNG>
   <!ENTITY WiresharkTimeReference SYSTEM "./wsug_graphics/ws-time-reference.png" NDATA PNG>
   <!ENTITY WiresharkEnabledProtocols SYSTEM "./wsug_graphics/ws-enabled-protocols.png" NDATA PNG>
   <!ENTITY WiresharkDecodeAs SYSTEM "./wsug_graphics/ws-decode-as.png" NDATA PNG>
   <!ENTITY WiresharkDecodeAsShow SYSTEM "./wsug_graphics/ws-decode-as-show.png" NDATA PNG>
-  <!ENTITY WiresharkFileSetDialog SYSTEM "./wsug_graphics/ws-file-set-dialog.png" NDATA PNG>
 
   <!-- Third Chapter Toolbar-->
   <!ENTITY WiresharkToolbarCaptureInterfaces SYSTEM "./wsug_graphics/toolbar/capture_interfaces_24.png" NDATA PNG>
@@ -245,6 +233,24 @@ FILE SECTION
   <!ENTITY WiresharkStatsSrtDcerpc SYSTEM "./wsug_graphics/ws-stats-srt-dcerpc.png" NDATA PNG>
 
   <!-- Fifth Chapter -->
+  <!ENTITY WiresharkOpenDialog1 SYSTEM "./wsug_graphics/ws-open-gtk1.png" NDATA PNG> 
+  <!ENTITY WiresharkSaveAsDialog1 SYSTEM "./wsug_graphics/ws-save-as-gtk1.png" NDATA PNG>
+  <!ENTITY WiresharkMergeDialog1 SYSTEM "./wsug_graphics/ws-merge-gtk1.png" NDATA PNG>
+  <!ENTITY WiresharkOpenDialog2 SYSTEM "./wsug_graphics/ws-open-gtk2.png" NDATA PNG> 
+  <!ENTITY WiresharkSaveAsDialog2 SYSTEM "./wsug_graphics/ws-save-as-gtk2.png" NDATA PNG>
+  <!ENTITY WiresharkMergeDialog2 SYSTEM "./wsug_graphics/ws-merge-gtk2.png" NDATA PNG>
+  <!ENTITY WiresharkOpenDialogWin32 SYSTEM "./wsug_graphics/ws-open-win32.png" NDATA PNG> 
+  <!ENTITY WiresharkSaveAsDialogWin32 SYSTEM "./wsug_graphics/ws-save-as-win32.png" NDATA PNG>
+  <!ENTITY WiresharkMergeDialogWin32 SYSTEM "./wsug_graphics/ws-merge-win32.png" NDATA PNG>
+  <!ENTITY WiresharkFileSetDialog SYSTEM "./wsug_graphics/ws-file-set-dialog.png" NDATA PNG>
+  <!ENTITY WiresharkExportPlainDialog SYSTEM "./wsug_graphics/ws-export-plain.png" NDATA PNG>
+  <!ENTITY WiresharkExportPSDialog SYSTEM "./wsug_graphics/ws-export-ps.png" NDATA PNG>
+  <!ENTITY WiresharkExportPSMLDialog SYSTEM "./wsug_graphics/ws-export-psml.png" NDATA PNG>
+  <!ENTITY WiresharkExportPDMLDialog SYSTEM "./wsug_graphics/ws-export-pdml.png" NDATA PNG>
+  <!ENTITY WiresharkExportSelectedDialog SYSTEM "./wsug_graphics/ws-export-selected.png" NDATA PNG>
+  <!ENTITY WiresharkPrint SYSTEM "./wsug_graphics/ws-print.png" NDATA PNG>
+  <!ENTITY WiresharkPacketRangeFrame SYSTEM "./wsug_graphics/ws-packet-range.png" NDATA PNG>
+  <!ENTITY WiresharkPacketFormatFrame SYSTEM "./wsug_graphics/ws-packet-format.png" NDATA PNG>
 
   <!-- Sixth Chapter -->
 
@@ -297,9 +303,7 @@ FILE SECTION
   &AppProtocols;
   &AppMessages;  
   &AppTools;
-  <!--
-  -->
-  
+
   &AppGPL;
   <!-- 
   Removed, as these chapters must be reworked
diff --git a/docbook/wsug_graphics/ws-merge-gtk1.png b/docbook/wsug_graphics/ws-merge-gtk1.png
new file mode 100644
index 0000000000..8de855eac2
--- /dev/null
+++ b/docbook/wsug_graphics/ws-merge-gtk1.png
diff --git a/docbook/wsug_graphics/ws-merge.png b/docbook/wsug_graphics/ws-merge-gtk2.png
index 3cc5b0a99e..3cc5b0a99e 100644
--- a/docbook/wsug_graphics/ws-merge.png
+++ b/docbook/wsug_graphics/ws-merge-gtk2.png
diff --git a/docbook/wsug_graphics/ws-merge-win32.png b/docbook/wsug_graphics/ws-merge-win32.png
new file mode 100644
index 0000000000..3e55289388
--- /dev/null
+++ b/docbook/wsug_graphics/ws-merge-win32.png
diff --git a/docbook/wsug_graphics/ws-open-gtk1.png b/docbook/wsug_graphics/ws-open-gtk1.png
new file mode 100644
index 0000000000..a9d8fbffb0
--- /dev/null
+++ b/docbook/wsug_graphics/ws-open-gtk1.png
diff --git a/docbook/wsug_graphics/ws-open-gtk2.png b/docbook/wsug_graphics/ws-open-gtk2.png
new file mode 100644
index 0000000000..21ab883231
--- /dev/null
+++ b/docbook/wsug_graphics/ws-open-gtk2.png
diff --git a/docbook/wsug_graphics/ws-open-win32.png b/docbook/wsug_graphics/ws-open-win32.png
new file mode 100644
index 0000000000..523a60c8e2
--- /dev/null
+++ b/docbook/wsug_graphics/ws-open-win32.png
diff --git a/docbook/wsug_graphics/ws-open.png b/docbook/wsug_graphics/ws-open.png
deleted file mode 100644
index 8857cf1efe..0000000000
--- a/docbook/wsug_graphics/ws-open.png
+++ /dev/null
diff --git a/docbook/wsug_graphics/ws-save-as-gtk1.png b/docbook/wsug_graphics/ws-save-as-gtk1.png
new file mode 100644
index 0000000000..7fd1a8eb5c
--- /dev/null
+++ b/docbook/wsug_graphics/ws-save-as-gtk1.png
diff --git a/docbook/wsug_graphics/ws-save-as.png b/docbook/wsug_graphics/ws-save-as-gtk2.png
index 0a518247e4..0a518247e4 100644
--- a/docbook/wsug_graphics/ws-save-as.png
+++ b/docbook/wsug_graphics/ws-save-as-gtk2.png
diff --git a/docbook/wsug_graphics/ws-save-as-win32.png b/docbook/wsug_graphics/ws-save-as-win32.png
new file mode 100644
index 0000000000..523a60c8e2
--- /dev/null
+++ b/docbook/wsug_graphics/ws-save-as-win32.png
diff --git a/docbook/wsug_src/WSUG_chapter_io.xml b/docbook/wsug_src/WSUG_chapter_io.xml
index ce980a9ac6..890410affc 100644
--- a/docbook/wsug_src/WSUG_chapter_io.xml
+++ b/docbook/wsug_src/WSUG_chapter_io.xml
@@ -42,14 +42,14 @@
       Open dialog box, which is discussed in more detail in 
       <xref linkend="ChIOOpen"/>. 
     </para>
-	<note><title>Note!</title>
+	<tip><title>It's convenient to use drag-and-drop!</title>
     <para>
-	You can also use <command>drag-and-drop </command> to open a file, by 
-	simply dropping the desired file from your file manager onto Wireshark's 
-	main window. However, drag-and-drop is not available/won't work in all 
-	desktop environments.
+	... to open a file, by simply dragging the desired file from your file 
+	manager and dropping it onto Wireshark's main window. 
+	However, drag-and-drop is not available/won't work in all desktop 
+	environments.
     </para>
-    </note>
+    </tip>
     <para>
 	  If you didn't save the current capture file before, you will be asked 
 	  to do so, to prevent data loss (this behaviour can be disabled in the 
@@ -71,84 +71,197 @@
 	  of the Wireshark Open File Dialog box.
       </para>
 	    <note>
-	      <title>Note</title>
+	      <title>The dialog appearance depends on your system!</title>
 	      <para>
-		  Wireshark uses the open dialog box from the version of the GTK+ 
-		  toolkit that it's using. This dialog was completely redesigned in 
-		  GTK version 2.4. Depending on the installed GTK version, 
-		  your dialog box might look different. However, as the 
-		  functionality remains almost the same, much of this description 
-		  will work with your version of Wireshark.
+		  The appearance of this dialog depends on the system and GTK+ toolkit 
+		  version used. However, the functionality remains basically the same 
+		  on either system.
 	      </para>
 	    </note>
-      <figure id="ChIOOpenFileDialog">
-	<title>The "Open Capture File" Dialog box</title>
-	<graphic entityref="WiresharkOpen" format="PNG"/>
-      </figure>
-      <para>
-	With this dialog box, you can perform the following actions:
-	<orderedlist>
+		
+	<para>
+	<command>Common dialog behaviour</command> on all systems:
+	</para>
+	<itemizedlist>
 	  <listitem>
 	    <para>
-		The "+ Add" button allows you to add a directory, selected in the 
-		right-hand pane, to the favorites (bookmarks?) list. Those changes 
-		are persistent.
+	      Select files and directories.
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-		The "- Remove" button allows you to remove a selected directory from 
-		that list again (the items like: "Home", "Desktop", and "Filesystem" 
-		cannot be removed).
+	      Click the Open/Ok button to accept your selected file and open it. 
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-	      Select files and directories with the list boxes.
+	      Click the Cancel button to go back to Wireshark and not load a capture 
+	      file.
 	    </para>
 	  </listitem>
+	</itemizedlist>
+
+      <para>
+	<command>Wireshark extensions</command> to the standard behaviour of 
+	these dialogs:
+      </para>
+	<itemizedlist>
 	  <listitem>
 	    <para>
 	      View file preview information (like the filesize, the number of 
-		  packets, ...), while browsing the filesystem.
+		  packets, ...), if you've selected a capture file.
 	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
-	      Specify a display filter with the Filter button and filter 
-	      field. This filter will be used when opening the new file.
+	      Specify a display filter with the "Filter:" button and filter 
+	      field. This filter will be used when opening the new file. 
+		  The text field background becomes green for a valid filter string 
+		  and red for an invalid one.
 		  Clicking on the Filter button causes Wireshark to pop up 
 	      the Filters dialog box (which is discussed further in 
 	      <xref linkend="ChWorkDisplayFilterSection"/>).
 	    </para>
+	    <para>
+		  XXX - we need a better description of these read filters
+	    </para>
 	  </listitem>
 	  <listitem>
 	    <para>
 	      Specify which name resolution is to be performed for all packets by 
-		  clicking on one of the "Enable name resolution" check buttons. 
+		  clicking on one of the "... name resolution" check buttons. 
 		  Details about name resolution can be found in 
 		  <xref linkend="ChAdvNameResolutionSection"/>.
 	    </para>
 	  </listitem>
-	  <listitem>
+	</itemizedlist>
+
+	<tip><title>Save a lot of time on huge capture files!</title>
+    <para>
+	You can change the display filter and name resolution settings later 
+	while viewing the packets. 
+	However, for huge capture files it can take a significant amount of 
+	extra time changing these settings later, so in such situations it can 
+	be a good idea to set at least the filter in advance here.
+    </para>
+    </tip>
+	
+	<!-- frame="none" -->
+    <table id="ChIOOpenFileTab">
+	<title>The system specific "Open Capture File" dialog box</title>
+      <tgroup cols="2">
+	    <tbody>
+		<row>
+		<entry valign="top">
+      <figure id="ChIOOpenFileDialogWin32">
+	<title>"Open" on native Windows</title>
+	<graphic entityref="WiresharkOpenDialogWin32" format="PNG"/>
+      </figure>
+		</entry>
+		<entry valign="top">
+		<para><command>Microsoft Windows (GTK2 installed)</command></para>
+      <para>
+		This is the common Windows file open dialog - 
+		plus some Wireshark extensions.
+      </para>
 	    <para>
-	      Click the Open button to accept your selected file and open it. 
-		  If Wireshark doesn't recognize the capture format, it will grey out 
-		  this button.
+		Specific for this dialog:
+      </para>
+	<itemizedlist>
+	<listitem>
+	    <para>
+	      If available, the "Help" button will lead you to this section of 
+		  this "User's Guide".
 	    </para>
-	  </listitem>
-	  <listitem>
+	</listitem>
+	<listitem>
 	    <para>
-	      Click the Cancel button to go back to Wireshark and not load a capture 
-	      file.
+ 		  XXX -  the "Filter:" button currently doesn't work on Windows!
 	    </para>
-	  </listitem>
-	</orderedlist>
-	You can also change the display filter and name resolution settings later while 
-	viewing the packets. However, for very large capture files it can take a 
-	significant amount of extra time changing these settings later, so it 
-	might be a good idea to set at least the filter in advance here.
+	</listitem>
+	<listitem>
+	    <para>
+		  XXX - missing feature:
+		  If Wireshark doesn't recognize the selected file as a capture file, 
+		  it should grey out the "Open" button.		  
+	    </para>
+	</listitem>
+	</itemizedlist>
+		</entry>
+	      </row>
+		<row>
+		<entry valign="top">
+      <figure id="ChIOOpenFileDialog">
+	<title>"Open" new GTK version</title>
+	<graphic entityref="WiresharkOpenDialog2" format="PNG"/>
+      </figure>
+	  </entry>
+	  <entry valign="top">
+      <para><command>Unix/Linux: GTK version >= 2.4</command></para>
+      <para>
+		This is the common Gimp/GNOME file open dialog - 
+		plus some Wireshark extensions.
+      </para>
+	    <para>
+		Specific for this dialog:
+      </para>
+	<itemizedlist>
+	<listitem>
+	    <para>
+		The "+ Add" button allows you to add a directory, selected in the 
+		right-hand pane, to the favorites list on the left. Those changes 
+		are persistent.
+	    </para>
+	</listitem>
+	<listitem>
+	    <para>
+		The "- Remove" button allows you to remove a selected directory from 
+		that list again (the items like: "Home", "Desktop", and "Filesystem" 
+		cannot be removed).
+	    </para>
+	</listitem>
+	<listitem>
+	    <para>
+		  If Wireshark doesn't recognize the selected file as a capture file, 
+		  it will grey out the "Open" button.
+	    </para>
+	</listitem>
+	</itemizedlist>
+	  </entry>
+		</row>
+	      <row>
+		<entry valign="top">
+      <figure id="ChIOOpenFileDialog1">
+	<title align="center">"Open" old GTK version</title>
+	<graphic entityref="WiresharkOpenDialog1" format="PNG"/>
+      </figure>
+		</entry>
+	  <entry valign="top">
+	    <para>
+		<command>Unix/Linux: GTK version &lt; 2.4 / Microsoft Windows (GTK1 
+		installed)</command></para>
+		<para>
+		  This is the file open dialog of former Gimp/GNOME versions - 
+		  plus some Wireshark extensions.
+		</para>
+	    <para>
+		Specific for this dialog:
       </para>
+	<itemizedlist>
+	<listitem>
+	    <para>
+		  If Wireshark doesn't recognize the selected file as a capture file, 
+		  it will grey out the "Ok" button.
+	    </para>
+	</listitem>
+	</itemizedlist>
+		</entry>
+		</row>
+	    </tbody>
+      </tgroup>
+    </table>
+		
+		
     </section>
 
   <section id="ChIOInputFormatsSection">
@@ -186,7 +299,7 @@
 		  <listitem><para>Catapult DCT2000 .out files</para></listitem>
 	</itemizedlist>
     </para>
-    <note><title>Note!</title>
+    <note><title>Open a file may fail due to invalid packet types!</title>
 	<para>
 	It may not be possible to read some formats dependent on the packet types 
 	captured. Ethernet captures are usually supported for most file formats, 
@@ -234,7 +347,7 @@
 	    </note>
       <figure id="ChIOSaveCaptureFileAs">
 	<title>The "Save Capture File As" dialog box</title>
-	<graphic entityref="WiresharkSaveAs" format="PNG"/>
+	<graphic entityref="WiresharkSaveAsDialog2" format="PNG"/>
       </figure>
       <para>
 	With this dialog box, you can perform the following actions:
@@ -385,7 +498,7 @@
 	</note>
 	<figure id="ChIOMergeDialog">
       <title>The "Merge with Capture File" dialog box</title>
-      <graphic entityref="WiresharkMergeDialog" format="PNG"/>
+      <graphic entityref="WiresharkMergeDialog2" format="PNG"/>
     </figure>
 	<variablelist>
 	<varlistentry>