1MHL(1)                      General Commands Manual                     MHL(1)
2
3
4

NAME

6       mhl - produce formatted listings of nmh messages
7

SYNOPSIS

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

DESCRIPTION

15       mhl is an nmh command for filtering and/or  displaying  text  messages.
16       It is the default method of displaying text messages for nmh (it is the
17       default showproc).
18
19       As with more, each of the messages specified as arguments (or the stan‐
20       dard  input)  will  be output.  If more than one message file is speci‐
21       fied, the user will be prompted prior to each one, and  a  <RETURN>  or
22       <EOT>  will  begin  the  output,  with <RETURN> clearing the screen (if
23       appropriate), and <EOT> (usually CTRL-D) suppressing the screen  clear.
24       An  <INTERRUPT> (usually CTRL-C) will abort the current message output,
25       prompting for the next message (if there is one), and a <QUIT> (usually
26       CTRL- will terminate the program (without core dump).
27
28       The  -bell  option  tells mhl to ring the terminal's bell at the end of
29       each page, while the -clear option tells mhl to clear the screen at the
30       end  of  each  page (or output a formfeed after each message).  Both of
31       these switches (and their inverse counterparts) take effect only if the
32       profile entry moreproc is defined but empty, and mhl is outputting to a
33       terminal.  If the moreproc entry is defined and non-empty, and  mhl  is
34       outputting to a terminal, then mhl will cause the moreproc to be placed
35       between the terminal and mhl and the switches  are  ignored.   Further‐
36       more,  if  the  -clear switch is used and mhl's output is directed to a
37       terminal, then mhl will consult the TERM and TERMCAP environment  vari‐
38       ables to determine the user's terminal type in order to find out how to
39       clear the screen.  If the -clear switch is given and  mhl's  output  is
40       not directed to a terminal (e.g., a pipe or a file), then mhl will send
41       a formfeed after each message.
42
43       To override the default moreproc and the profile entry, use the  -more‐
44       proc  program  switch.   Note  that  mhl will never start a moreproc if
45       invoked on a hardcopy terminal.
46
47       The -length length and -width width switches set the screen length  and
48       width, respectively.  These default to the values indicated by TERMCAP,
49       if appropriate, otherwise they default to 40 and 80, respectively.
50
51       The default format file used by mhl is called “mhl.format”.   mhl  will
52       first  search  for this file in the user's nmh directory, and will then
53       search in the directory /etc/nmh.  This default can be changed by using
54       the -form formatfile switch.
55
56       Finally,  the -folder +folder switch sets the nmh folder name, which is
57       used for the “messagename:” field  described  below.   The  environment
58       variable  $mhfolder  is  consulted  for  the default value, which next,
59       show, and prev initialize appropriately.
60
61       mhl operates in two phases: 1) read and parse the format file,  and  2)
62       process  each  message (file).  During phase 1, an internal description
63       of the format is produced as a structured list.  In phase 2, this  list
64       is  walked  for  each message, outputting message information under the
65       format constraints from the format file.
66
67       The format file can contain information  controlling  screen  clearing,
68       screen size, wrap-around control, transparent text, component ordering,
69       and component formatting.  Also, a list of components to ignore may  be
70       specified,  and a couple of “special” components are defined to provide
71       added functionality.  Message output will be in the order specified  by
72       the order in the format file.
73
74       Each line of a format file has one of the following forms:
75
76            ;comment
77            :cleartext
78            variable[,variable...]
79            component:[variable,...]
80
81       ·   A line beginning with a `;' is a comment, and is ignored.
82
83       ·   A line beginning with a `:' is clear text, and is output exactly as
84           is.
85
86       ·   A line containing only a `:' produces a blank line in the output.
87
88       ·   A line beginning with “component:” defines the format for the spec‐
89           ified component,
90
91       ·   Remaining lines define the global environment.
92
93       For example, the line:
94
95            width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
96
97       defines the screen size to be 80 columns by 40 rows, specifies that the
98       screen should be cleared prior to each page, that the overflow indenta‐
99       tion is 5, and that overflow text should be flagged with “***”.
100
101       Following  are  all  of  the current variables and their arguments.  If
102       they follow a component, they apply only to that component,  otherwise,
103       their  affect  is  global.  Since the whole format is parsed before any
104       output processing, the  last  global  switch  setting  for  a  variable
105       applies  to the whole message if that variable is used in a global con‐
106       text (i.e., bell, clearscreen, width, length).
107
108            variable       type       semantics
109            width          integer    screen width or component width
110            length         integer    screen length or component length
111            offset         integer    positions to indent “component: ”
112            overflowtext   string     text to use at the beginning of an
113                                      overflow line
114            overflowoffset integer    positions to indent overflow lines
115            compwidth      integer    positions to indent component text
116                                      after the first line is output
117            uppercase      flag       output text of this component in all
118                                      upper case
119            nouppercase    flag       don't uppercase
120            clearscreen    flag/G     clear the screen prior to each page
121            noclearscreen  flag/G     don't clearscreen
122            bell           flag/G     ring the bell at the end of each page
123            nobell         flag/G     don't bell
124            component      string/L   name to use instead of “component” for
125                                      this component
126            nocomponent    flag       don't output “component: ” for this
127                                      component
128            center         flag       center component on line (works for
129                                      one-line components only)
130            nocenter       flag       don't center
131            leftadjust     flag       strip off leading whitespace on each
132                                      line of text
133            noleftadjust   flag       don't leftadjust
134            rtrim          flag       trim whitespace at end of text lines
135            nortrim        flag       retain whitespace at end of text
136                                      lines (default)
137            compress       flag       change newlines in text to spaces
138            nocompress     flag       don't compress
139            wrap           flag       Wrap lines that exceed width (default)
140            nowrap         flag       Do not perform line wrapping
141            split          flag       don't combine multiple fields into
142                                      a single field
143            nosplit        flag       combine multiple fields into
144                                      a single field
145            newline        flag       print newline at end of components
146                                      (this is the default)
147            nonewline      flag       don't print newline at end of components
148            formatfield    string     format string for this component
149                                      (see below)
150            decode         flag       decode text as RFC 2047 encoded
151                                      header field
152            addrfield      flag       field contains addresses
153            datefield      flag       field contains dates
154            format         flag       Run component through formatproc filter
155                                      (body only)
156            noformat       flag       Do not run component through
157                                      formatproc filter (default)
158            formatarg      string     Argument to format filter
159
160       To specify the value of  integer-valued  and  string-valued  variables,
161       follow  their  name  with an equals-sign and the value.  Integer-valued
162       variables are given decimal values, while string-valued  variables  are
163       given  arbitrary  text  bracketed by double-quotes.  If a value is suf‐
164       fixed by “/G” or “/L”, then its value is useful  in  a  global-only  or
165       local-only context (respectively).
166
167       A line of the form:
168
169            ignores=component,...
170
171       specifies a list of components which are never output.
172
173       The  component  “MessageName” (case-insensitive) will output the actual
174       message name (file name) preceded by the folder name if one  is  speci‐
175       fied or found in the environment.  The format is identical to that pro‐
176       duced by the -header option to show.
177
178       The component “Extras” will output all of the components of the message
179       which  were  not  matched  by  explicit  components, or included in the
180       ignore list.  If this component is not specified, an ignore list is not
181       needed since all non-specified components will be ignored.
182
183       If “nocomponent” is not specified, then the component name will be out‐
184       put as it appears in the format file.
185
186       The default format file is:
187
188            ; mhl.format
189            ;
190            ; default message filter for `show'
191            ;
192            :
193            overflowtext="***",overflowoffset=5
194            leftadjust,compwidth=9
195            ignores=msgid,message-id,received,content-type,content-transfer-encoding,content-id
196            Date:formatfield="%<(nodate{text})%{text}%|%(pretty{text})%>"
197            To:
198            cc:
199            From:formatfield="%(unquote(decode{text}))"
200            Subject:decode
201            :
202            extras:nocomponent
203            :
204            body:nocomponent,overflowtext=,overflowoffset=0,noleftadjust
205
206       The variable “formatfield”  specifies  a  format  string  (see  mh-for‐
207       mat(5)).   The  flag  variables  “addrfield” and “datefield” (which are
208       mutually exclusive), tell mhl to interpret the escapes  in  the  format
209       string as either addresses or dates, respectively.
210
211       By default, mhl does not apply any formatting string to fields contain‐
212       ing address or dates (see mh-mail(5) for a list of these fields).  Note
213       that  this  results  in  faster  operation  since  mhl  must parse both
214       addresses and dates in order to apply a  format  string  to  them.   If
215       desired, mhl can be given a default format string for either address or
216       date fields (but not both).  To do this,  on  a  global  line  specify:
217       either the flag addrfield or datefield, along with the appropriate for‐
218       matfield variable string.
219
220       The “format” flag specifies that this component will be run through the
221       filter  program specified by the formatproc profile entry.  This filter
222       program is expected to read data on standard input and output  data  on
223       standard output.  Currently the “format” flag is only supported for the
224       “body” component.  The component name will be prefixed  to  the  output
225       after the filter has been run.  The expected use of this is to filter a
226       message body to create more pleasing text to use in a reply message.  A
227       suggested filter to use for repl(1) is as follows:
228
229            body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
230
231       The  -fmtproc  and -nofmtproc switches can be used to override the for‐
232       matproc profile entry.
233
234       The formatarg option specifies a string that is used as an argument  to
235       the format filter.  This string is processed by mh-format(5) and all of
236       the message components  are  available  for  use.   Multiple  formatarg
237       options  can  be used to build up multiple arguments to the format fil‐
238       ter.
239

FILES

241       /etc/nmh/mhl.format        The message template
242       or <mh-dir>/mhl.format     Rather than the standard template
243       $HOME/.mh_profile          The user profile
244

PROFILE COMPONENTS

246       moreproc:            Program to use as interactive front-end
247       formatproc:          Program to use as a filter for components that
248                            have the “format” flag set.
249

SEE ALSO

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

DEFAULTS

254       `-bell'
255       `-noclear'
256       `-length 40'
257       `-width 80'
258

CONTEXT

260       None
261

BUGS

263       There should be some way to pass `bell' and `clear' information to  the
264       front-end.
265
266       The “nonewline” option interacts badly with “compress” and “split”.
267
268       The “format” option really should work on something other than the body
269       component.
270
271
272
273nmh-1.7.1                         2014-09-15                            MHL(1)
Impressum