Convert the user interface chapter to AsciiDoc.

Start mentioning Qt. Update and add HIG links.

Change-Id: Iac984045b03a96862981d58ff63c9ee6bcdbbce8
Reviewed-on: https://code.wireshark.org/review/127
Tested-by: Wireshark Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Gerald Combs <gerald@wireshark.org>

4 files changed, 214 insertions, 256 deletions

diff --git a/docbook/CMakeLists.txt b/docbook/CMakeLists.txt
index 2c03b72c2b..1431c00100 100644
--- a/docbook/CMakeLists.txt
+++ b/docbook/CMakeLists.txt
@@ -190,7 +190,7 @@ set(WSDG_FILES
 	wsdg_generated_src/WSDG_chapter_quick_setup.xml
 	wsdg_generated_src/WSDG_chapter_sources.xml
 	wsdg_generated_src/WSDG_chapter_tools.xml
-	wsdg_src/WSDG_chapter_userinterface.xml
+	wsdg_generated_src/WSDG_chapter_userinterface.xml
 	wsdg_generated_src/WSDG_chapter_works.xml
 	wsdg_src/WSDG_meta_info.xml
 	wsdg_generated_src/WSDG_preface.xml
@@ -206,6 +206,7 @@ set(WSDG_ASCIIDOC_FILES
 	wsdg_src/WSDG_chapter_quick_setup.asciidoc
 	wsdg_src/WSDG_chapter_sources.asciidoc
 	wsdg_src/WSDG_chapter_tools.asciidoc
+	wsdg_src/WSDG_chapter_userinterface.asciidoc
 	wsdg_src/WSDG_chapter_works.asciidoc
 	wsdg_src/WSDG_preface.asciidoc
 )
diff --git a/docbook/Makefile.common b/docbook/Makefile.common
index c83c2a5874..362ce2a73a 100644
--- a/docbook/Makefile.common
+++ b/docbook/Makefile.common
@@ -167,7 +167,7 @@ WSDG_FILES =	\
 	wsdg_src/WSDG_chapter_quick_setup.asciidoc	\
 	wsdg_src/WSDG_chapter_sources.asciidoc		\
 	wsdg_src/WSDG_chapter_tools.asciidoc		\
-	wsdg_src/WSDG_chapter_userinterface.xml	\
+	wsdg_src/WSDG_chapter_userinterface.asciidoc	\
 	wsdg_src/WSDG_chapter_works.asciidoc		\
 	wsdg_src/WSDG_meta_info.xml		\
 	wsdg_src/WSDG_preface.asciidoc			\
@@ -182,6 +182,7 @@ WSDG_GENERATED_SOURCE = \
 	wsdg_src/WSDG_chapter_quick_setup.xml	\
 	wsdg_src/WSDG_chapter_sources.xml	\
 	wsdg_src/WSDG_chapter_tools.xml		\
+	wsdg_src/WSDG_chapter_userinterface.xml	\
 	wsdg_src/WSDG_chapter_works.xml		\
 	wsdg_src/WSDG_preface.xml
 
diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc
new file mode 100644
index 0000000000..1a9eb30d30
--- /dev/null
+++ b/docbook/wsdg_src/WSDG_chapter_userinterface.asciidoc
@@ -0,0 +1,210 @@
+++++++++++++++++++++++++++++++++++++++
+<!-- WSDG Chapter User Interface -->
+++++++++++++++++++++++++++++++++++++++
+    
+[[ChapterUserInterface]]
+
+== User Interface
+
+[[ChUIIntro]]
+
+=== Introduction
+
+Wireshark can be logically separated into the backend (dissecting protocols,
+file loading and saving, capturing, etc.) and the frontend (the user interface).
+
+The following frontends are currently maintained by the Wireshark
+development team:
+
+* Wireshark, GTK 2.x based
+
+* Wireshark, GTK 3.x based (Wireshark 1.10 and newer)
+
+* Wireshark, Qt based (Wireshark 1.11 and newer)
+
+* TShark, console based
+
+There are other Wireshark frontends which are not developed nor maintained by
+the Wireshark development team:
+
+* Packetyzer (Win32 native interface, written in Delphi and released
+under the GPL, see: http://www.paglo.com/opensource/packetyzer[])
+
+* hethereal (web based frontend, not actively maintained and not
+finished)
+
+This chapter is focused on the Wireshark frontend, and especially on
+the GTK interface.
+
+[[ChUIGTK]]
+
+=== The GTK library
+
+.We're switching to Qt
+[NOTE]
+====
+This chapter describes the state of our stable release, which is based on GTK+.
+A major effort is underway to migrate Wireshark to Qt. If you would like to add
+a new interface feature you should use it and not GTK+.
+====
+
+Wireshark is based on the GTK toolkit. See http://www.gtk.org[] for details.
+GTK is designed to hide the details of the underlying GUI in a platform
+independent way. As GTK is intended to be a multiplatform tool, there are some
+drawbacks, as the result is a somewhat "non native" look and feel.
+
+GTK is available for many different platforms including, but not limited to:
+Unix/Linux, Mac OS X and Win32. It's the foundation of the famous GNOME desktop,
+so the future development of GTK should be certain. GTK is implemented in plain
+C (as is Wireshark itself), and available under the LGPL (Lesser General Public
+License), making it free to used by commercial and noncommercial applications.
+
+There are other similar toolkits like wxWidgets which could also be used for
+Wireshark. There's no "one and only" reason for or against any of these
+toolkits. However, the decision towards GTK was made a long time ago :-)
+
+As of 2013 there are two major GTK versions available:
+
+[[ChUIGTK2x]]
+
+==== GTK Version 2.x
+
+GTK 2.x depends on the following libraries:
+
+* GObject (Object library. Basis for GTK and others)
+
+* GLib (A general-purpose utility library, not specific to graphical user
+  interfaces. GLib provides many useful data types, macros, type conversions,
+  string utilities, file utilities, a main loop abstraction, and so on.)
+
+* Pango (Pango is a library for internationalized text handling. It centers
+  around the PangoLayout object, representing a paragraph of text. Pango
+  provides the engine for GtkTextView, GtkLabel, GtkEntry, and other widgets
+  that display text.)
+
+* ATK (ATK is the Accessibility Toolkit. It provides a set of generic interfaces
+  allowing accessibility technologies to interact with a graphical user
+  interface. For example, a screen reader uses ATK to discover the text in an
+  interface and read it to blind users. GTK+ widgets have built-in support for
+  accessibility using the ATK framework.)
+
+* GdkPixbuf (This is a small library which allows you to create GdkPixbuf
+  ("pixel buffer") objects from image data or image files. Use a
+  GdkPixbuf in combination with GtkImage to display images.)
+
+* GDK (GDK is the abstraction layer that allows GTK+ to support multiple
+  windowing systems. GDK provides drawing and window system facilities on X11,
+  Windows, and the Linux framebuffer device.)
+
+[[ChUIGTK3x]]
+
+==== GTK Version 3.x
+
+Wireshark (as of version 1.10) has been ported to use the GTK3 library.
+
+GTK 3.x depends on the following libraries:
+
+(See GTK 2.x)
+
+[[ChUIGTKCompat]]
+
+==== Compatibility GTK versions
+
+The GTK library itself defines some values which makes it easy to distinguish
+between the versions, e.g. +GTK_MAJOR_VERSION+ and +GTK_MINOR_VERSION+ will be
+set to the GTK version at compile time inside the gtkversion.h header.
+
+[[ChUIGTKWeb]]
+
+==== GTK resources on the web
+
+You can find several resources about GTK.
+
+First of all, have a look at http://www.gtk.org[]. This
+will be the first place to look at. If you want to develop GTK related
+things for Wireshark, the most important place might be the GTK API
+documentation at http://library.gnome.org/devel/gtk/stable/[].
+
+Several mailing lists are available about GTK development, see
+http://mail.gnome.org/mailman/listinfo[], the gtk-app-devel-list may be your
+friend.
+
+As it's often done wrong: You should post a mail to *help* the developers
+there instead of only complaining. Posting such a thing like "I don't like
+your dialog, it looks ugly" won't be of much help. You might think about
+what you dislike and describe why you dislike it and provide a suggestion
+for a better way.
+
+[[ChUIGUIDocs]]
+
+=== GUI Reference documents
+
+Although the GUI development of Wireshark is platform independent, the
+Wireshark development team tries to
+follow the GNOME Human Interface Guidelines (HIG) where appropriate.
+This is the case, because both GNOME and Wireshark are based on the GTK+
+toolkit and the GNOME HIG is excellently written and easy to understand.
+
+For further reference, see the following documents:
+
+* Android Design:
+http://developer.android.com/design/index.html[] (Wireshark doesn't have a
+mobile frontend but there is still useful information here)
+
+* GNOME Human Interface Guidelines:
+http://library.gnome.org/devel/hig-book/stable/[]
+
+* The KDE Usability/HIG project:
+http://techbase.kde.org/Projects/Usability/HIG[]
+
+* OS X Human Interface Guidelines:
+https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html[]
+
+* Design apps for the Windows desktop:
+http://msdn.microsoft.com/en-us/library/Aa511258.aspx[]
+
+[[ChUIGTKDialogs]]
+
+=== Adding/Extending Dialogs
+
+This is usually the main area for contributing new user interface features.
+
+XXX: add the various functions from gtk/dlg_utils.h
+
+[[ChUIGTKWidgetNamings]]
+
+=== Widget naming
+
+It seems to be common sense to name the widgets with some
+descriptive trailing characters, like:
+
+* xy_lb = gtk_label_new();
+
+* xy_cb = gtk_checkbox_new();
+
+* XXX: add more examples
+
+However, this schema isn't used at all places inside the code.
+
+[[ChUIGTKPitfalls]]
+
+=== Common GTK programming pitfalls
+
+There are some common pitfalls in GTK programming.
+
+[[ChUIGTKShowAll]]
+
+==== Usage of gtk_widget_show() / gtk_widget_show_all()
+
+When a GTK widget is created it will be hidden by default. In order to
+show it, a call to gtk_widget_show() has to be done.
+
+
+It isn't necessary to do this for each and every widget created. A call
+to gtk_widget_show_all() on the parent of all the widgets in question
+(e.g. a dialog window) can be done, so all of its child widgets will
+be shown too.
+
+++++++++++++++++++++++++++++++++++++++
+<!-- End of WSDG Chapter User Interface -->
+++++++++++++++++++++++++++++++++++++++
diff --git a/docbook/wsdg_src/WSDG_chapter_userinterface.xml b/docbook/wsdg_src/WSDG_chapter_userinterface.xml
deleted file mode 100644
index 324d5b02b5..0000000000
--- a/docbook/wsdg_src/WSDG_chapter_userinterface.xml
+++ /dev/null
@@ -1,254 +0,0 @@
-<!-- WSDG Chapter User Interface -->
-<!-- $Id$ -->
-
-<chapter id="ChapterUserInterface">
-  <title>User Interface</title>
-
-  <section id="ChUIIntro">
-	<title>Introduction</title>
-	<para>
-	Wireshark can be "logically" separated into the backend (dissecting of
-	protocols, file load/save, capturing, ...) and the frontend (the user
-	interface). However, there's currently no clear separation between
-	these two parts (no clear API definition), but this might change in the
-	future.
-	</para>
-	<para>
-	The following frontends are currently maintained by the Wireshark
-	development team:
-	<itemizedlist>
-	  <listitem><para>
-	  Wireshark, GTK 2.x based
-	  </para></listitem>
-	  <listitem><para>
-	  Wireshark, GTK 3.x based (Wireshark 1.10 and newer)
-	  </para></listitem>
-	  <listitem><para>
-	  TShark, console based
-	  </para></listitem>
-	</itemizedlist>
-	There exist other Wireshark frontends, not developed nor
-	maintained by the Wireshark development team:
-	<itemizedlist>
-	  <listitem><para>
-	  Packetyzer (Win32 native interface, written in Delphi and released
-	  under the GPL, see:
-	  <ulink url="http://www.paglo.com/opensource/packetyzer"/>)
-	  </para></listitem>
-	  <listitem><para>
-	  hethereal (web based frontend, not actively maintained and not
-	  finished)
-	  </para></listitem>
-	</itemizedlist>
-	This chapter is focused on the Wireshark frontend, and especially on
-	the GTK specific things.
-	</para>
-  </section>
-
-	<section id="ChUIGTK">
-	<title>The GTK library</title>
-	<para>
-	Wireshark is based on the GTK toolkit, see: <ulink url="http://www.gtk.org"/>
-	for details. GTK is designed to hide the details of the underlying GUI in
-	a platform independent way. As GTK is intended to be a
-	multiplatform tool, there are some drawbacks, as the result is a
-	somewhat "non native" look and feel.
-	</para>
-	<para>
-	GTK is available for a lot of different platforms including, but not
-	limited to: Unix/Linux, Mac OS X and Win32. It's the foundation of
-	the famous GNOME desktop, so the future development of GTK should be
-	certain.
-	GTK is implemented in plain C (as is Wireshark itself), and available under
-	the LGPL (Lesser General Public License), being free to used by
-	commercial and noncommercial applications.
-	</para>
-	<para>
-	There are other similar toolkits like Qt, wxwidgets, ..., which could
-	also be used for Wireshark. There's no "one and only" reason for or against
-	any of these toolkits. However, the decision towards GTK was made a
-	long time ago :-)
-	</para>
-	<para>
-	Currently [2013] there are two major GTK versions
-	available:
-	</para>
-
-
-	<section id="ChUIGTK2x">
-	<title>GTK Version 2.x</title>
-	<para>
-	GTK 2.x depends on the following libraries:
-	<itemizedlist>
-	  <listitem><para>
-	  GObject (Object library. Basis for GTK and others)
-	  </para></listitem>
-	  <listitem><para>
-	  GLib (A general-purpose utility
-	  library, not specific to graphical user interfaces.
-	  GLib provides many useful data types, macros, type conversions,
-	  string utilities, file utilities, a main loop abstraction, and so on.)
-	  </para></listitem>
-	  <listitem><para>
-	  Pango (Pango is a library for internationalized text handling. It centers
-	  around the #PangoLayout object, representing a paragraph of text.
-	  Pango provides the engine for #GtkTextView, #GtkLabel, #GtkEntry, and
-	  other widgets that display text.)
-	  </para></listitem>
-	  <listitem><para>
-	  ATK (ATK is the Accessibility Toolkit. It provides a set of generic
-	  interfaces allowing accessibility technologies to interact with a
-	  graphical user interface. For example, a screen reader uses ATK to
-	  discover the text in an interface and read it to blind users. GTK+
-	  widgets have built-in support for accessibility using the ATK
-	  framework.)
-	  </para></listitem>
-	  <listitem><para>
-	  GdkPixbuf (This is a small library which allows you to create #GdkPixbuf
-	  ("pixel buffer") objects from image data or image files. Use a
-	  #GdkPixbuf in combination with #GtkImage to display images.)
-	  </para></listitem>
-	  <listitem><para>
-	  GDK (GDK is the abstraction layer that allows GTK+ to support multiple
-	  windowing systems. GDK provides drawing and window system facilities
-	  on X11, Windows, and the Linux framebuffer device.)
-	  </para></listitem>
-	</itemizedlist>
-	</para>
-	</section>
-
-
-	<section id="ChUIGTK3x">
-	<title>GTK Version 3.x</title>
-	<para>
-	Wireshark (as of version 1.10) has been ported to use the GTK3 library.
-	</para>
-	<para>
-	GTK 3.x depends on the following libraries:
-	</para>
-	<para>
-	(See GTK 2.x)
-	</para>
-	</section>
-
-
-	<section id="ChUIGTKCompat">
-	<title>Compatibility GTK versions</title>
-	<para>
-	The GTK library itself defines some values which makes it easy to
-	distinguish between the versions, e.g.:
-	GTK_MAJOR_VERSION and GTK_MINOR_VERSION
-	will be set to the GTK version at compile time inside the gtkversion.h header.
-	</para>
-	</section>
-
-	<section id="ChUIGTKWeb">
-	<title>GTK resources on the web</title>
-	<para>
-	You can find several resources about GTK.
-	</para>
-	<para>
-	First of all, have a look at: <ulink url="http://www.gtk.org"/> as this
-	will be the first place to look at. If you want to develop GTK related
-	things for Wireshark, the most important place might be the GTK API
-	documentation at: <ulink url="http://library.gnome.org/devel/gtk/stable/"/>.
-	</para>
-	<para>
-	Several mailing lists are available about GTK development, see <ulink
-	url="http://mail.gnome.org/mailman/listinfo"/>, the gtk-app-devel-list
-	may be your friend.
-	</para>
-  <para>
-	As it's often done wrong: You should post a mail to *help* the developers
-	there instead of only complaining. Posting such a thing like "I don't like
-	your dialog, it looks ugly" won't be of much help. You might think about
-	what you dislike and describe why you dislike it and provide a suggestion
-	for a better way.
-	</para>
-	</section>
-
-	</section>
-
-	<section id="ChUIGUIDocs">
-	<title>GUI Reference documents</title>
-	<para>
-	Although the GUI development of Wireshark is platform independent, the
-	Wireshark development team tries to
-	follow the GNOME Human Interface Guidelines (HIG) where appropriate.
-	This is the case, because both GNOME and Wireshark are based on the GTK+
-	toolkit and the GNOME HIG is excellently written and easy to understand.
-	</para>
-	<para>
-	For further reference, see the following documents:
-	<itemizedlist>
-	  <listitem><para>
-	  GNOME Human Interface Guidelines at:
-	  <ulink url="http://library.gnome.org/devel/hig-book/stable/"/>
-	  </para></listitem>
-	  <listitem><para>
-	  KDE user interface related documents at:
-	  <ulink url="http://developer.kde.org/documentation/standards/kde/style/basics/index.html"/>
-	  </para></listitem>
-	  <listitem><para>
-	  Win32 styleguides available at:
-	  <ulink url="http://msdn.microsoft.com/en-us/library/aa511258.aspx"/>
-	  </para></listitem>
-	</itemizedlist>
-	</para>
-	</section>
-
-  <section id="ChUIGTKDialogs">
-	<title>Adding/Extending Dialogs</title>
-	<para>
-	This is usually the main area for contributing new user interface features.
-	</para>
-	<para>
-	XXX: add the various functions from gtk/dlg_utils.h
-	</para>
-  </section>
-
-  <section id="ChUIGTKWidgetNamings">
-	<title>Widget naming</title>
-	<para>
-	It seems to be common sense to name the widgets with some
-	descriptive trailing characters, like:
-	<itemizedlist>
-	  <listitem><para>
-	  xy_lb = gtk_label_new();
-	  </para></listitem>
-	  <listitem><para>
-	  xy_cb = gtk_checkbox_new();
-	  </para></listitem>
-	  <listitem><para>
-	  XXX: add more examples
-	  </para></listitem>
-	</itemizedlist>
-	However, this schema isn't used at all places inside the code.
-	</para>
-  </section>
-
-
-  <section id="ChUIGTKPitfalls">
-	<title>Common GTK programming pitfalls</title>
-	<para>
-	There are some common pitfalls in GTK programming.
-	</para>
-
-	<section id="ChUIGTKShowAll">
-	<title>Usage of gtk_widget_show() / gtk_widget_show_all()</title>
-	<para>
-	When a GTK widget is created it will be hidden by default. In order to
-	show it, a call to gtk_widget_show() has to be done.
-	</para>
-	<para>
-	It isn't necessary to do this for each and every widget created. A call
-	to gtk_widget_show_all() on the parent of all the widgets in question
-	(e.g. a dialog window) can be done, so all of its child widgets will
-	be shown too.
-	</para>
-	</section>
-
-  </section>
-
-</chapter>
-<!-- End of WSDG Chapter User Interface -->