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

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