summaryrefslogtreecommitdiff
path: root/doc/texinfo/mu-mh.texi
blob: bbde23774c5306043bed2821eead0564c7805acc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 2006-2008, 2010-2012, 2014-2018 Free Software
@c Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

The primary aim of this implementation is to provide an interface
between Mailutils and Emacs using mh-e module.

To use Mailutils MH with Emacs, add the following line to your
site-start.el or .emacs file:

(load "mailutils-mh")

For the information about the current state of Mailutils MH
implementation please refer to file @file{mh/TODO} in the Mailutils
distribution directory.

@FIXME{This is perhaps not so important now.}

@menu
* Diffs::      Major differences between Mailutils MH and other MH
               implementations.
@end menu

@node Diffs
@subsection Major differences between Mailutils MH and other MH implementations

@enumerate 1
@item UUCP addresses are not supported;

@item Mailutils supports a set of new format specifications
(@pxref{Format String Diffs});

@item Mailutils provides a set of new profile variables
(@pxref{Profile Variable Diffs});

@item All programs recognize @option{--help} and @option{--version} options

These options are recognized only if no other arguments are present in
the command line.  Abbreviations are not recognized.  This makes Mailutils
MH implementation compatible with the standard usage for GNU tools.

@item Several programs behave differently (@pxref{Program
Diffs});

@end enumerate

@menu
* Format String Diffs::
* Profile Variable Diffs::
* Program Diffs::
@end menu

@node Format String Diffs
@subsubsection New and Differing MH Format Specifications

@anchor{decode function}
@deftypefn {MH Format} string decode (string @var{str})

Decodes the input string @var{str} as per RFC 2047.  Useful in printing
@samp{From:}, @samp{To:} and @samp{Subject:} headers.

Notice that, unlike the similar NMH function, @code{decode} checks the value
of the global profile variable @code{Charset} (@pxref{Charset variable})
to determine the charset to output the result in.  If this variable is
not set, @code{decode} returns its argument without any change.  If
this variable is set to @code{auto}, @code{decode} tries to determine
the charset name from the setting of @env{LC_ALL} environment
variable.  Otherwise, the value of @code{Charset} is taken to be the
name of the character set.
@end deftypefn

@deftypefn {MH Format} string package ()

Returns package name (string @samp{mailutils}).
@end deftypefn

@deftypefn {MH Format} string package_string ()

Returns full package string (e.g.  @samp{GNU Mailutils 2.1})
@end deftypefn

@deftypefn {MH Format} string version ()

Returns mailutils version.
@end deftypefn

@deftypefn {MH Format} string unre (string @var{str})

The function removes any leading whitespace and eventual @samp{Re:} prefix
from its argument.  Useful for creating subjects in reply messages:

@smallexample
  %<@{subject@}Subject: Re: %(unre@{subject@})\\n%>
@end smallexample
@end deftypefn

@anchor{reply_regex function}
@deftypefn {MH Format} void reply_regex (string @var{r})

Sets the regular expression used to recognize reply messages.  The
argument @var{r} should be a POSIX extended regular expression. 
Matching is case insensitive. 

For example, the following invocation

@smallexample
  %(reply_regex ^\(re|aw|ang|odp\)\(\\[[0-9]+\\]\)?:[[:blank:]])
@end smallexample

@noindent
corresponds to English @samp{Re}, Polish @samp{Odp}, Norwegian @samp{Aw} or
German @samp{Ang}, optionally followed by a number in brackets, followed
by colon and any amount of whitespace.  Notice proper quoting of the
regex metacharacters.

See also @code{Reply-Regex} (@pxref{Reply-Regex variable}) and
@code{isreply} (@pxref{isreply MH function}) below.

@end deftypefn

@anchor{isreply MH function}
@deftypefn {MH Format} boolean isreply ([string @var{str}])

If @var{str} is not given, the value of @samp{Subject:} header is taken.

The function returns true if its argument matches the ``reply subject''
regular expression.  This expression is set via the global profile variable
@code{Reply-Regex} (@pxref{Reply-Regex variable}) or via the format
function @code{reply_regex}. 

This function is useful for creating @samp{Subject:} headers in reply
messages.  For example, consider the following construction:

@smallexample
@group
%<@{subject@}%(lit)%<(isreply)%?\
(profile reply-prefix)%(concat)%|%(concat Re:)%>\
%(concat@{subject@})%(printhdr Subject: )\n%>
@end group
@end smallexample

If the @samp{Subject:} header already contained reply prefix, this construct
leaves it unchanged.  Otherwise it prepends to it the value of
@code{Reply-Prefix} profile variable, or, if it is unset, the string
@samp{Re:}. 

This expression is used in default @file{replcomps} and
@file{replgroupcomps} files.
@end deftypefn

@deftypefn {MH Format} boolean rcpt (@samp{to} | @samp{cc} | @samp{me} | @samp{all})

This function returns true if the given element is present in the
recipient mask (as modified by @option{-cc} or @option{-nocc} options) and
false otherwise.  It is used in default formats for @command{repl} and
@command{comp}, e.g.: 

@smallexample
%(lit)%<(rcpt to)%(formataddr@{to@})%>
@end smallexample

Notice that this means that usual @file{replcomps} file will be ignoring
@option{-cc} and @option{-nocc} options, unless it has been modified
as shown above. 
@end deftypefn

@deftypefn {MH Format} string concat ()

Appends whitespace + arg to string register.
@end deftypefn

@deftypefn {MH Format} string printhdr (string @var{str})

Prints the value of string register, prefixed by @var{str}.
The output is formatted as a RFC 822 header, i.e.
it is split at whitespace characters nearest to the width boundary
and each subsequent segment is prefixed with horizontal tabulation.
@end deftypefn

@deftypefn {MH Format} string in_reply_to ()

Generates the value for @samp{In-reply-to:} header according to RFC
2822. 
@end deftypefn

@deftypefn {MH Format} string references ()

Generates the value for @samp{References:} header according to RFC 2822.
@end deftypefn

@node Profile Variable Diffs
@subsubsection New MH Profile Variables

@anchor{Charset variable}
@deftypevar {MH Variable} string Charset

Controls the character set in which the components decoded via
the @code{decode} (@pxref{decode function}) format function should be
output.
@end deftypevar

@anchor{Reply-Regex variable}
@deftypevar {MH Variable} string Reply-Regex

Keeps the regular expression used to recognize reply messages.  The
argument should be a POSIX extended regular expression.  Matching
is case insensitive. 

For more information, please see @xref{reply_regex function}.
@end deftypevar

@node Program Diffs
@subsubsection Differences in MH Program Behavior

@table @command
@item anno

The prompt in interactive mode is @samp{Component name:}, instead
of @samp{Enter component name:} displayed by the RAND @command{anno}.

If a @option{-component field} is not specified and standard input
is not connected to a terminal, @command{anno} does not display
the prompt before reading the component from the standard input.
RAND @command{anno} displays the prompt anyway.

@item burst

The utility is able to burst both RFC 934 digest messages and MIME
multipart messages.  It provides two additional command line options:
@option{-recurse} and @option{-length}.

The @option{-recurse} option instructs the utility to recursively
expand the digest.

The @option{-length} option can be used to set the minimal encapsulation
boundary length for RFC 934 digests.  Default length is 1,
i.e. encountering one dash immediately following a newline triggers
digest decoding.  It is OK for messages that follow RFC 934
specification.  However, many user agents do not precisely follow it,
in particular, they often do not escape lines starting with a dash by
@samp{- } sequence.  @command{Mailman} is one of such agents.  To cope
with such digests you can set encapsulation boundary length to a higher
value.  For example, @command{bounce -length 8} has been found to be
sufficient for most Mailman-generated digests.

@item comp

Understands @option{-build} option.

@item fmtdump

This command is not provided.  Use @option{fmtcheck} instead.

@item inc
@itemize @bullet
@item The @option{-moveto} option.
The @option{-moveto} option instructs @command{inc} to move
messages into another folder after incorporating them.  This option
has effect only if the @option{-truncate} option has also been
specified and the underlying mailbox supports the @samp{move}
operation.  Currently only @samp{imap} and @samp{imaps} mailboxes
support it.  For example, the following command moves incorporated
messages into the @samp{archive} folder:

@example
inc -file imaps://imap.gmail.com -moveto=archive
@end example

The @samp{moveto} URL parameter can be used instead of this option,
e.g.:

@example
inc -file 'imaps://imap.gmail.com;moveto=archive'
@end example

@item Multiple sources
Mailutils @command{inc} is able to incorporate messages from several
source mailboxes. These are specified via multiple @option{-file}
options, e.g.:

@example
inc  -truncate \
     -file 'imaps://imap.gmail.com;moveto=archived' \
     -file pops://mail.gnu.org \
     -file /var/mail/root
@end example

@item URL parameters
The following additional parameters can be used in the mailbox
URLs supplied with the @option{-file} option:

@table @option
@item moveto=@var{folder}
Moves incorporated messages into another folder.  This was discussed
above.

@item nomoveto
Disables the previous @option{-moveto} option.

@item truncate[=@var{bool}]
Controls source mailbox truncation.  If @var{bool} is not given or it is
@samp{yes}, the mailbox will be truncated after successful processing.
If @var{bool} is @samp{no}, the source mailbox will not be truncated.
@end table
@end itemize

@item mhl

The @samp{ignores} keyword can be used in variable list.  In that
case, if its value contains  more than one component name
it must be enclosed in double-quotes, e.g.:

@smallexample
leftadjust,compwidth=9,"ignores=msgid,message-id,received"
@end smallexample

@noindent
The above is equivalent to the following traditional notation:

@smallexample
leftadjust,compwidth=9
ignores=msgid,message-id,received
@end smallexample

The @samp{MessageName} component is not yet implemented.

Interactive prompting is not yet implemented.

The following format variables are silently ignored: @samp{center},
@samp{split}, @samp{datefield}.

@item mhn

@itemize @bullet

@item New option
New option @option{-compose} forces @command{mhn} editing mode.  This
is also the default mode.  This differs from the standard
@command{mhn}, which switches to the editing mode only if no other
options were given and the input file name coincides with the value of
@env{mhdraft} environment variable.  

@item Show mode (@option{-show})
If an appropriate mhn-show-type[/subtype] was not found, GNU @command{mhn}
prints the decoded message content using @code{moreproc}
variable.  Standard @command{mhn} in this case used to print @samp{don't
know how to display content} diagnostic. 

The default behaviour is to pipe the content to the standard input
of the mhn-show-type[/subtype] command.  This is altered to using a
temporary file if the command contains @code{%f} or @code{%F} escapes.

@item Store mode (@option{-store})
If the @code{Content-Disposition} header contains @samp{filename=},
and @command{mhn} is invoked with @option{-auto} switch, it
transforms the file name into the absolute notation and uses it only
if it lies below the current mhn-storage directory.  Standard
@command{mhn} only requires that the file name do not begin with @samp{/}.

Before saving a message part, GNU @command{mhn} checks if the file already
exists.  If so, it asks whether the user wishes to rewrite it.  This
behaviour is disabled when @option{-quiet} option was given.
@end itemize

@item mhparam

The @option{-all} mode does not display commented out entries.

@item pick

New command line option @option{-cflags} allows to control the type of 
regular expressions used.  The option must occur right before
@option{--@var{component} @var{pattern}} or equivalent construct (like
@option{-cc}, @option{-from}, etc.) 

The argument to this option is a string of type specifications:

@multitable @columnfractions 0.20 0.80
@item B @tab Use basic regular expressions
@item E @tab Use extended regular expressions
@item I @tab Ignore case
@item C @tab Case sensitive
@end multitable

Default is @samp{EI}.

The flags remain in effect until the next occurrence of @option{-cflags}
option.

Sample usage:

@smallexample
pick -cflag BC -subject '*a string' 
@end smallexample

The date comparison options (@option{-before} and @option{-after}
accept date specifications in a wide variety of formats, e.g.:

@smallexample
pick -after 20030301
pick -after 2003-03-01
pick -after 01-mar-2003
pick -after 2003-mar-01
pick -before '1 year ago'
etc...
@end smallexample

@item prompter
@enumerate
@item
Prompter attempts to use GNU Readline library, if it is installed.
Consequently, arguments to @option{-erase} and @option{-kill} option
must follow GNU style key sequence notation (@pxref{Readline Init File
Syntax, keyseq,,readline,GNU Readline Library}).

If @command{prompter} is built without @command{readline}, it accepts
the following character notations:

@table @asis
@item \@var{nnnn}
Here, @var{n} stands for a single octal digit.

@item ^@var{chr}
This notation is translated to the ASCII code @samp{@var{chr} + 0100}.
@end table

@item
Component continuation lines are not required to begin with a
whitespace.  If leading whitespace is not present, @command{prompter}
will add it automatically.
@end enumerate

@item refile

@enumerate
@item
Linking messages between folders goes against the logic of Mailutils,
so @command{refile} never makes links even if called with
@option{-link} option.  The latter is actually a synonym for @option{-copy},
which preserves the original message.

@item
The @option{-preserve} option is not implemented.  It is retained for backward
compatibility only.

@item
Message specs and folder names may be interspersed.
@end enumerate

@item repl

Understands @option{-use} option.  Disposition shell provides
@code{use} command. 

@item rmm

@enumerate 1
@item
Different behaviour if one of the messages in the list does not exist:

Mailutils @command{rmm} does not delete any messages.  Standard
@command{rmm} in this case deletes all messages preceding the
non-existent one. 

@item
The @command{rmm} utility will unlink messages, if the @code{rmmproc}
profile component has empty value, e.g.:

@example
rmmproc:
@end example
@end enumerate

@item sortm

New option @option{-numfield} specifies numeric comparison for the
given field. 

Any number of @option{-datefield}, @option{-textfield} and
@option{-numfield} options may be given, thus allowing to build sort
criteria of arbitrary complexity. 

The order of @option{-.*field} options sets the ordering priority.  This
differs from the behaviour of the standard @command{sortm}, which
always orders datefield-major, textfield-minor.

Apart from sorting the mailfolder the following actions may be
specified:

@table @option
@item -list
List the ordered messages using a format string given by
@option{-form} or @option{-format} option.

@item -dry-run
Do not actually sort messages, rather print what would have been
done.  This is useful for debugging purposes.
@end table

@end table


Return to:

Send suggestions and report system problems to the System administrator.