phpman > info > mhl(1)

MHL(1mh)                                                              MHL(1mh)

NAME
       mhl - produce formatted listings of nmh messages

SYNOPSIS
       /usr/lib/mh/mhl [-help] [-version] [-bell | -nobell] [-clear | -no-
            clear] [-folder +folder] [-form formfile] [-length lines] [-width
            columns] [-moreproc program] [-nomoreproc] [-fmtproc program]
            [-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 /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
       /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(1mh)