mhl



MHL(1)                                                                  MHL(1)




NAME

       mhl - produce formatted listings of nmh messages


SYNOPSIS

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


DESCRIPTION

       Mhl is a 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
       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 scree 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.  Fur-
       thermore, if the `-clear' switch is used and mhl's 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 out-
       put 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
       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, respec-
       tively.

       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 compo-
       nent, and finally, 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
       applies to the whole message if that variable is used in a global  con-
       text (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  suf-
       fixed  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 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
       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 out-
       put as it appears in the format file.

       The default format file is:


       The  variable  "formatfield"  specifies  a  format  string (see mh-for-
       mat (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 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
       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 for-
       matfield 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'
       `-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".



[nmh-1.0.4]                         MH.6.8                              MHL(1)

Man(1) output converted with man2html