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 mh 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 mmh
  24 command for filtering and/or displaying text
  25 messages.  It is the default method of displaying text messages for
  26 .B mmh
  27 (it is the default
  28 .IR showproc ).
  29 .PP
  30 The
  31 .B \-width
  32 .I width
  33 switch sets the screen width.  This defaults to the value indicated by
  34 .BR $TERMCAP ,
  35 if appropriate, otherwise it defaults to 80.
  36 .PP
  37 The default format file used by
  38 .B mhl
  39 is called
  40 .RI ` mhl.format '.
  41 .B mhl
  42 will first search for this file in the user's
  43 .B mmh
  44 directory, and will then search in the directory
  45 .IR %etcdir% .
  46 This default
  47 can be changed by using the
  48 .B \-form
  49 .I formatfile
  50 switch.
  51 Note: In contrast to any other
  52 .B mmh
  53 tool, the
  54 .B \-form
  55 switch does only take file names, but no format strings with a prepended
  56 equal sign `='.
  57 .PP
  58 .B Mhl
  59 operates in two phases: 1) read and parse the format file, and
  60 2) process each message (file).  During phase 1, an internal description
  61 of the format is produced as a structured list.  In phase 2, this list
  62 is walked for each message, outputting message information under the
  63 format constraints from the format file.
  64 .PP
  65 The format file can contain information controlling
  66 screen size, wrap\-around control, transparent text, component ordering,
  67 and component formatting.  Also, a list of components to ignore may be
  68 specified, and a couple of `special' components are defined
  69 to provide added functionality.  Message output will be in the order
  70 specified by the order in the format file.
  71 .PP
  72 Each line of a format file has one of the following forms:
  73 .PP
  74 .RS 5
  75 .nf
  76 ;comment
  77 :cleartext
  78 variable[,variable...]
  79 component:[variable,...]
  80 .fi
  81 .RE
  82 .PP
  83 .IP \(bu 4
  84 A line beginning with a `;' is a comment, and is ignored.
  85 .IP \(bu 4
  86 A line beginning with a `:' is clear text, and is output exactly as is.
  87 .IP \(bu 4
  88 A line containing only a `:' produces a blank line in the output.
  89 .IP \(bu 4
  90 A line beginning with `component:' defines the format for the specified
  91 component,
  92 .IP \(bu 4
  93 Remaining lines define the global environment.
  94 .PP
  95 For example, the line:
  96 .PP
  97 .RS 5
  98 width=80,overflowtext="***",overflowoffset=5
  99 .RE
 100 .PP
 101 defines the screen size to be 80 columns by 40 rows, specifies that the
 102 overflow indentation
 103 is 5, and that overflow text should be flagged with `***'.
 104 .PP
 105 Following are all of the current variables and their arguments.  If they
 106 follow a component, they apply only to that component, otherwise, their
 107 affect is global.  Since the whole format is parsed before any output
 108 processing, the last global switch setting for a variable applies to
 109 the whole message if that variable is used in a global context (i.e.,
 110 width).
 111 .PP
 112 .RS 5
 113 .nf
 114 .ta \w'xxxxxxxxxxxxx  'u +\w'integer/G  'u
 115 .I "variable    type    semantics
 116 width   integer screen width or component width
 117 length  integer component length
 118 offset  integer positions to indent `component: '
 119 overflowtext    string  text to use at the beginning of an
 120                 overflow line
 121 overflowoffset  integer positions to indent overflow lines
 122 compwidth       integer positions to indent component text
 123                 after the first line is output
 124 uppercase       flag    output text of this component in all
 125                 upper case
 126 nouppercase     flag    don't uppercase
 127 component       string/L        name to use instead of `component' for
 128                 this component
 129 nocomponent     flag    don't output `component: ' for this
 130                 component
 131 center  flag    center component on line (works for
 132                 one\-line components only)
 133 nocenter        flag    don't center
 134 leftadjust      flag    strip off leading whitespace on each
 135                 line of text
 136 noleftadjust    flag    don't leftadjust
 137 compress        flag    change newlines in text to spaces
 138 nocompress      flag    don't compress
 139 rtrim   flag    trim whitespace at end of text lines
 140 nortrim flag    retain whitespace at end of text lines (default)
 141 split   flag    don't combine multiple fields into
 142                 a single field
 143 nosplit flag    combine multiple fields into
 144                 a single field
 145 newline flag    print newline at end of components
 146                 (this is the default)
 147 nonewline       flag    don't print newline at end of components
 148 formatfield     string  format string for this component
 149                 (see below)
 150 decode  flag    decode text as RFC-2047 encoded
 151                 header field
 152 addrfield       flag    field contains addresses
 153 datefield       flag    field contains dates
 154 .fi
 155 .RE
 156 .PP
 157 To specify the value of integer\-valued and string\-valued variables,
 158 follow their name with an equals\-sign and the value.  Integer\-valued
 159 variables are given decimal values, while string\-valued variables
 160 are given arbitrary text bracketed by double\-quotes.  If a value is
 161 suffixed by `/G' or `/L', then its value is useful in
 162 a global\-only or local\-only context (respectively).
 163 .PP
 164 A line of the form:
 165 .PP
 166 .RS 5
 167 ignores=component,...
 168 .RE
 169 .PP
 170 specifies a list of components which are never output.
 171 This option supports some simple globbing,
 172 so a '*' at the end of a component will match
 173 for all components which start which the string.
 174 When you want to match a component which ends with
 175 a '*', you can escape the '*' with a '\\'.
 176 .PP
 177 The component `MessageName' (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 `Extras' 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 `nocomponent' 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 `formatfield' specifies a format string (see
 199 .BR mh\-format (5)).
 200 The flag variables `addrfield' and
 201 `datefield' (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/.mmh/profile~^The user profile
 229 .fi
 230
 231 .SH "PROFILE COMPONENTS"
 232 none
 233
 234 .SH "SEE ALSO"
 235 show(1), ap(8), dp(8)
 236
 237 .SH DEFAULTS
 238 .nf
 239 .RB ` \-width \ 80'
 240 .fi
 241
 242 .SH CONTEXT
 243 None
 244
 245 .SH BUGS
 246 In contrast to any other
 247 .B mmh
 248 tool, the
 249 .B \-form
 250 switch does only take file names, but no format strings with a prepended
 251 equal sign `='.
 252 .PP
 253 The `nonewline' option interacts badly with `compress'
 254 and `split'.