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 ap‐
23       propriate), 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 in‐
45       voked 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  ap‐
105       plies to the whole message if that variable is used in a global context
106       (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 lo‐
165       cal-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 ig‐
180       nore 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            Resent-To:formatfield="%(unquote(decode{text}))"
197            Resent-cc:formatfield="%(unquote(decode{text}))"
198            Resent-From:formatfield="%(unquote(decode{text}))"
199            Date:formatfield="%<(nodate{text})%{text}%|%(pretty{text})%>"
200            To:formatfield="%(unquote(decode{text}))"
201            cc:formatfield="%(unquote(decode{text}))"
202            From:formatfield="%(unquote(decode{text}))"
203            Subject:decode
204            :
205            extras:nocomponent
206            :
207            body:nocomponent,overflowtext=,overflowoffset=0,noleftadjust
208
209       The variable “formatfield”  specifies  a  format  string  (see  mh-for‐
210       mat(5)).  The flag variables “addrfield” and “datefield” (which are mu‐
211       tually exclusive), tell mhl to interpret  the  escapes  in  the  format
212       string as either addresses or dates, respectively.
213
214       By default, mhl does not apply any formatting string to fields contain‐
215       ing address or dates (see mh-mail(5) for a list of these fields).  Note
216       that  this  results  in  faster operation since mhl must parse both ad‐
217       dresses and dates in order to apply a format string to  them.   If  de‐
218       sired,  mhl  can be given a default format string for either address or
219       date fields (but not both).  To do this, on a global line specify:  ei‐
220       ther  the  flag addrfield or datefield, along with the appropriate for‐
221       matfield variable string.
222
223       The “format” flag specifies that this component will be run through the
224       filter  program specified by the formatproc profile entry.  This filter
225       program is expected to read data on standard input and output  data  on
226       standard output.  Currently the “format” flag is only supported for the
227       “body” component.  The component name will be prefixed  to  the  output
228       after the filter has been run.  The expected use of this is to filter a
229       message body to create more pleasing text to use in a reply message.  A
230       suggested filter to use for repl(1) is as follows:
231
232            body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
233
234       The  -fmtproc  and -nofmtproc switches can be used to override the for‐
235       matproc profile entry.
236
237       The formatarg option specifies a string that is used as an argument  to
238       the format filter.  This string is processed by mh-format(5) and all of
239       the message components are available for use.  Multiple  formatarg  op‐
240       tions can be used to build up multiple arguments to the format filter.
241

FILES

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

PROFILE COMPONENTS

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

SEE ALSO

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

DEFAULTS

256       `-bell'
257       `-noclear'
258       `-length 40'
259       `-width 80'
260

CONTEXT

262       None
263

BUGS

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