Provided by: nmh_1.3-1_i386 bug

NAME

       mhl - produce formatted listings of nmh messages

SYNOPSIS

       /usr/lib/mh/mhl [-bell | -nobell] [-clear | -noclear] [-folder +folder]
            [-form formfile] [-length lines] [-width columns] [-moreproc
            program] [-nomoreproc] [files ...]  [-version] [-help]

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
       standard input) will be output.  If  more  than  one  message  file  is
       specified,  the user will be prompted prior to each one, and a <RETURN>
       or <EOT> will begin the output, with <RETURN> clearing the  screen  (if
       appropriate),  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.
       Furthermore, if the -clear switch is used and mhls output is  directed
       to a terminal, then mhl will consult the $TERM and $TERMCAP environment
       variables to determine the user’s terminal type in order  to  find  out
       how to clear the screen.  If the -clear switch is used 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
       -moreproc program switch.  Note that mhl will never start a moreproc if
       invoked 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 /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 show,
       next, 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,...]

       ·   A line beginning with a ‘;’ is a comment, and is ignored.

       ·   A line beginning with a ‘:’ is clear text, and is output exactly as
           is.

       ·   A line containing only a ‘:’ produces a blank line in the output.

       ·   A line beginning with  “component:”  defines  the  format  for  the
           specified component,

       ·   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
       indentation 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
       applies  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
            compress       flag       change newlines in text to spaces
            nocompress     flag       don’t compress
            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

       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
       suffixed by “/G” or “/L”, then its value is useful in a global-only  or
       local-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
       specified or found in the environment.  The format is identical to that
       produced 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
       ignore 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
       output 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:decode
            Subject:decode
            :
            extras:nocomponent
            :
            body:nocomponent,overflowtext=,overflowoffset=0,noleftadjust

       The   variable   “formatfield”   specifies   a   format   string   (see
       mh-format(5)).   The  flag variables “addrfield” and “datefield” (which
       are mutually 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
       containing 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 addresses and dates in order to apply  a  format  string  to
       them.   If desired, 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:  either  the  flag  addrfield  or  datefield,  along  with the
       appropriate formatfield variable string.

FILES

       /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

SEE ALSO

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

DEFAULTS

-bell’
       ‘-noclear’
       ‘-length40’
       ‘-width80’

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”.