Return to pick.me CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / usd / 08.mh

Annotation of 43BSDReno/share/doc/usd/08.mh/pick.me, revision 1.1

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

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