WSDG: Layout and content updates.

Adjust the column widths of some tables to that they render more cleanly
and without FOP warnings. Move some table content to plain text instead
of trying to shove it into table cells. Fix some other layout and
formatting.

Change-Id: I40e40fd7ca5c3cc594ea30c8b1ad233afd4cdca4
Reviewed-on: https://code.wireshark.org/review/17880
Reviewed-by: Gerald Combs <gerald@wireshark.org>

6 files changed, 99 insertions, 64 deletions

diff --git a/docbook/Makefile.am b/docbook/Makefile.am
index 8115944dd7..86c8e73467 100644
--- a/docbook/Makefile.am
+++ b/docbook/Makefile.am
@@ -60,6 +60,7 @@ WSUG_GRAPHICS =	\
 	wsug_graphics/ws-capture-menu.png		\
 	wsug_graphics/ws-capture-options.png		\
 	wsug_graphics/ws-capture-options-compile-selected-bpfs.png	\
+	wsug_graphics/ws-capture-options-output.png			\
 	wsug_graphics/ws-capture-options-manage-interfaces-local.png	\
 	wsug_graphics/ws-capture-options-manage-interfaces-pipes.png	\
 	wsug_graphics/ws-capture-options-manage-interfaces-remote-plus.png	\
diff --git a/docbook/asciidoc.conf b/docbook/asciidoc.conf
index c0678bb929..c658adc399 100644
--- a/docbook/asciidoc.conf
+++ b/docbook/asciidoc.conf
@@ -7,6 +7,7 @@ wireshark-version=2.3.0
 # "scaledwidth" only applies to PDF output
 pdf-scaledwidth=scaledwidth="85%"
 screenshot-attrs=scaledwidth="85%"
+small-screenshot-attrs=scaledwidth="35%"
 toolbar-icon-attrs=height=24,width=24
 related-attrs=height=18
 # XXX height=22 results in content-height="22px" in the .fo file. Not sure
diff --git a/docbook/wsug_graphics/ws-capture-options-output.png b/docbook/wsug_graphics/ws-capture-options-output.png
new file mode 100644
index 0000000000..9cc6b82266
--- /dev/null
+++ b/docbook/wsug_graphics/ws-capture-options-output.png
diff --git a/docbook/wsug_src/WSUG_chapter_capture.asciidoc b/docbook/wsug_src/WSUG_chapter_capture.asciidoc
index 456b0ce023..e1f4146fcf 100644
--- a/docbook/wsug_src/WSUG_chapter_capture.asciidoc
+++ b/docbook/wsug_src/WSUG_chapter_capture.asciidoc
@@ -324,8 +324,9 @@ you do not specify this Wireshark simply adds new packets onto the end of the
 list but does not scroll the packet list pane. This option is greyed out if
 ``Update list of packets in real time'' is disabled.
 
-_Hide capture info dialog_::
-If this option is checked, the capture info dialog described in  <<ChCapRunningSection>> will be hidden.
+// XXX ChCapRunningSection currently disabled
+//_Hide capture info dialog_::
+//If this option is checked, the capture info dialog described in  <<ChCapRunningSection>> will be hidden.
 
 ==== Name Resolution frame
 
@@ -347,8 +348,9 @@ Once you have set the values you desire and have selected the options you need,
 simply click on button:[Start] to commence the capture or button:[Cancel] to
 cancel the capture.
 
-If you start a capture, Wireshark allows you to stop capturing when you have
-enough packets captured, for details see <<ChCapRunningSection>>.
+// XXX ChCapRunningSection currently disabled
+//If you start a capture, Wireshark allows you to stop capturing when you have
+//enough packets captured, for details see <<ChCapRunningSection>>.
 
 [[ChCapEditInterfaceSettingsSection]]
 
@@ -640,11 +642,17 @@ image::wsug_graphics/ws-capture-interface-details.png[{screenshot-attrs}]
 
 While capturing the underlying libpcap capturing engine will grab the packets
 from the network card and keep the packet data in a (relatively) small kernel
-buffer. This data is read by Wireshark and saved into the capture file(s) the
-user specified.
+buffer. This data is read by Wireshark and saved into a capture file.
 
-Different modes of operation are available when saving this packet data to the
-capture file(s).
+By default Wireshark saves packets to a temporary file. You can also tell
+Wireshark to save to a specific (``permanent'') file and switch to a
+different file after a given time has elapsed or a given number of packets
+have been captured. These options are controlled in the ``Output'' tab in
+the ``Capture Options'' dialog.
+
+[[ChCapCaptureOptionsOutputDialog]]
+.Capture output options
+image::wsug_graphics/ws-capture-options-output.png[{screenshot-attrs}]
 
 [TIP]
 ====
@@ -668,9 +676,9 @@ Information about the folders used for capture files can be found in
 
 [[ChCapTabCaptureFiles]]
 .Capture file mode selected by capture options
-[options="header"]
+[options="header",cols="2,2,2,3,5"]
 |===============
-|``File'' option|``Use multiple files'' option|``Ring buffer with n files'' option|Mode|Resulting filename(s) used
+|File Name|``Create a new file...''|``Use a ring buffer...''|Mode|Resulting filename(s) used
 |-|-|-|_Single temporary file_|wiresharkXXXXXX (where XXXXXX is a unique number)
 |foo.cap|-|-|_Single named file_|foo.cap
 |foo.cap|x|-|_Multiple files, continuous_|foo_00001_20100205110102.cap, foo_00002_20100205110318.cap, ...
@@ -678,27 +686,27 @@ Information about the folders used for capture files can be found in
 |===============
 
 _Single temporary file_::
-A temporary file will be created and used (this is the default). After capturing
-is stopped this file can be saved later under a user specified name.
+  A temporary file will be created and used (this is the default). After capturing
+  is stopped this file can be saved later under a user specified name.
 
 _Single named file_::
-A single capture file will be used. If you want to place the new capture file in
-a specific folder choose this mode.
+  A single capture file will be used. If you want to place the new capture file in
+  a specific folder choose this mode.
 
 _Multiple files, continuous_::
-Like the ``Single named file'' mode, but a new file is created and used after
-reaching one of the multiple file switch conditions (one of the ``Next file every
-...'' values).
+  Like the ``Single named file'' mode, but a new file is created and used after
+  reaching one of the multiple file switch conditions (one of the ``Next file every
+  ...'' values).
 
 _Multiple files, ring buffer_::
-Much like ``Multiple files continuous'', reaching one of the multiple files switch
-conditions (one of the ``Next file every ...'' values) will switch to the next
-file. This will be a newly created file if value of ``Ring buffer with n files''
-is not reached, otherwise it will replace the oldest of the formerly used files
-(thus forming a ``ring'').
-+
-This mode will limit the maximum disk usage, even for an unlimited amount of
-capture input data, only keeping the latest captured data.
+  Much like ``Multiple files continuous'', reaching one of the multiple files switch
+  conditions (one of the ``Next file every ...'' values) will switch to the next
+  file. This will be a newly created file if value of ``Ring buffer with n files''
+  is not reached, otherwise it will replace the oldest of the formerly used files
+  (thus forming a ``ring'').
+  +
+  This mode will limit the maximum disk usage, even for an unlimited amount of
+  capture input data, only keeping the latest captured data.
 
 [[ChCapLinkLayerHeader]]
 
@@ -872,6 +880,11 @@ _SESSIONNAME_ (terminal server)::
 
 On Windows it asks the operating system if it's running in a Remote Desktop Services environment.
 
+////
+
+// XXX Capture Info is currently disabled, but might be resurrected. See
+// capture_info.[ch] and their git logs for details.
+
 [[ChCapRunningSection]]
 
 === While a Capture is running ...
@@ -891,6 +904,7 @@ cannot be changed.
 This ``Capture Info'' dialog box can be hidden using the ``Hide capture info
 dialog'' option in the Capture Options dialog box.
 ====
+////
 
 [[ChCapStopSection]]
 
diff --git a/docbook/wsug_src/WSUG_chapter_customize.asciidoc b/docbook/wsug_src/WSUG_chapter_customize.asciidoc
index 34ef3433ca..d855405798 100644
--- a/docbook/wsug_src/WSUG_chapter_customize.asciidoc
+++ b/docbook/wsug_src/WSUG_chapter_customize.asciidoc
@@ -507,7 +507,7 @@ background colors respectively.
 
 [[ChCustChooseColorDialog]]
 .A color chooser
-image::wsug_graphics/ws-choose-color-rule.png[{screenshot-attrs}]
+image::wsug_graphics/ws-choose-color-rule.png[{small-screenshot-attrs}]
 
 The color chooser appearance depends on your operating system. The OS X color
 picker is shown. Select the color you desire for the selected packets and click
diff --git a/docbook/wsug_src/WSUG_chapter_work.asciidoc b/docbook/wsug_src/WSUG_chapter_work.asciidoc
index eaf6af6864..59e388ed99 100644
--- a/docbook/wsug_src/WSUG_chapter_work.asciidoc
+++ b/docbook/wsug_src/WSUG_chapter_work.asciidoc
@@ -71,7 +71,7 @@ description of each item.
 
 [[ColumnHeaderPopupMenuTable]]
 .The menu items of the ``Packet List'' column header pop-up menu
-[options="header"]
+[options="header",cols="3,2,5"]
 |===============
 |Item|Identical to main menu's item:|Description
 |menu:Sort Ascending[]|| Sort the packet list in ascending order based on this column.
@@ -101,7 +101,7 @@ The following table gives an overview of which functions are available  in this
 
 [[PacketListPopupMenuTable]]
 .The menu items of the ``Packet List'' pop-up menu
-[options="header"]
+[options="header",cols="3,2,5"]
 |===============
 |Item|Identical to main menu's item:|Description
 |menu:Mark Packet (toggle)[]|menu:Edit[]| Mark/unmark a packet.
@@ -146,7 +146,7 @@ description of each item.
 [[PacketDetailsPopupMenuTable]]
 
 .The menu items of the ``Packet Details'' pop-up menu
-[options="header"]
+[options="header",cols="3,2,5"]
 |===============
 |Item|Identical to main menu's item:|Description
 |menu:Expand Subtrees[]|menu:View[]| Expand the currently selected subtree.
@@ -283,7 +283,7 @@ You can use English and C-like terms in the same way, they can even be  mixed in
 [[DispCompOps]]
 
 .Display Filter comparison operators
-[options="header"]
+[options="header",cols="1,1,4"]
 |===============
 |English|C-like|Description and example
 |eq |== |Equal. `ip.src==10.0.0.5`
@@ -300,37 +300,55 @@ of the types and example of how to express them.
 [[ChWorkFieldTypes]]
 
 .Display Filter Field Types
-[options="header"]
-|===============
-|Type|Example
-|Unsigned integer (8-bit, 16-bit, 24-bit, 32-bit) |
-You can express integers in decimal, octal, or  hexadecimal. The following display filters are  equivalent:
-----
-ip.len le 1500
-ip.len le 02734
-ip.len le 0x436
-----
-|Signed integer (8-bit, 16-bit, 24-bit, 32-bit) |
-|Boolean|
-A boolean field is present in the protocol decode only if its value is true. For
-example, _tcp.flags.syn_ is present, and thus true, only if the SYN flag is
-present in a TCP segment header.
-
-Thus the filter expression  _tcp.flags.syn_ will select only  those packets for which this flag exists, that is,  TCP segments where the segment header contains the  SYN flag. Similarly, to find source-routed token  ring packets, use a filter expression of  _tr.sr_.
-|Ethernet address (6 bytes)|Separators can be a colon (:), dot (.) or dash (-) and can have one or two bytes between separators:
-----
-eth.dst == ff:ff:ff:ff:ff:ff
-eth.dst == ff-ff-ff-ff-ff-ff
-eth.dst == ffff.ffff.ffff
-----
-|IPv4 address|ip.addr == 192.168.0.1
+Unsigned integer::
+  Can be 8, 16, 24, 32, or 64 bits. You can express integers in decimal, octal,
+  or  hexadecimal. The following display filters are  equivalent:
 
-Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address is in a certain subnet. For example, this display filter will find all packets in the 129.111 Class-B network:
+  ip.len le 1500
 
-ip.addr == 129.111.0.0/16
-|IPv6 address|ipv6.addr == ::1
-|String (text)|http.request.uri == "https://www.wireshark.org/"
-|===============
+  ip.len le 02734
+
+  ip.len le 0x436
+
+Signed integer::
+  Can be 8, 16, 24, 32, or 64 bits. As with unsigned integers you can use
+  decimal, octal, or  hexadecimal.
+
+Boolean::
+  A boolean field is present in the protocol decode only if its value is true. For
+  example, +tcp.flags.syn+ is present, and thus true, only if the SYN flag is
+  present in a TCP segment header.
+
+  The filter expression  +tcp.flags.syn+ will select only  those packets for which
+  this flag exists, that is,  TCP segments where the segment header contains the
+  SYN flag. Similarly, to find source-routed token ring packets, use a filter
+  expression of  +tr.sr+.
+
+Ethernet address::
+  6 bytes separated by a colon (:), dot (.) or dash (-) with one or two bytes between separators:
+
+  eth.dst == ff:ff:ff:ff:ff:ff
+
+  eth.dst == ff-ff-ff-ff-ff-ff
+
+  eth.dst == ffff.ffff.ffff
+
+IPv4 address::
+  ip.addr == 192.168.0.1
+
+  Classless InterDomain Routing (CIDR) notation can be used to test if
+  an IPv4 address is in a certain subnet. For example, this display
+  filter will find all packets in the 129.111 Class-B network:
+
+  ip.addr == 129.111.0.0/16
+
+IPv6 address::
+  +ipv6.addr == ::1+
+
+  As with IPv4 addresses, IPv6 addresses can match a subnet.
+
+Text string::
+  +http.request.uri == "https://www.wireshark.org/"+
 
 ==== Combining expressions
 
@@ -339,16 +357,18 @@ You can combine filter expressions in Wireshark using the  logical operators sho
 [[FiltLogOps]]
 
 .Display Filter Logical Operations
-[options="header"]
+[options="header",cols="1,1,4"]
 |===============
 |English|C-like|Description and example
 |and     |&amp;&amp;| Logical AND. `ip.src==10.0.0.5 and tcp.flags.fin`
 |or      |\|\|      | Logical OR. `ip.scr==10.0.0.5 or ip.src==192.1.1.1`
 |xor     |^^        | Logical XOR. `tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29`
 |not     |!         | Logical NOT. `not llc`
-|[...]   |          |
+|[...]   |          | See ``Substring Operator'' below.
+|in      |          | See ``Membership Operator'' below.
+|===============
 
-Substring Operator.
+==== Substring Operator
 Wireshark allows you to select subsequences of a sequence in rather elaborate
 ways. After a label you can place a pair of brackets [] containing a comma
 separated list of range specifiers.
@@ -383,7 +403,6 @@ eth.src[0:3,1-2,:4,4:,2] ==
 ----
 Wireshark allows you to string together single ranges in a comma separated list
 to form compound ranges as shown above.
-|===============
 
 ==== Membership Operator.
 Wireshark allows you to test a field for membership in a set of values or
@@ -400,7 +419,7 @@ tcp.port == 80 || tcp.port == 443 || tcp.port == 8080
 
 [[ChWorkBuildDisplayFilterMistake]]
 
-==== A common mistake
+==== A Common Mistake
 
 Using the != operator on combined expressions like eth.addr, ip.addr, tcp.port,
 and udp.port will probably not work as expected.