WSUG: Update the I/O Graphs section.

Update the I/O Graphs section of the User's Guide. Use the name "I/O
Graphs" consistently.

Update the image thanks to Chuck Craft.

Ping-Bug: 16359
Change-Id: I6b60fd1b79a849e4467c7ca7927279e16dd6e671
Reviewed-on: https://code.wireshark.org/review/35762
Reviewed-by: Gerald Combs <gerald@wireshark.org>
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>

docbook/wsug_src/WSUG_chapter_statistics.adoc

@@ -370,58 +370,125 @@ btn:[Save as...] lets you save the data as text, CSV, YAML, or XML.
 
 [[ChStatIOGraphs]]
 
-=== The “I/O Graph” Window
+=== The “I/O Graphs” Window
 
-User configurable graph of the captured network packets.
-
-You can define up to five differently colored graphs.
+Lets you plot packet and protocol data in a variety of ways.
 
 .The “I/O Graphs” window
 image::wsug_graphics/ws-stats-iographs.png[{screenshot-attrs}]
 
-The user can configure the following things:
+As shown above, this window contains a chart drawing area along with a customizable list of graphs.
+Graphs are saved in your current <<ChCustConfigProfilesSection,profile>>.
+They are divided into time intervals, which can be set as described below.
+Hovering over the graph shows the last packet in each interval except as noted below.
+Clicking on the graph takes you to the associated packet in the packet list.
+Individual graphs can be configured using the following options:
 
-* _Graphs_
+Enabled::
+Draw or don’t draw this graph.
 
-  - __Graph 1-5__: enable the specific graph 1-5 (only graph 1 is enabled by default)
+Graph Name::
+The name of this graph.
 
-  - __Color__: the color of the graph (cannot be changed)
+Display Filter::
+Limits the graph to packets that match this filter.
 
-  - __Filter__: a display filter for this graph (only the packets that pass this filter will be taken into account for this graph)
+Color::
+The color to use for plotting the graph’s lines, bars, or points.
 
-  - __Style__: the style of the graph (Line/Impulse/FBar/Dot)
+Style::
+How to visually represent the graph’s data, e.g. by drawing a line, bar, circle, plus, etc.
 
-* _X Axis_
+Y Axis::
+The value to use for the graph’s Y axis. Can be one of:
 
-  - __Tick interval__: an interval in x direction lasts (10/1 minutes or 10/1/0.1/0.01/0.001 seconds)
+Packets, Bytes, or Bits:::
+The total number of packets, packet bytes, or packet bits that match the graph’s display filter per interval.
+<<ChStatIOGraphsMissingValues, Zero values>> are omitted in some cases.
 
-  - __Pixels per tick__: use 10/5/2/1 pixels per tick interval
+SUM(Y Field):::
+The sum of the values of the field specified in “Y Field” per interval.
 
-  - __View as time of day__: option to view x direction labels as time of day instead of seconds or minutes since beginning of capture
+COUNT FRAMES(Y Field):::
+The number of frames that contain the field specified in “Y Field” per interval.
+Unlike thie plain “Packets” graph, this always displays <<ChStatIOGraphsMissingValues, zero values>>.
 
-* _Y Axis_
+COUNT FIELDS(Y Field):::
+The number of instances of the field specified in “Y Field” per interval.
+Some fields, such as _dns.resp.name_, can show up multiple times in a packet.
 
-  - __Unit__: the unit for the y direction (Packets/Tick, Bytes/Tick, Bits/Tick, Advanced...) [XXX - describe the Advanced feature.]
+MAX(Y Field), MIN(Y Field), AVG(Y Field):::
+The maximum, minimum, and arithmetic mean values of the specified “Y Field” per interval.
+For MAX and MIN values, hovering and clicking the graph will show and take you to the packet with the MAX or MIN value in the interval instead of the most recent packet.
 
-  - __Scale__: the scale for the y unit (Logarithmic,Auto,10,20,50,100,200,500,...)
+// io_graph_item.c says:
+// "LOAD graphs plot the QUEUE-depth of the connection over time"
+// (for response time fields such as smb.time, rpc.time, etc.)
+// This interval is expressed in milliseconds.
+LOAD(Y Field):::
+If the “Y Field” is a relative time value, this is the sum of the “Y Field” values divided by the interval time.
+This can be useful for tracking response times.
 
-The btn:[Save] button will save the currently displayed portion of the graph as one
-of various file formats.
+Y Field::
+The display filter field from which to extract values for the Y axis calculations listed above.
+
+SMA Period::
+Show an average of values over a specified period of intervals.
+
+The chart as a whole can be configured using the controls under the graph list:
+
+btn:[{plus}]::
+Add a new graph.
+
+btn:[-]::
+Add a new graph.
+
+btn:[Copy]::
+Copy the selected graph.
+
+btn:[Clear]::
+Remove all graphs.
+
+Mouse drags / zooms::
+When using the mouse inside the graph area, either drag the graph contents or select a zoom area.
+
+Interval::
+Set the interval period for the graph.
+
+Time of day::
+Switch between showing the absolute time of day or the time relative from the start of capture in the X axis.
+
+Log scale::
+Switch between a logarithmic or linear Y axis.
+
+The main dialog buttons along the bottom let you do the following:
+
+The btn:[Help] button will take you to this section of the User’s Guide.
 
 The btn:[Copy] button will copy values from selected graphs to the clipboard in CSV
 (Comma Separated Values) format.
 
+btn:[Copy from] will let you copy graphs from another profile.
+
+btn:[Close] will close this dialog.
+
+btn:[Save As...] will save the currently displayed graph as an image or CSV data.
 
 [TIP]
 ====
-Click in the graph to select the first package in the selected interval.
+You can see a list of useful keyboard shortcuts by right-clicking on the graph.
 ====
 
-// Applies to the Qt verson:
-// .Missing Values Are Zero
+[[ChStatIOGraphsMissingValues]]
 
-// Wireshark's I/O Graph window doesn’t distinguish between missing and zero values.
-// For _plain_ scatter plots, it is assumed that zero values indicate missing data, and those values are ommitted.
+==== Missing Values Are Zero
+
+Wireshark's I/O Graph window doesn’t distinguish between missing and zero values.
+For scatter plots it is assumed that zero values indicate missing data, and those values are omitted.
+Zero values are shown in line graphs, and bar charts.
+
+// No longer true as of eb4e2cca69.
+// For _plain_ (Packets, Bytes, and Bits) scatter plots, it is assumed that zero values indicate missing data, and those values are omitted.
 // Zero values are shown in line graphs, bar charts, and _calculated_ scatter plots.
 // Scatter plots are considered calculated if they have a calculated Y axis field or if a moving average is set.
 

ui/qt/conversation_dialog.cpp

@@ -228,7 +228,7 @@ void ConversationDialog::graphTcp()
     }
 
     // XXX The GTK+ code opens the TCP Stream dialog. We might want
-    // to open the I/O Graph dialog instead.
+    // to open the I/O Graphs dialog instead.
     QString filter;
     if (conv_item->etype == ENDPOINT_TCP) {
         filter = QString("tcp.stream eq %1").arg(conv_item->conv_id);

ui/qt/io_graph_dialog.cpp

@@ -716,7 +716,7 @@ void IOGraphDialog::reject()
     if (!uat_model_)
         return;
 
-    // Changes to the I/O Graph settings are always saved,
+    // Changes to the I/O Graphs settings are always saved,
     // there is no possibility for "rejection".
     QString error;
     if (uat_model_->applyChanges(error)) {

ui/qt/main_window.ui

@@ -2050,7 +2050,7 @@
   </action>
   <action name="actionStatisticsIOGraph">
    <property name="text">
-    <string>&amp;I/O Graph</string>
+    <string>&amp;I/O Graphs</string>
    </property>
    <property name="toolTip">
     <string>Create graphs based on display filter fields</string>