home | help 
MH-SEQUENCE(7)			    [mmh-0.4]			  MH-SEQUENCE(7)

NAME
     mh-sequence - sequence specification for mh message system

DESCRIPTION
     A	sequence  (or sequence set) is a symbolic name representing a message or
     collection of messages.  mmh has several internally defined  sequences,  as
     well as allowing users to define their own sequences.

   Message Specification and Pre-Defined Message Sequences
     Most mmh commands accept a `msg' or `msgs' specification, where `msg' indi-
     cates  one message and `msgs' indicates one or more messages.  To designate
     a message, you may use either its number (e.g., 1, 10, 234) or one of these
     `reserved' message names:

	  Name	    Description
	  f	    the first message in the folder
	  p	    the message numerically preceding `c'
	  c	    the most recently accessed message
	  n	    the message numerically following `c'
	  l	    the last message in the folder

     In commands that take a `msg' argument, the default is `c'.

     For example: In a folder containing five messages numbered 5, 10,	94,  177
     and  325, `f' is 5 and `l' is 325.  If `c' is 94, then `p' is 10 and `n' is
     177.

     The word `msgs' indicates that one or more messages may be specified.  Such
     a specification consists of one message designation or of	several  message
     designations separated by spaces.	A message designation consists either of
     a message name as defined above, or a message range.

     A	message  range	is specified as `name1-name2' or `name:i', where `name',
     `name1' and `name2' are message names, and `i' is an integer.

     The specification `name1-name2' designates all currently existing	messages
     from  `name1'  to	`name2'  inclusive.   The  `reserved'  message	name `a'
     (``all'') is a shorthand for the message range `f-l'.

	  Name	    Description
	  a	    all messages in the folder (i.e. `f-l')

     The specification `name:i' designates up to `i' messages.	 These	messages
     start  with  `name'  if  `name'  is a message number or one of the reserved
     names `f' `c', or `n', The messages end with `name' if  `name'  is  `p'  or
     `l'.   The  interpretation of `i' may be overridden by preceding `i' with a
     plus or minus sign; `+i' always means up  to  `i'	messages  starting  with
     `name', and `-i' always means up to `i' messages ending with `name'.

     In  commands  which  accept a `msgs' argument, the default is either `c' or
     `a', depending on which makes more sense for each command (see the individ-
     ual man pages for details).

     Repeated specifications of the same message have the same effect as a  sin-
     gle specification of the message.

     There  is also a special `reserved' message name `b' (``beyond'') which can
     be used with the mhpath command. It refers to the next (not yet used)  mes-
     sage number after `l'.

	  Name	    Description
	  b	    the next message number beyond `l'

   User-Defined Message Sequences
     In  addition to the `reserved' (pre-defined) message names given above, mmh
     supports user-defined sequence names.  User-defined sequences allow the mmh
     user a tremendous amount of power in dealing with groups of messages in the
     same folder by allowing the user to bind a group of messages to a	meaning-
     ful symbolic name.

     The  name	used  to denote a message sequence must consist of an alphabetic
     character followed by zero or more alphanumeric characters, and can not  be
     one  of  the `reserved' message names above.  After defining a sequence, it
     can be used wherever an mmh command expects a `msg' or `msgs' argument.

     Some forms of message ranges are allowed with user-defined sequences.   The
     specification  `name:i'  may be used, and it designates up to the first `i'
     messages (or last `i' messages for `-i') which are elements of the user-de-
     fined sequence `name'.

     The specifications `name:n' and `name:p' may also be used, and they  desig-
     nate  the	next or previous message (relative to the current message) which
     is an element of the  user-defined  sequence  `name'.   The  specifications
     `name:f'  and  `name:l'  are  equivalent to `name:1' and `name:-1', respec-
     tively.  The specification `name:c' is not allowed (use just `c'  instead).
     Note: The syntax of these message range specifications is subject to change
     in the future.

     User-defined  sequence names are specific to each folder.	They are defined
     using the pick and mark commands.

   Public and Private User-Defined Sequences
     There are two varieties of  user-defined  sequences:  public  and	private.
     Public  sequences	of a folder are accessible to any mmh user that can read
     that folder.  They are kept in each folder in the file  determined  by  the
     `Mh-Sequences' profile entry (default is .mh_sequences).  Private sequences
     are  accessible  only  to the mmh user that defined those sequences and are
     kept in the user's mh context file.

     In general, the commands that create sequences (such as pick and mark) will
     create public sequences if the folder for which the sequences are being de-
     fined is writable by the mmh user.  For most commands, this can be overrid-
     den by using the switches -public and  -private.	But  if  the  folder  is
     read-only,  or  if  the  `Mh-Sequences' profile entry is defined but empty,
     then private sequences will be created instead.

   Sequence Negation
     Mmh provides the ability to select all messages not elements of a	user-de-
     fined  sequence.	A special string is used to preface an existing user-de-
     fined sequence name.  This specification then refers to those messages  not
     elements  of  the	specified sequence name.  The default negation prefix is
     the exlamation mark `!', but it may be change to any  string,  by	defining
     the entry `Sequence-Negation' in the mmh profile file.  For example, if the
     profile entry is:

	  Sequence-Negation: not

     then  anytime  an	mmh command is given `notfoo' as a `msg' or `msgs' argu-
     ment, it would substitute all messages that are not  elements  of	the  se-
     quence `foo'.

     Obviously, the user should beware of defining sequences with names that be-
     gin  with	the value of the `Sequence-Negation' profile entry.  The default
     value `!' was chosen due to its similar meaning in the C  programming  lan-
     guage,  and  because  it  cannot be part of a user-defined sequence. But if
     your shell provides history expansion, you might need to quote the  exlama-
     tion mark (prefix it with a backslash).

     To deactivate the negation mechanism, define Sequence-Negation in your pro-
     file to an empty value.

   The Previous Sequence
     Mmh  provides  the  ability  to  remember the `msgs' or `msg' argument last
     given to an mmh command.  The entry `Previous-Sequence' should  be  defined
     in  the  mmh  profile;  its value should be a sequence name or multiple se-
     quence names separated by spaces.	If this entry is defined,  when  an  mmh
     command finishes, it will define the sequence(s) named in the value of this
     entry  to	be  those messages that were specified to the command.	Hence, a
     profile entry of

	  Previous-Sequence: pseq

     directs any mmh command that accepts a `msg' or `msgs' argument  to  define
     the sequence `pseq' as those messages when it finishes.

     Note:  there  can be a performance penalty in using the `Previous-Sequence'
     facility.	If it is used, all mmh programs have to write the  sequence  in-
     formation	to the .mh_sequences file for the folder each time they run.  If
     the `Previous-Sequence' profile entry is not included, only pick  and  mark
     will write to the .mh_sequences file.

   The Unseen Sequence
     Finally,  the unseen sequence indicates which messages have not been previ-
     ously seen by the user.  The commands inc, rcvstore, show, and flist  honor
     the  sequence.   Whenever new messages are placed in a folder (using inc or
     rcvstore), the new messages will also be added to the unseen sequence.

     inc, for example, adds new messages to the unseen sequence.  Unlike the be-
     havior of the previous sequence, however, the unseen sequence will  not  be
     zeroed by inc.

     Similarly,  whenever  show,  next,  or prev display a message, that message
     will be removed from the unseen sequence.

     The default unseen sequence is named `u'.	To change, define a  `Unseen-Se-
     quence'  entry  in  your  profile.   It  may also contain multiple sequence
     names, separated by spaces.  In this case, anything that applied to a  sin-
     gle unseen sequence, applies to multiple ones, too.

     The  unseen  sequence  mechanism is automatically activated.  To deactivate
     it, define the `Unseen-Sequence' entry in your profile with an empty value.

FILES
     $HOME/.mmh/profile 		  The user profile
     $HOME/.mmh/context 		  The user context
     <folder>/.mh_sequences		  File for public sequences

PROFILE COMPONENTS
     Mh-Sequences:	  Name of file to store public sequences
     Sequence-Negation:   To designate messages not in a sequence
     Previous-Sequence:   The last message specification given
     Unseen-Sequence:	  Those messages not yet seen by the user

SEE ALSO
     flist(1), mark(1), pick(1), mh-profile(5)

DEFAULTS
     None

MH.6.8				   2019-01-06			  MH-SEQUENCE(7)
home | help