[observer] Update user guide

Document the new Ports tab and tracing of ports.

1 files changed, 86 insertions, 23 deletions

diff --git a/lib/observer/doc/src/observer_ug.xml b/lib/observer/doc/src/observer_ug.xml
index be5d249f37..6eb72f3e58 100644
--- a/lib/observer/doc/src/observer_ug.xml
+++ b/lib/observer/doc/src/observer_ug.xml
@@ -168,7 +168,7 @@
       <item><p>The length of the message queue for the process.</p></item>
     </taglist>
 
-    <p>Option <em>Process info</em> opens a detailed information window on the selected process, 
+    <p>Option <em>Process info</em> opens a detailed information window on the process under the mouse pointer,
       including the following:</p>
     <taglist>
       <tag>Process Information</tag>
@@ -195,12 +195,53 @@
       </p>
     </note>
 
-    <p>Option <em>Trace Processes</em> adds the selected process identifiers to tab 
+    <p>Option <em>Trace selected processes</em> adds the selected process identifiers to tab
     <em>Trace Overview</em> plus the node that the processes reside on.
     </p>
-    <p>Option <em>Trace Named Processes</em> adds the registered name of the processes. This can be 
+    <p>Option <em>Trace selected processes by name</em> adds the registered name of the processes. This can be 
     useful when tracing is done on many nodes, as processes with that name are then traced on 
     all traced nodes.</p>
+    <p>Option <em>Kill process</em> brutally kills the processes under
+    the mouse pointer by sending an exit signal with
+    reason <c>kill</c>.</p>
+
+  </section>
+
+  <section>
+    <title>Ports Tab</title>
+    <p>Tab <em>Ports</em> lists port information in columns.
+    For each port the following information is displayed:
+    </p>
+    <taglist>
+      <tag>Id</tag>
+      <item><p>The port identifier.</p></item>
+      <tag>Connected</tag>
+      <item><p>The process identifier for the process that owns the
+	  port.</p></item>
+      <tag>Name</tag>
+      <item><p>The registered name of the port, if any.</p></item>
+      <tag>Controls</tag>
+      <item><p>The name of the command set by <seealso marker="erts:erlang#open_port-2"><c>erlang:open_port/2</c></seealso>.</p></item>
+      <tag>Slot</tag>
+      <item><p>The internal index of the port.</p></item>
+    </taglist>
+
+    <p>Option <em>Port info</em> opens a detailed information window
+      for the port under the mouse pointer. In addition to the
+      information above, it also shows links and monitors.</p>
+
+    <p>Option <em>Trace selected ports</em> adds the selected port
+      identifiers, and the nodes that the ports reside on,
+      to tab <em>Trace Overview</em>.</p>
+
+    <p>Option <em>Trace selected ports by name</em> adds the
+      registered name of the port to tab <em>Trace Overview</em>. This
+      can be useful when tracing is done on many nodes, as ports with
+      that name are then traced on all traced nodes.</p>
+
+    <p>Option <em>Close</em>
+      executes <seealso marker="erts:erlang#port_close-1"><c>erlang:port_close/1</c></seealso>
+      on the port under the mouse pointer.</p>
 
   </section>
 
@@ -211,8 +252,11 @@
     applications are not diplayed. Use menu <em>View</em> to view "system"
     ETS tables, unreadable ETS tables, or Mnesia tables.
     </p>
-    <p>Double-click to view the table content. To view table information, select the table 
-    and activate menu <em>View &gt; Table information</em>.</p>
+    <p>Double-click to view the table content, or right-click and
+    select option <em>Show Table Content</em>. To view table
+    information, select the table and activate menu <em>View &gt;
+    Table information</em>, or right-click and select option <em>Table
+    info</em>.</p>
     <p>You can use <seealso marker="stdlib:re">regular
     expressions</seealso> and search for objects, and edit or delete them.
     </p>
@@ -220,11 +264,12 @@
 
   <section>
     <title>Trace Overview Tab</title>
-    <p>Tab <em>Trace Overview</em> handles tracing. Trace
-    by selecting the processes to be traced and how to trace
-    them. You can trace messages, function calls, and events, where
-    events are process-related events such as <c>spawn</c>,
-    <c>exit</c>, and many others.
+    <p>Tab <em>Trace Overview</em> handles tracing. Trace by selecting
+    the processes or ports to be traced and how to trace them. For
+    processes, you can trace messages, function calls, scheduling,
+    garbage collections, and process-related events such
+    as <c>spawn</c>, <c>exit</c>, and many others. For ports, you can
+    trace messages, scheduling and port-related events.
     </p>
 
     <p>To trace function calls, you also need to set up
@@ -234,31 +279,49 @@
     specifications can also be used to trigger more information
     in the trace messages.
     </p>
-    <note><p>Trace patterns only apply to the traced processes.</p></note>
+
+    <p>You can also set match specifications on messages. By default,
+    if tracing messages, all messages sent and/or received by the
+    process or port are traced. Match specifications can be used to
+    reduce the number of traced messages and/or to trigger more
+    information in the trace messages.</p>
+
+    <note><p>Trace patterns only apply to the traced processes and
+    ports.</p></note>
 
     <p>
-      Processes are added from the <em>Applications</em> or <em>Processes</em> tabs.
-      A special <em>new</em> identifier, meaning all processes spawned after trace 
-      start, can be added with button <em>Add 'new' Process</em>.
+      Processes are added from the <em>Applications</em>
+      or <em>Processes</em> tabs. Ports are added from
+      the <em>Ports</em> tab.  A special <em>new</em> identifier,
+      meaning all processes, or ports, started after trace start, can
+      be added with buttons <em>Add 'new' Processes</em> and <em>Add
+      'new' Ports</em>, respecively.
     </p>
     <p>
-      When adding processes, a window with trace options is displayed. The chosen 
-      options are set for the selected processes.
-      Process options can be changed by right-clicking a process.
+      When adding processes or ports, a window with trace options is
+      displayed. The chosen options are set for the selected
+      processes/ports.  To change the options, right-click the process
+      or port and select <em>Edit process options</em>. To remove a
+      process or port from the list, right-click and select <em>Remove
+      process</em> or <em>Remove port</em>, respectively.
     </p>
     <p>
-      Processes added by process identifiers add the nodes these
-      processes reside on in the node list. More nodes can be added by clicking 
-      button <em>Add Nodes</em>.
+      Processes and ports added by process/port identifiers add the
+      nodes these processes/ports reside on in the node list. More
+      nodes can be added by clicking button <em>Add Nodes</em>, or by
+      right-clicking in the <em>Nodes</em> list and select <em>Add
+      Nodes</em>. To remove nodes, select them, then right-click and
+      choose <em>Remove nodes</em>.
     </p>
     <p>
       If function calls are traced, trace patterns must be added by clicking button
       <em>Add Trace Pattern</em>. Select a module, function(s), and a match specification.
       If no functions are selected, all functions in the module are traced.</p>
     <p>
-      Trace patterns can also be added for traced messages. This is
-      done in the same way as for traced function calls. Separate
-      trace patterns must be set for sent and received messages.
+      Trace patterns can also be added for traced messages. Click
+      button <em>Add Trace Pattern</em> and select <em>Messages
+      sent</em> or <em>Messages received</em>, and a match
+      specification.
     </p>
     <p>
       A few basic match specifications are provided in the tool, and