git.marmaro.de Git - mmh/blob - man/mhl.man

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