Return to pick.rf CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / mh / conf / doc

Annotation of 43BSD/contrib/mh/conf/doc/pick.rf, revision 1.1

1.1     ! root        1: .\"    @(MHWARNING)
        !             2: .TH PICK 1 "April 22, 1986" MH [mh.6]
        !             3: .UC 6
        !             4: .SH NAME
        !             5: pick \- select messages by content
        !             6: .SH SYNOPSIS
        !             7: .in +.5i
        !             8: .ti -.5i
        !             9: .ie t \{\
        !            10: .ta .4i 1.8i
        !            11: .nf
        !            12: .in .5i
        !            13: ^pick~^^\0\-cc~^ \%[+folder] \%[msgs] \%[\-help]
        !            14: ^^^\0\-date~^ \%[\-before\ date] \%[\-after\ date] \%[\-datefield\ field]
        !            15: ^^^\0\-from~^
        !            16: ^^^\s+2\b'\(lt\(bv\(bv\(lk\(bv\(bv\(lb'\s0\-search~\s+2\b'\(rt\(bv\(bv\(rk\(bv\(bv\(rb'\s0^ pattern \%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...] \%[\-lbrace\ ...\ \-rbrace]
        !            17: ^^^\0\-subject~^
        !            18: ^^^\0\-to~^ \%[\-sequence\ name\ ...] \%[\-public] \%[\-nopublic] \%[\-zero] \%[\-nozero]
        !            19: ^^^\0\-\|\-component~^ \%[\-list] \%[\-nolist]
        !            20: .fi
        !            21: .re
        !            22: .in 1i
        !            23: .\}
        !            24: .el \{\
        !            25: .ti .5i
        !            26: pick
        !            27: \%[+folder] \%[msgs]
        !            28: \%[\-and\ ...] \%[\-or\ ...] \%[\-not\ ...] \%[\-lbrace\ ...\ \-rbrace]
        !            29: \%[\-\|\-component\ pattern]
        !            30: \%[\-after\ date] \%[\-before\ date] \%[\-datefield\ field]
        !            31: \%[\-sequence\ name\ ...]
        !            32: \%[\-public] \%[\-nopublic]
        !            33: \%[\-zero] \%[\-nozero]
        !            34: \%[\-list] \%[\-nolist]
        !            35: \%[\-help]
        !            36: .\}
        !            37: 
        !            38: .ti .5i
        !            39: typically:
        !            40: .br
        !            41: scan\0`pick\0\-from\0jones`
        !            42: .br
        !            43: pick\0\-to\0holloway\0\-sequence\0select
        !            44: .br
        !            45: show\0`pick\0\-before\0friday`
        !            46: .in -.5i
        !            47: .SH DESCRIPTION
        !            48: \fIPick\fR searches messages within a folder for the specified
        !            49: contents, and then identifies those messages.
        !            50: Two types of search primitives are available:
        !            51: pattern matching and date constraint operations.
        !            52: 
        !            53: A modified \fIgrep\fR(1) is used to perform the matching, so the
        !            54: full regular expression (see \fIed\fR(1)) facility is available
        !            55: within `pattern'.
        !            56: With `\-search', `pattern' is used directly,
        !            57: and with the others, the grep pattern constructed is:
        !            58: 
        !            59: .ti +.5i
        !            60: \*(lqcomponent[ \\t]*:\&.*pattern\*(rq
        !            61: 
        !            62: This means that the pattern specified for a `\-search' will be
        !            63: found everywhere in the message, including the header and the body,
        !            64: while the other pattern matching requests are limited to the single
        !            65: specified component.
        !            66: The expression
        !            67: 
        !            68: .ti +.5i
        !            69: `\-\-component\ pattern'
        !            70: 
        !            71: is a shorthand for specifying
        !            72: 
        !            73: .ti +.5i
        !            74: `\-search \*(lqcomponent[ \\t]*:\&.*pattern\*(rq\ '
        !            75: 
        !            76: It is used to pick a component which is not one of
        !            77: \*(lqTo:\*(rq, \*(lqcc:\*(rq, \*(lqDate:\*(rq, \*(lqFrom:\*(rq,
        !            78: or \*(lqSubject:\*(rq.
        !            79: An example is `pick\0\-\-reply\-to\0pooh'.
        !            80: 
        !            81: Pattern matching is performed on a per\-line basis.
        !            82: Within the header of
        !            83: the message, each component is treated as one long line, but in
        !            84: the body, each line is separate.
        !            85: Lower\-case letters in the
        !            86: search pattern will match either lower or upper case in the
        !            87: message, while upper case will match only upper case.
        !            88: 
        !            89: Independent of any pattern matching operations requested,
        !            90: the switches `\-after date' or `\-before date' may also be used
        !            91: to introduce date/time contraints on all of the messages.
        !            92: By default, the \*(lqDate:\*(rq field is consulted,
        !            93: but if another date yielding field
        !            94: (such as \*(lqBB\-Posted:\*(rq or \*(lqDelivery\-Date:\*(rq) should be used,
        !            95: the `\-datefield\ field' switch may be used.
        !            96: \fIPick\fR will actually parse the date fields in each of the messages
        !            97: specified in `msgs'
        !            98: (unlike the `\-date' switch described above which does a pattern matching
        !            99: operation),
        !           100: and compare them to the date/time specified by use of the `\-after'
        !           101: and `\-before' switches.
        !           102: If `\-after' is given,
        !           103: then only those messages whose \*(lqDate:\*(rq field value
        !           104: is chronologically after
        !           105: the date specified will be considered.
        !           106: The `\-before' switch specifies the complimentary action.
        !           107: 
        !           108: Both the `\-after' and `\-before' switches take legal 822\-style date
        !           109: specifications as arguments.
        !           110: \fIPick\fR will default certain missing fields so that the entire date
        !           111: need not be specified.
        !           112: These fields are (in order of defaulting):
        !           113: timezone, time and timezone, date, date and timezone.
        !           114: All defaults are taken from the current date, time, and timezone.
        !           115: In addition to 822\-style dates,
        !           116: \fIpick\fR will also recognize any of the days of the week
        !           117: (\*(lqsunday\*(rq, \*(lqmonday\*(rq, and so on),
        !           118: and the special dates
        !           119: \*(lqtoday\*(rq, \*(lqyesterday\*(rq, and \*(lqtomorrow\*(rq.
        !           120: All days of the week are judged to refer to a day in the past
        !           121: (e.g., telling \fIpick\fR \*(lqsaturday\*(rq on
        !           122: a \*(lqtuesday\*(rq means \*(lqlast\ saturday\*(rq
        !           123: not \*(lqthis\ saturday\*(rq).
        !           124: Finally, in addition to these special specifications,
        !           125: \fIpick\fR will also honor a specification of the form \*(lq\-dd\*(rq,
        !           126: which means \*(lqdd days ago\*(rq.
        !           127: 
        !           128: \fIPick\fR supports complex boolean operations on the searching primitives
        !           129: with the `\-and', `\-or', `\-not', and `\-lbrace\ ...\ \-rbrace' switches.
        !           130: For example,
        !           131: 
        !           132: .ti +.5i
        !           133: pick\0\-after\0yesterday\0\-and\0\-lbrace\0\-from\0freida\0\-or\0\-from\0fear\0\-rbrace
        !           134: 
        !           135: identifies messages recently sent by \*(lqfrieda\*(rq or \*(lqfear\*(rq.
        !           136: 
        !           137: The matching primitives take precedence over the `\-not' switch,
        !           138: which in turn takes precedence over `\-and'
        !           139: which in turn takes precedence over `\-or'.
        !           140: To override the default precedence,
        !           141: the `\-lbrace' and `\-rbrace' switches are provided,
        !           142: which act just like opening and closing parentheses in logical expressions.
        !           143: 
        !           144: Once the search has been performed,
        !           145: if the `\-list' switch is given,
        !           146: the message numbers of the selected messages are written to the standard
        !           147: output separated by newlines.
        !           148: This is \fIextremely\fR useful for quickly generating arguments for other
        !           149: \fIMH\fR programs by using the \*(lqbackquoting\*(rq syntax of the shell.
        !           150: For example,
        !           151: the command
        !           152: 
        !           153: .ti +.5i
        !           154: scan\0`pick\0+todo\0\-after\0\*(lq31 Mar 83 0123 PST\*(rq`
        !           155: 
        !           156: says to \fIscan\fR those messages in the indicated folder which meet the
        !           157: appropriate criterion.
        !           158: Note that since \fIpick\fR\0's context changes are written out prior to
        !           159: \fIscan\fR\0's invocation,
        !           160: you need not give the folder argument to \fIscan\fR as well.
        !           161: 
        !           162: Regardless of the operation of the `\-list' switch,
        !           163: the `\-sequence name' switch may be given once for each sequence the user
        !           164: wishes to define.
        !           165: For each sequence named,
        !           166: that sequence will be defined to mean exactly those messages selected by
        !           167: \fIpick\fR.
        !           168: For example,
        !           169: 
        !           170: .ti +.5i
        !           171: pick\0\-from\0frated\0\-seq\0fred
        !           172: 
        !           173: defines a new message sequence for the current folder called \*(lqfred\*(rq
        !           174: which contains exactly those messages that were selected.
        !           175: 
        !           176: Note that whenever \fIpick\fR processes a `\-sequence\ name' switch,
        !           177: it sets `\-nolist'.
        !           178: 
        !           179: By default, \fIpick\fR will zero the sequence before adding it.
        !           180: This action can be disabled with the `\-nozero' switch,
        !           181: which means that the messages selected by \fIpick\fR will be added to the
        !           182: sequence, if it already exists, and any messages already a part of that
        !           183: sequence will remain so.
        !           184: 
        !           185: The `\-public' and `\-nopublic' switches are used by \fIpick\fR in the same
        !           186: way \fImark\fR uses them.
        !           187: .Fi
        !           188: ^$HOME/\&.mh\(ruprofile~^The user profile
        !           189: .Pr
        !           190: ^Path:~^To determine the user's MH directory
        !           191: .Ps
        !           192: ^Current\-Folder:~^To find the default current folder
        !           193: .Sa
        !           194: mark(1)
        !           195: .De
        !           196: `+folder' defaults to the current folder
        !           197: .Ds
        !           198: `msgs' defaults to all
        !           199: .Ds
        !           200: `\-datefield date'
        !           201: .Ds
        !           202: `\-nopublic' if the folder is read\-only, `\-public' otherwise
        !           203: .Ds
        !           204: `\-zero'
        !           205: .Ds
        !           206: `\-list' is the default if no `\-sequence', `\-nolist' otherwise
        !           207: .Co
        !           208: If a folder is given, it will become the current folder.
        !           209: .Hi
        !           210: In previous versions of \fIMH\fR,
        !           211: the \fIpick\fR command would \fIshow\fR, \fIscan\fR, or \fIrefile\fR the
        !           212: selected messages.
        !           213: This was rather \*(lqinverted logic\*(rq from the UNIX point of view,
        !           214: so \fIpick\fR was changed to define sequences and output those sequences.
        !           215: Hence, \fIpick\fR can be used to generate the arguments for all other
        !           216: \fIMH\fR commands,
        !           217: instead of giving \fIpick\fR endless switches for invoking those commands
        !           218: itself.
        !           219: 
        !           220: Also, previous versions of \fIpick\fR balked if you didn't specify a search
        !           221: string or a date/time constraint.
        !           222: The current version does not, and merely matches the messages you specify.
        !           223: This lets you type something like:
        !           224: 
        !           225: .ti +.5i
        !           226: show\0`pick\0last:20\0\-seq\0fear`
        !           227: 
        !           228: instead of typing
        !           229: 
        !           230: .in +.5i
        !           231: .nf
        !           232: mark\0\-add\0\-nozero\0\-seq\0fear\0last:20
        !           233: show\0fear
        !           234: .fi
        !           235: .in -.5i
        !           236: 
        !           237: Finally,
        !           238: timezones used to be ignored when comparing dates:
        !           239: they aren't any more.
        !           240: .Bu
        !           241: The argument to the `\-after' and `\-before' switches must be interpreted
        !           242: as a single token by the shell that invokes \fIpick\fR.
        !           243: Therefore,
        !           244: one must usually place the argument to this switch inside double\-quotes.
        !           245: Furthermore,
        !           246: any occurance of `\-datefield' must occur prior to the `\-after'
        !           247: or `\-before' switch it applies to.
        !           248: 
        !           249: If \fIpick\fR is used in a back\-quoted operation,
        !           250: such as
        !           251: 
        !           252: .ti +.5i
        !           253: scan\0`pick\0\-from\0jones`
        !           254: 
        !           255: and \fIpick\fR fails (e.g., no messages are from \*(lqjones\*(rq),
        !           256: then the shell will still run the outer command (e.g., \*(lqscan\*(rq).
        !           257: Since no messages were matched,
        !           258: \fIpick\fR produced no output,
        !           259: and the argument given to the outer command as a result of backquoting
        !           260: \fIpick\fR is empty.
        !           261: In the case of \fIMH\fR programs,
        !           262: the outer command now acts as if the default `msg' or `msgs' should be used
        !           263: (e.g., \*(lqall\*(rq in the case of \fIscan\fR\0).
        !           264: To prevent this unexpected behavior,
        !           265: if `\-list' was given,
        !           266: and if its standard output is not a tty,
        !           267: then \fIpick\fR outputs the illegal message number \*(lq0\*(rq when it fails.
        !           268: This lets the outer command fail gracefully as well.
        !           269: .En

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.