1MHL(1)                             [nmh-1.3]                            MHL(1)
2
3
4

NAME

6       mhl - produce formatted listings of nmh messages
7

SYNOPSIS

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

DESCRIPTION

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

FILES

211       /etc/nmh/mhl.format        The message template
212       or <mh-dir>/mhl.format     Rather than the standard template
213       $HOME/.mh_profile          The user profile
214
215

PROFILE COMPONENTS

217       moreproc:            Program to use as interactive front-end
218
219

SEE ALSO

221       show(1), ap(8), dp(8)
222
223

DEFAULTS

225       `-bell'
226       `-noclear'
227       `-length40'
228       `-width80'
229
230

CONTEXT

232       None
233
234

BUGS

236       There  should be some way to pass `bell' and `clear' information to the
237       front-end.
238
239       The “nonewline” option interacts badly with “compress” and “split”.
240
241
242
243MH.6.8                            1 June 2008                           MHL(1)
Impressum