Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MH-SEQUENCE(5)		      File Formats Manual		MH-SEQUENCE(5)

       mh-sequence - sequence specification for	nmh message system

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

   Message Specification and Pre-Defined Message Sequences
       Most  nmh  commands accept a `msg' or `msgs' specification, where `msg'
       indicates 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:

	    first  the first message in	the folder
	    last   the last message in the folder
	    cur	   the most recently accessed message
	    prev   the message numerically preceding "cur"
	    next   the message numerically following "cur"

       In commands that	take a `msg' argument, the default  is	"cur".	 As  a
       shorthand, "." is equivalent to "cur".

       For  example:  In a folder containing five messages numbered 5, 10, 94,
       177 and 325, "first" is 5 and "last" is 325.   If  "cur"	 is  94,  then
       "prev" is 10 and	"next" 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,  as  separate  arguments.	 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:n",	 where
       `name', `name1' and `name2' are message names, and `n' is an integer.

       The  specification "name1-name2"	designates all currently existing mes-
       sages from `name1' to `name2' inclusive.	 The "reserved"	 message  name
       "all" is	a shorthand for	the message range "first-last".

       The  specification  "name:n" designates up to `n' messages.  These mes-
       sages start with	`name' if `name' is a message number or	one of the re-
       served  names "first" "cur", or "next", The messages end	with `name' if
       `name' is "prev"	or "last".  The	interpretation of `n' may be  overrid-
       den by preceding	`n' with a plus	or minus sign; `+n' always means up to
       `n' messages starting with `name', and `-n' always means	up to `n' mes-
       sages ending with `name'.

       Substituting  `='  for  `:'  (i.e., "name=n") will reduce the selection
       from a range of up to `n' messages, to a	selection of  just  the	 `n'th
       message.	 So for	example, while "name:-3" selects the 3 messages	ending
       with `name', "name=-3" selects just the 2nd previous message.  It is an
       error  if  the  requested  message  does	 not exist (i.e., there	aren't
       enough messages in the folder).

       In commands which accept	a `msgs' argument, the default is either "cur"
       or "all", depending on which makes more sense for each command (see the
       individual man pages for	details).  Repeated specifications of the same
       message have the	same effect as a single	specification of the message.

       There  is also a	special	"reserved" message name	"new" which is used by
       the mhpath command.

   User-Defined	Message	Sequences
       In addition to the "reserved" (pre-defined) message names given	above,
       nmh supports user-defined sequence names.  User-defined sequences allow
       the nmh 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 meaningful	symbolic name.

       The name	used to	denote a message sequence must consist	of  an	alpha-
       betic  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	nmh command expects a `msg' or
       `msgs' argument.

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

       The  specifications  "name:next"	 and "name:prev" may also be used, and
       they designate the next or previous message (relative  to  the  current
       message)	 which is an element of	the user-defined sequence `name'.  The
       specifications "name:first" and "name:last" are equivalent to  "name:1"
       and  "name:-1",	respectively.  The specification "name:cur" is not al-
       lowed (use just "cur" instead).	The  syntax  of	 these	message	 range
       specifications is subject to change in the future.

       Single  messages	(as opposed to ranges) may also	be selected by substi-
       tuting `=' for `:', as in "name=n".  This  will	reduce	the  selection
       from  being a range of up to `n'	messages, to being a selection of just
       the `n'th message.  So while "seq:5" selects the	first  5  messages  of
       sequence	 `seq',	 "seq=5" selects just the 5th message of the sequence.
       It is an	error if the requested message does  not  exist	 (i.e.,	 there
       aren't at least `n' messages in the sequence).

       User-defined  sequence names are	specific to each folder.  They are de-
       fined 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 nmh 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).  Pri-
       vate sequences are accessible only to the nmh user that	defined	 those
       sequences and are kept in the user's nmh	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 defined is	writable by the	nmh user.  For most commands, this can
       be overridden 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
       Nmh provides the	ability	to select all messages not elements of a user-
       defined	sequence.   To	do this, the user should define	the entry "Se-
       quence-Negation"	in the nmh profile file; its value may be any  string.
       This  string  is	then used to preface an	existing user-defined sequence
       name.  This specification then refers to	those messages not elements of
       the specified sequence name.  For example, if the profile entry is:

	    Sequence-Negation: not

       then any	time an	nmh command is given "notfoo" as a `msg' or `msgs' ar-
       gument, it would	substitute all messages	that are not elements  of  the
       sequence	"foo".

       Obviously, the user should beware of defining sequences with names that
       begin with the value of the "Sequence-Negation" profile entry.

   The Previous	Sequence
       Nmh provides the	ability	to remember the	`msgs' or `msg'	argument  last
       given  to  an nmh command.  The entry "Previous-Sequence" should	be de-
       fined in	the nmh	profile; its value should be a sequence	name or	multi-
       ple  sequence  names, as	separate arguments.  If	this entry is defined,
       when an nmh 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 nmh command that accepts a `msg' or `msgs' argument to  de-
       fine the	sequence "pseq"	as those messages when it finishes.

       Note:  there  can  be  a	performance penalty in using the "Previous-Se-
       quence" facility.  If it	is used, all nmh programs have	to  write  the
       sequence	information 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,	 many users like to indicate which messages have not been pre-
       viously seen by them.  The commands flist, inc, mhshow,	rcvstore,  and
       show  honor  the	profile	entry "Unseen-Sequence"	to support this	activ-
       ity.  This entry	in the .mh_profile should be defined as	 one  or  more
       sequence	 names,	 as  separate arguments.  If there is a	value for "Un-
       seen-Sequence" in the profile, then whenever new	messages are placed in
       a  folder  (using inc or	rcvstore), the new messages will also be added
       to all the sequences named in this profile entry.  For example, a  pro-
       file entry of

	    Unseen-Sequence: unseen

       directs	inc  to	add new	messages to the	sequence "unseen".  Unlike the
       behavior	of the "Previous-Sequence" entry in the	profile, however,  the
       sequence(s) will	not be zeroed by inc.

       Similarly,  whenever  show,  mhshow,  next, or prev displays a message,
       that message will be removed from  any  sequences  named	 by  the  "Un-
       seen-Sequence" entry in the profile.

   Sequence File Format
       The sequence file format	is based on the	RFC 5322 message format.  Each
       line of the sequence file corresponds to	one sequence.  The line	starts
       with the	sequence name followed by a `:', then followed by a space-sep-
       arated list of message numbers that correspond  to  messages  that  are
       part of the named sequence.  A contiguous range of messages can be rep-
       resented	as "lownum-highnum".

       Sample sequence file

	    work: 3 6 8	22-33 46
	    unseen: 47 49-51 54
	    cur: 46

       Nmh commands that modify	the sequence file  will	 silently  remove  se-
       quences	for  nonexistent  messages  when the sequence file is updated.
       The exception to	this is	the "cur" sequence, which is allowed to	 point
       to a nonexistent	message.

   Sequence File Locking
       The  "datalocking" profile entry	controls the type of locking used when
       reading and writing sequence files.  The	locking	 mechanisms  supported
       are  detailed  in mh-profile(5).	 This protects sequence	file integrity
       when multiple nmh commands are run simultaneously.  Nmh	commands  that
       modify the sequence file	use transactional locks; the lock is held from
       the time	the sequence file is read until	it it written out.   This  en-
       sures  that modifications to the	sequence file will not be lost if mul-
       tiple commands are run simultaneously.  Long-running nmh	commands, such
       as  inc	and  pick,  will  release the sequence lock during the bulk of
       their runtime and reread	the sequence file after	 their	processing  is
       complete	to reduce lock contention time.

       Note:  Currently	 transactional locks are only supported	for public se-
       quences;	private	sequences will not get corrupted, but the  possibility
       exists  that two	nmh commands run simultaneously	that add messages to a
       private sequence	could result in	one command's messages	not  appearing
       on the requested	sequence.

       $HOME/.mh-profile   The user's profile.
       <mh-dir>/context	   The user's context.
			   File	for public sequences.

       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.

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


nmh-1.7.1			  2013-10-17			MH-SEQUENCE(5)


Want to link to this manual page? Use this URL:

home | help