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

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