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