diplodocus.org Git - nmh/blob - man/mhl.man

   1 .TH MHL %manext1% "September 14, 2014" "%nmhversion%"
   2 .\"
   3 .\" %nmhwarning%
   4 .\"
   5 .SH NAME
   6 mhl \- produce formatted listings of nmh messages
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B %nmhlibexecdir%/mhl
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RB [ \-bell " | " \-nobell ]
  14 .RB [ \-clear " | " \-noclear ]
  15 .RB [ \-folder
  16 .IR +folder ]
  17 .RB [ \-form
  18 .IR formfile ]
  19 .RB [ \-length
  20 .IR lines ]
  21 .RB [ \-width
  22 .IR columns ]
  23 .RB [ \-moreproc
  24 .IR program ]
  25 .RB [ \-nomoreproc ]
  26 .RB [ \-fmtproc
  27 .IR program ]
  28 .RB [ \-nofmtproc ]
  29 .RI [ files
  30 .IR \&... ]
  31 .ad
  32 .SH DESCRIPTION
  33 .B Mhl
  34 is an
  35 .B nmh
  36 command for filtering and/or displaying text
  37 messages.  It is the default method of displaying text messages for
  38 .B nmh
  39 (it is the default
  40 .IR showproc ).
  41 .PP
  42 As with
  43 .BR more ,
  44 each of the messages specified as arguments (or
  45 the standard input) will be output.  If more than one message file is
  46 specified, the user will be prompted prior to each one, and a <RETURN>
  47 or <EOT> will begin the output, with <RETURN> clearing the screen (if
  48 appropriate), and <EOT> (usually CTRL\-D) suppressing the screen clear.
  49 An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
  50 prompting for the next message (if there is one), and a <QUIT> (usually
  51 CTRL-\\) will terminate the program (without core dump).
  52 .PP
  53 The
  54 .B \-bell
  55 option tells
  56 .B mhl
  57 to ring the terminal's bell at the
  58 end of each page, while the
  59 .B \-clear
  60 option tells
  61 .B mhl
  62 to clear the
  63 screen at the end of each page (or output a formfeed after each message).
  64 Both of these switches (and their inverse counterparts) take effect only
  65 if the profile entry
  66 .I moreproc
  67 is defined but empty, and
  68 .B mhl
  69 is outputting to a terminal.  If the
  70 .I moreproc
  71 entry is defined and
  72 non-empty, and
  73 .B mhl
  74 is outputting to a terminal, then
  75 .B mhl
  76 will
  77 cause the
  78 .I moreproc
  79 to be placed between the terminal and
  80 .B mhl
  81 and the switches are ignored.  Furthermore, if the
  82 .B \-clear
  83 switch is
  84 used and \fImhl's\fR output is directed to a terminal, then
  85 .B mhl
  86 will consult the
  87 .B $TERM
  88 and
  89 .B $TERMCAP
  90 environment variables
  91 to determine the user's terminal type in order to find out how to clear
  92 the screen.  If the
  93 .B \-clear
  94 switch is used and
  95 .BR mhl 's
  96 output is
  97 not directed to a terminal (e.g., a pipe or a file), then
  98 .B mhl
  99 will
 100 send a formfeed after each message.
 101 .PP
 102 To override the default
 103 .I moreproc
 104 and the profile entry, use the
 105 .B \-moreproc
 106 .I program
 107 switch.  Note that
 108 .B mhl
 109 will never start a
 110 .I moreproc
 111 if invoked on a hardcopy terminal.
 112 .PP
 113 The
 114 .B \-length
 115 .I length
 116 and
 117 .B \-width
 118 .I width
 119 switches set the screen
 120 length and width, respectively.  These default to the values indicated by
 121 .BR $TERMCAP ,
 122 if appropriate, otherwise they default to 40 and 80, respectively.
 123 .PP
 124 The default format file used by
 125 .B mhl
 126 is called
 127 .RI \*(lq mhl.format \*(rq.
 128 .B mhl
 129 will first search for this file in the user's
 130 .B nmh
 131 directory, and will then search in the directory
 132 .IR %nmhetcdir% .
 133 This default
 134 can be changed by using the
 135 .B \-form
 136 .I formatfile
 137 switch.
 138 .PP
 139 Finally, the
 140 .B \-folder
 141 .I +folder
 142 switch sets the
 143 .B nmh
 144 folder name,
 145 which is used for the \*(lqmessagename:\*(rq field described below.  The
 146 environment variable
 147 .B $mhfolder
 148 is consulted for the default value,
 149 which
 150 .BR show ,
 151 .BR next ,
 152 and
 153 .B prev
 154 initialize appropriately.
 155 .PP
 156 .B Mhl
 157 operates in two phases: 1) read and parse the format file, and
 158 2) process each message (file).  During phase 1, an internal description
 159 of the format is produced as a structured list.  In phase 2, this list
 160 is walked for each message, outputting message information under the
 161 format constraints from the format file.
 162 .PP
 163 The format file can contain information controlling screen clearing,
 164 screen size, wrap\-around control, transparent text, component ordering,
 165 and component formatting.  Also, a list of components to ignore may be
 166 specified, and a couple of \*(lqspecial\*(rq components are defined
 167 to provide added functionality.  Message output will be in the order
 168 specified by the order in the format file.
 169 .PP
 170 Each line of a format file has one of the following forms:
 171 .PP
 172 .RS 5
 173 .nf
 174 ;comment
 175 :cleartext
 176 variable[,variable...]
 177 component:[variable,...]
 178 .fi
 179 .RE
 180 .PP
 181 .IP \(bu 4
 182 A line beginning with a `;' is a comment, and is ignored.
 183 .IP \(bu 4
 184 A line beginning with a `:' is clear text, and is output exactly as is.
 185 .IP \(bu 4
 186 A line containing only a `:' produces a blank line in the output.
 187 .IP \(bu 4
 188 A line beginning with \*(lqcomponent:\*(rq defines the format for the specified
 189 component,
 190 .IP \(bu 4
 191 Remaining lines define the global environment.
 192 .PP
 193 For example, the line:
 194 .PP
 195 .RS 5
 196 width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
 197 .RE
 198 .PP
 199 defines the screen size to be 80 columns by 40 rows, specifies that the
 200 screen should be cleared prior to each page, that the overflow indentation
 201 is 5, and that overflow text should be flagged with \*(lq***\*(rq.
 202 .PP
 203 Following are all of the current variables and their arguments.  If they
 204 follow a component, they apply only to that component, otherwise, their
 205 affect is global.  Since the whole format is parsed before any output
 206 processing, the last global switch setting for a variable applies to
 207 the whole message if that variable is used in a global context (i.e.,
 208 bell, clearscreen, width, length).
 209 .PP
 210 .RS 5
 211 .nf
 212 .ta \w'noclearscreen  'u +\w'integer/G  'u
 213 .I "variable    type    semantics"
 214 width   integer screen width or component width
 215 length  integer screen length or component length
 216 offset  integer positions to indent \*(lqcomponent: \*(rq
 217 overflowtext    string  text to use at the beginning of an
 218                 overflow line
 219 overflowoffset  integer positions to indent overflow lines
 220 compwidth       integer positions to indent component text
 221                 after the first line is output
 222 uppercase       flag    output text of this component in all
 223                 upper case
 224 nouppercase     flag    don't uppercase
 225 clearscreen     flag/G  clear the screen prior to each page
 226 noclearscreen   flag/G  don't clearscreen
 227 bell    flag/G  ring the bell at the end of each page
 228 nobell  flag/G  don't bell
 229 component       string/L        name to use instead of \*(lqcomponent\*(rq for
 230                 this component
 231 nocomponent     flag    don't output \*(lqcomponent: \*(rq for this
 232                 component
 233 center  flag    center component on line (works for
 234                 one\-line components only)
 235 nocenter        flag    don't center
 236 leftadjust      flag    strip off leading whitespace on each
 237                 line of text
 238 noleftadjust    flag    don't leftadjust
 239 rtrim   flag    trim whitespace at end of text lines
 240 nortrim flag    retain whitespace at end of text
 241                 lines (default)
 242 compress        flag    change newlines in text to spaces
 243 nocompress      flag    don't compress
 244 wrap    flag    Wrap lines that exceed width (default)
 245 nowrap  flag    Do not perform line wrapping
 246 split   flag    don't combine multiple fields into
 247                 a single field
 248 nosplit flag    combine multiple fields into
 249                 a single field
 250 newline flag    print newline at end of components
 251                 (this is the default)
 252 nonewline       flag    don't print newline at end of components
 253 formatfield     string  format string for this component
 254                 (see below)
 255 decode  flag    decode text as RFC 2047 encoded
 256                 header field
 257 addrfield       flag    field contains addresses
 258 datefield       flag    field contains dates
 259 format  flag    Run component through formatproc filter
 260                 (body only)
 261 noformat        flag    Do not run component through
 262                 formatproc filter (default)
 263 formatarg       string  Argument to format filter
 264 .fi
 265 .RE
 266 .PP
 267 To specify the value of integer\-valued and string\-valued variables,
 268 follow their name with an equals\-sign and the value.  Integer\-valued
 269 variables are given decimal values, while string\-valued variables
 270 are given arbitrary text bracketed by double\-quotes.  If a value is
 271 suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq, then its value is useful in
 272 a global\-only or local\-only context (respectively).
 273 .PP
 274 A line of the form:
 275 .PP
 276 .RS 5
 277 ignores=component,...
 278 .RE
 279 .PP
 280 specifies a list of components which are never output.
 281 .PP
 282 The component \*(lqMessageName\*(rq (case\-insensitive) will output the
 283 actual message name (file name) preceded by the folder name if one is
 284 specified or found in the environment.  The format is identical to that
 285 produced by the
 286 .B \-header
 287 option to
 288 .BR show .
 289 .PP
 290 The component \*(lqExtras\*(rq will output all of the components of the
 291 message which were not matched by explicit components, or included in
 292 the ignore list.  If this component is not specified, an ignore list is
 293 not needed since all non\-specified components will be ignored.
 294 .PP
 295 If \*(lqnocomponent\*(rq is NOT specified, then the component name will
 296 be output as it appears in the format file.
 297 .PP
 298 The default format file is:
 299 .PP
 300 .RS 5
 301 .nf
 302 %mhl_format%
 303 .fi
 304 .RE
 305 .PP
 306 The variable \*(lqformatfield\*(rq specifies a format string (see
 307 .IR mh\-format (5)).
 308 The flag variables \*(lqaddrfield\*(rq and
 309 \*(lqdatefield\*(rq (which are mutually exclusive), tell
 310 .B mhl
 311 to interpret the escapes in the format string as either addresses or
 312 dates, respectively.
 313 .PP
 314 By default,
 315 .B mhl
 316 does not apply any formatting string to fields
 317 containing address or dates (see
 318 .IR mh\-mail (5)
 319 for a list of these
 320 fields).  Note that this results in faster operation since
 321 .B mhl
 322 must parse both addresses and dates in order to apply a format string
 323 to them.  If desired,
 324 .B mhl
 325 can be given a default format string for
 326 either address or date fields (but not both).  To do this, on a global
 327 line specify: either the flag addrfield or datefield, along with the
 328 appropriate formatfield variable string.
 329 .PP
 330 The \*(lqformat\*(rq flag specifies that this component will be run through
 331 the filter program specified by the
 332 .IR formatproc
 333 profile entry.  This filter program is expected to read data on standard
 334 input and output data on standard output.  Currently the \*(lqformat\*(rq
 335 flag is only supported for the \*(lqbody\*(rq component.  The component
 336 name will be prefixed to the output
 337 .IR after
 338 the filter has been run.  The expected use of this is to filter a message
 339 body to create more pleasing text to use in a reply message.
 340 A suggested filter to use for
 341 .IR repl(1)
 342 is as follows:
 343 .PP
 344 .RS 5
 345 body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
 346 .RE
 347 .PP
 348 The
 349 .B \-fmtproc
 350 and
 351 .B \-nofmtproc
 352 switches can be used to override the
 353 .I formatproc
 354 profile entry.
 355 .PP
 356 The
 357 .I formatarg
 358 option specifies a string that is used as an argument to the format filter.
 359 This string is processed by
 360 .IR mh\-format (5)
 361 and all of the message components are available for use.  Multiple
 362 .I formatarg
 363 options can be used to build up multiple arguments to the format filter.
 364 .SH FILES
 365 .fc ^ ~
 366 .nf
 367 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 368 ^%nmhetcdir%/mhl.format~^The message template
 369 ^or <mh\-dir>/mhl.format~^Rather than the standard template
 370 ^$HOME/\&.mh\(ruprofile~^The user profile
 371 .fi
 372 .SH "PROFILE COMPONENTS"
 373 .fc ^ ~
 374 .nf
 375 .ta 2.4i
 376 .ta \w'ExtraBigProfileName  'u
 377 ^moreproc:~^Program to use as interactive front\-end
 378 ^formatproc:~^Program to use as a filter for components that
 379 ^^have the \*(lqformat\*(rq flag set.
 380 .fi
 381 .SH "SEE ALSO"
 382 .IR show (1),
 383 .IR ap (8),
 384 .IR dp (8)
 385 .SH DEFAULTS
 386 .nf
 387 .RB ` \-bell '
 388 .RB ` \-noclear '
 389 .RB ` \-length\ 40 '
 390 .RB ` \-width\ 80 '
 391 .fi
 392 .SH CONTEXT
 393 None
 394 .SH BUGS
 395 There should be some way to pass `bell' and `clear' information to the
 396 front\-end.
 397 .PP
 398 The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq
 399 and \*(lqsplit\*(rq.
 400 .PP
 401 The \*(lqformat\*(rq option really should work on something other than the body
 402 component.