stap.1: mention a little about the probe point !/? operators

... even though they're listed in stapprobes.3stap also.

diff --git a/stap.1 b/stap.1
index 6c8efbbb71c7494ddfaa9faf811b34875560af38..509e4c9ee5fee20cf31412dce2a1504a0d5d6963 100644 (file)
--- a/stap.1
+++ b/stap.1
@@ -1012,6 +1012,31 @@ listed in the
 .IR stapprobes (3stap)
 manual pages.
 .PP
+All probe points must be resolvable by systemtap against the selected
+kernel/user-space software on the target machine for the script to
+run.  However, it is possible to express probe point preference or
+optionalness with modifying punctuation.
+.SAMPLE
+.BR probe " PROBEPOINT1 " !, " PROBEPOINT2 " { " [STMT ...] " }
+.ESAMPLE
+The
+.BR !
+sign after PROBEPOINT1 means that it is preferred, and if it
+is valid/resolvable, then all subsequent probe points in the list
+should be ignored.  This is useful if there exist multiple ways to
+identify similar events, but some are preferred to others
+(e.g., for reasons of flexibility or performance).
+.SAMPLE
+.BR probe " PROBEPOINT1 " ?, " PROBEPOINT2 " { " [STMT ...] " }
+.ESAMPLE
+The
+.BR ?
+sign after both PROBEPOINT1 indicates that the former is
+optional.  If systemtap cannot resolve that probe point (for
+example, because it names kernel functions or tracepoints that
+do not exist), then that probe point is ignored, and the rest of
+the script is processed.
+.PP
 The probe handler is interpreted relative to the context of each
 event.  For events associated with kernel code, this context may
 include