New feature: multi-line triggering.

1 files changed, 90 insertions, 32 deletions

diff --git a/pw.1 b/pw.1
index 8c95cca..1f25b7e 100644
--- a/pw.1
+++ b/pw.1
@@ -184,49 +184,107 @@ and
 also terminate colon mode without executing a command. Colon commands
 are documented in the COLON COMMANDS section below.
 
-.IP "\fB/\fP\fIpattern\fP, \fB?\fP\fIpattern\fP"
-Activate trigger mode if a non-empty
+.IP "[\fIpos\fP]\fB/\fP\fIpattern\fP, [\fIpos\fP]\fB?\fP\fIpattern\fP"
+Set a trigger if a non-empty
 .I pattern
-is specified, or else cancel trigger mode if an empty pattern is
-specified. The
+is specified, or else cancel a trigger if an empty pattern is specified.
+The
 .B /
-command specifies
-.I "head trigger"
+command specifies a
+.I "head-referenced trigger"
 mode, whereas
 .B ?
 specifies
-.I "tail trigger"
+.I "tail-referenced trigger"
 mode.
-Under head trigger mode,
-the display refreshes only when the most recent line ("head line")
-in the FIFO matches the specified
-.IR pattern .
-The head line is the one which will appear at
-the bottom of the display, since newer lines appear at the bottom
-and scroll out toward the top.
-In head trigger mode, the status string
-.BI "TRIG (/" pattern ")"
-appears, showing the pattern preceded by a slash.
-Under tail trigger mode,
-the display refreshes only when the least recent line ("tail line") in the FIFO
-matches the specified
-.IR pattern .
-That line is the one which will appear at
-the top of the display.  In tail trigger mode, the status string
-.BI "TRIG (?" pattern ")"
-appears, showing the pattern preceded by a question mark.
-The
-.I pattern
-is interpreted as either an extended regular expression (ERE)
-or (BRE) depending on the current setting.
+
+Under trigger mode, the display is suspended, similarly to suspend mode.
+It is only refreshed when data arrives into the FIFO such that the
+state of the FIFO then matches certain regular expression patterns.
+
+A head-referenced trigger is relative to most recently received data
+which appears at the bottom of the display. A tail-referenced
+trigger is on least-recently received data, relative to the top
+of the display.  If one or more triggers are set, then trigger
+mode is in effect. If all triggers are removed, trigger mode
+is canceled.
+
+Tail-referenced and head-referenced triggers are mutually exclusive.
+If a tail-referenced trigger command is successfully executed,
+then all head-referenced triggers are removed. Vice versa, a
+tail-referenced trigger command cancels all head-referenced triggers.
+
+If the numeric prefix
+.I pos
+is omitted, or specified as zero, then it defaults to 1.
+The prefix specifies the relative position of the pattern.
+A head-referenced trigger's position is relative to the most
+recent data in the FIFO, and therefore is effectively a
+reverse line number relative to the bottom of the display.
+For example
+.B /foo
+or, equivalently,
+.B 1/foo
+triggers when the bottom line of the display contains a match for
+the expression
+.BR foo .
+Whereas
+.B 3/bar
+triggers when the third line from the bottom matches
+.BR bar .
+To cancel the
+.B 3/bar
+trigger without canceling the
+.B 1/foo
+trigger, the command
+.B 3/
+can be used:
+.B 3/
+with an empty pattern. Inversely, the tail-referenced pattern
+positions are from the top of the display. Thus
+.B ?foo
+or
+.B 1?foo
+trigger when the top line contains a match for
+.BR foo .
+
+If the value of
+.I pos
+specifies a line beyond the display range, or a value greater than 100, the
+command is ignored.
+
 Trigger patterns saved in a history which may be navigated for
 recall using the up and down arrow keys or
 .B Ctrl-P
 and
 .BR Ctrl-N .
-While the trigger pattern is being edited, the current trigger remains
-in effect. Editing a trigger pattern may be canceled with
-.BR ESC .
+While the trigger pattern is being edited, the current set of
+triggers remains in effect. Editing a trigger pattern may be canceled with
+.BR ESC ,
+in which case it is not entered into the history and and the
+trigger command isn't executed.  The history stores only the patterns, not the
+.I pos
+prefix or the
+.B ?
+or
+.B /
+command. Erroneous patterns, and the patterns of ignored commands
+are still entered into the history; empty patterns are not.
+
+The
+.I pattern
+of a newly issued command interpreted as either an extended regular
+expression (ERE) or (BRE) depending on the current setting.
+This is true even if it is recalled from a history entry which had been created
+under a different mode.
+
+In trigger mode, the status string
+.B TRIG/
+or
+.B TRIG?
+is shown followed by the list of triggers in parentheses.
+Patterns which have a position other than 1 are preceded by
+the position shown in square brackets.
 
 .IP "[\fIcount\fP]\fB+\fP"
 Increases the display size by