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

FreeBSD Manual Pages

  
 
  

home | help
MHL(1)			    General Commands Manual			MHL(1)

NAME
       mhl - produce formatted listings	of nmh messages

SYNOPSIS
       /usr/local/libexec/nmh/mhl [-help] [-version] [-bell | -nobell] [-clear
	    | -noclear]	[-folder +folder] [-form formfile] [-length lines]
	    [-width columns] [-moreproc	program] [-nomoreproc] [-fmtproc pro-
	    gram] [-nofmtproc] [files ...]

DESCRIPTION
       mhl is an nmh command for filtering and/or  displaying  text  messages.
       It is the default method	of displaying text messages for	nmh (it	is the
       default showproc).

       As with more, each of the messages specified as arguments (or the stan-
       dard  input)  will  be output.  If more than one	message	file is	speci-
       fied, the user will be prompted prior to	each one, and  a  <RETURN>  or
       <EOT>  will begin the output, with <RETURN> clearing the	screen (if ap-
       propriate), and <EOT> (usually CTRL-D) suppressing  the	screen	clear.
       An  <INTERRUPT> (usually	CTRL-C)	will abort the current message output,
       prompting for the next message (if there	is one), and a <QUIT> (usually
       CTRL- will terminate the	program	(without core dump).

       The  -bell  option  tells mhl to	ring the terminal's bell at the	end of
       each page, while	the -clear option tells	mhl to clear the screen	at the
       end  of	each  page (or output a	formfeed after each message).  Both of
       these switches (and their inverse counterparts) take effect only	if the
       profile entry moreproc is defined but empty, and	mhl is outputting to a
       terminal.  If the moreproc entry	is defined and non-empty, and  mhl  is
       outputting to a terminal, then mhl will cause the moreproc to be	placed
       between the terminal and	mhl and	the switches  are  ignored.   Further-
       more,  if  the  -clear switch is	used and mhl's output is directed to a
       terminal, then mhl will consult the TERM	and TERMCAP environment	 vari-
       ables to	determine the user's terminal type in order to find out	how to
       clear the screen.  If the -clear	switch is given	and  mhl's  output  is
       not directed to a terminal (e.g., a pipe	or a file), then mhl will send
       a formfeed after	each message.

       To override the default moreproc	and the	profile	entry, use the	-more-
       proc  program switch.  Note that	mhl will never start a moreproc	if in-
       voked on	a hardcopy terminal.

       The -length length and -width width switches set	the screen length  and
       width, respectively.  These default to the values indicated by TERMCAP,
       if appropriate, otherwise they default to 40 and	80, respectively.

       The default format file used by mhl is called "mhl.format".   mhl  will
       first  search  for this file in the user's nmh directory, and will then
       search in  the  directory  /usr/local/etc/nmh.	This  default  can  be
       changed by using	the -form formatfile switch.

       Finally,	 the -folder +folder switch sets the nmh folder	name, which is
       used for	the "messagename:" field  described  below.   The  environment
       variable	 $mhfolder  is	consulted  for	the default value, which next,
       show, and prev initialize appropriately.

       mhl operates in two phases: 1) read and parse the format	file,  and  2)
       process	each  message (file).  During phase 1, an internal description
       of the format is	produced as a structured list.	In phase 2, this  list
       is  walked  for	each message, outputting message information under the
       format constraints from the format file.

       The format file can contain information	controlling  screen  clearing,
       screen size, wrap-around	control, transparent text, component ordering,
       and component formatting.  Also,	a list of components to	ignore may  be
       specified,  and a couple	of "special" components	are defined to provide
       added functionality.  Message output will be in the order specified  by
       the order in the	format file.

       Each line of a format file has one of the following forms:

	    ;comment
	    :cleartext
	    variable[,variable...]
	    component:[variable,...]

       o   A line beginning with a `;' is a comment, and is ignored.

       o   A line beginning with a `:' is clear	text, and is output exactly as
	   is.

       o   A line containing only a `:'	produces a blank line in the output.

       o   A line beginning with "component:" defines the format for the spec-
	   ified component,

       o   Remaining lines define the global environment.

       For example, the	line:

	    width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5

       defines the screen size to be 80	columns	by 40 rows, specifies that the
       screen should be	cleared	prior to each page, that the overflow indenta-
       tion is 5, and that overflow text should	be flagged with	"***".

       Following  are  all  of	the current variables and their	arguments.  If
       they follow a component,	they apply only	to that	component,  otherwise,
       their  affect  is  global.  Since the whole format is parsed before any
       output processing, the last global switch setting for  a	 variable  ap-
       plies to	the whole message if that variable is used in a	global context
       (i.e., bell, clearscreen, width,	length).

	    variable	   type	      semantics
	    width	   integer    screen width or component	width
	    length	   integer    screen length or component length
	    offset	   integer    positions	to indent "component: "
	    overflowtext   string     text to use at the beginning of an
				      overflow line
	    overflowoffset integer    positions	to indent overflow lines
	    compwidth	   integer    positions	to indent component text
				      after the	first line is output
	    uppercase	   flag	      output text of this component in all
				      upper case
	    nouppercase	   flag	      don't uppercase
	    clearscreen	   flag/G     clear the	screen prior to	each page
	    noclearscreen  flag/G     don't clearscreen
	    bell	   flag/G     ring the bell at the end of each page
	    nobell	   flag/G     don't bell
	    component	   string/L   name to use instead of "component" for
				      this component
	    nocomponent	   flag	      don't output "component: " for this
				      component
	    center	   flag	      center component on line (works for
				      one-line components only)
	    nocenter	   flag	      don't center
	    leftadjust	   flag	      strip off	leading	whitespace on each
				      line of text
	    noleftadjust   flag	      don't leftadjust
	    rtrim	   flag	      trim whitespace at end of	text lines
	    nortrim	   flag	      retain whitespace	at end of text
				      lines (default)
	    compress	   flag	      change newlines in text to spaces
	    nocompress	   flag	      don't compress
	    wrap	   flag	      Wrap lines that exceed width (default)
	    nowrap	   flag	      Do not perform line wrapping
	    split	   flag	      don't combine multiple fields into
				      a	single field
	    nosplit	   flag	      combine multiple fields into
				      a	single field
	    newline	   flag	      print newline at end of components
				      (this is the default)
	    nonewline	   flag	      don't print newline at end of components
	    formatfield	   string     format string for	this component
				      (see below)
	    decode	   flag	      decode text as RFC 2047 encoded
				      header field
	    addrfield	   flag	      field contains addresses
	    datefield	   flag	      field contains dates
	    format	   flag	      Run component through formatproc filter
				      (body only)
	    noformat	   flag	      Do not run component through
				      formatproc filter	(default)
	    formatarg	   string     Argument to format filter

       To specify the value of	integer-valued	and  string-valued  variables,
       follow  their  name  with an equals-sign	and the	value.	Integer-valued
       variables are given decimal values, while string-valued	variables  are
       given  arbitrary	 text  bracketed by double-quotes.  If a value is suf-
       fixed by	"/G" or	"/L", then its value is	useful in a global-only	or lo-
       cal-only	context	(respectively).

       A line of the form:

	    ignores=component,...

       specifies a list	of components which are	never output.

       The  component  "MessageName" (case-insensitive)	will output the	actual
       message name (file name)	preceded by the	folder name if one  is	speci-
       fied or found in	the environment.  The format is	identical to that pro-
       duced by	the -header option to show.

       The component "Extras" will output all of the components	of the message
       which  were  not	matched	by explicit components,	or included in the ig-
       nore list.  If this component is	not specified, an ignore list  is  not
       needed since all	non-specified components will be ignored.

       If "nocomponent"	is not specified, then the component name will be out-
       put as it appears in the	format file.

       The default format file is:

	    ; mhl.format
	    ;
	    ; default message filter for `show'
	    ;
	    :
	    overflowtext="***",overflowoffset=5
	    leftadjust,compwidth=9
	    ignores=msgid,message-id,received,content-type,content-transfer-encoding,content-id
	    Date:formatfield="%<(nodate{text})%{text}%|%(pretty{text})%>"
	    To:
	    cc:
	    From:formatfield="%(unquote(decode{text}))"
	    Subject:decode
	    :
	    extras:nocomponent
	    :
	    body:nocomponent,overflowtext=,overflowoffset=0,noleftadjust

       The variable "formatfield"  specifies  a	 format	 string	 (see  mh-for-
       mat(5)).	 The flag variables "addrfield"	and "datefield"	(which are mu-
       tually exclusive), tell mhl to interpret	 the  escapes  in  the	format
       string as either	addresses or dates, respectively.

       By default, mhl does not	apply any formatting string to fields contain-
       ing address or dates (see mh-mail(5) for	a list of these	fields).  Note
       that  this  results  in	faster operation since mhl must	parse both ad-
       dresses and dates in order to apply a format string to  them.   If  de-
       sired,  mhl  can	be given a default format string for either address or
       date fields (but	not both).  To do this,	on a global line specify:  ei-
       ther  the  flag addrfield or datefield, along with the appropriate for-
       matfield	variable string.

       The "format" flag specifies that	this component will be run through the
       filter  program specified by the	formatproc profile entry.  This	filter
       program is expected to read data	on standard input and output  data  on
       standard	output.	 Currently the "format"	flag is	only supported for the
       "body" component.  The component	name will be prefixed  to  the	output
       after the filter	has been run.  The expected use	of this	is to filter a
       message body to create more pleasing text to use	in a reply message.  A
       suggested filter	to use for repl(1) is as follows:

	    body:component=">",overflowtext=">",overflowoffset=0,format,nowrap

       The  -fmtproc  and -nofmtproc switches can be used to override the for-
       matproc profile entry.

       The formatarg option specifies a	string that is used as an argument  to
       the format filter.  This	string is processed by mh-format(5) and	all of
       the message components are available for	use.  Multiple	formatarg  op-
       tions can be used to build up multiple arguments	to the format filter.

FILES
       /usr/local/etc/nmh/mhl.format	    The	message	template
       or <mh-dir>/mhl.format		    Rather than	the standard template
       $HOME/.mh_profile		    The	user profile

PROFILE	COMPONENTS
       moreproc:	    Program to use as interactive front-end
       formatproc:	    Program to use as a	filter for components that
			    have the "format" flag set.

SEE ALSO
       show(1),	ap(8), dp(8)

DEFAULTS
       `-bell'
       `-noclear'
       `-length	40'
       `-width 80'

CONTEXT
       None

BUGS
       There  should be	some way to pass `bell'	and `clear' information	to the
       front-end.

       The "nonewline" option interacts	badly with "compress" and "split".

       The "format" option really should work on something other than the body
       component.

nmh-1.7.1			  2014-09-15				MHL(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | PROFILE COMPONENTS | SEE ALSO | DEFAULTS | CONTEXT | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mhl&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help