1S-NAIL(1)                 BSD General Commands Manual                S-NAIL(1)
2

NAME

4     S-nail [v14.9.23] — send and receive Internet mail
5

SYNOPSIS

7     s-nail [-DdEFinv~#] [-: spec] [-A account] [:-a attachment:]
8            [:-b bcc-addr:] [:-C "field: body":] [:-c cc-addr:]
9            [-M type | -m file | -q file | -t] [-r from-addr]
10            [:-S var[=value]:] [-s subject] [:-T "field: addr":] [:-X cmd:]
11            [:-Y cmd:] [-.] :to-addr: [-- :mta-option:]
12
13     s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":]
14            [-L spec] [-r from-addr] [:-S var[=value]:] [-u user] [:-X cmd:]
15            [:-Y cmd:] [-- :mta-option:]
16     s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":] -f
17            [-L spec] [-r from-addr] [:-S var[=value]:] [:-X cmd:] [:-Y cmd:]
18            [file] [-- :mta-option:]
19
20     s-nail -h | --help
21     s-nail -V | --version
22

DESCRIPTION

24           Note: S-nail (S-nail) will see major changes in v15.0 (circa 2022).
25           Some backward incompatibilities cannot be avoided.  COMMANDS change
26           to  Shell-style argument quoting, and shell metacharacters will be‐
27           come (more) meaningful.  Some commands accept new syntax today  via
28           wysh  (Command  modifiers).   Behaviour is flagged [v15-compat] and
29           [no  v15-compat],  setting  v15-compat  (INTERNAL  VARIABLES)  will
30           choose  new behaviour when applicable; giving it a value makes wysh
31           an implied default.  [Obsolete] flags what will vanish.
32
33           Warning! v15-compat (with value) will be a default in v14.10.0!
34
35     S-nail provides a simple and friendly environment for sending and receiv‐
36     ing mail.  It is intended to provide the functionality of the POSIX
37     mailx(1) command, but is MIME capable and optionally offers extensions
38     for line editing, S/MIME, SMTP and POP3, among others.  S-nail divides
39     incoming mail into its constituent messages and allows the user to deal
40     with them in any order.  It offers many COMMANDS and INTERNAL VARIABLES
41     for manipulating messages and sending mail.  It provides the user simple
42     editing capabilities to ease the composition of outgoing messages, and
43     increasingly powerful and reliable non-interactive scripting capabili‐
44     ties.
45
46   Options
47     -: spec, --resource-files=..
48               Controls loading of (as via source) Resource files: spec is
49               parsed case-insensitively, the letter ‘s’ corresponds to the
50               system wide s-nail.rc, ‘u’ the user's personal file ~/.mailrc.
51               The (original) system wide resource is also compiled-in, acces‐
52               sible via ‘x’.  The letters ‘-’ and ‘/’ disable usage of re‐
53               source files.  Order matters, default is ‘su’.  This option
54               overrides -n.
55
56     -A name, --account=..
57               Activate user account name after program startup is complete
58               (resource files loaded, only -X commands are to be executed),
59               and switch to its primary system mailbox (most likely the
60               inbox).  If activation fails the program exits if used non-in‐
61               teractively, or if any of errexit or posix are set.
62
63     -a file[=input-charset[#output-charset]], --attach=..
64               (Send mode) Attach file.  For (Compose mode) opportunities re‐
65               fer to ~@ and ~^.  file is subject to tilde expansion (see
66               Filename transformations and folder); if it is not accessible
67               but contains a ‘=’ character, anything before the last ‘=’ will
68               be used as the filename, anything thereafter as a character set
69               specification, as shown.
70
71               If only an input character set is specified, the input side is
72               fixed, and no character set conversion will be applied; an
73               empty or the special string hyphen-minus ‘-’ is taken for
74               ttycharset (the default).  If an output character set has also
75               been specified the desired conversion is performed immediately,
76               not considering file type and content, except for an empty
77               string or hyphen-minus ‘-’, which select the default conversion
78               algorithm (see Character sets): no immediate conversion is per‐
79               formed, file and its contents will be MIME-classified (HTML
80               mail and MIME attachments, The mime.types files) first — only
81               the latter mode is available unless features includes
82               ‘,+iconv,’.
83
84     -B        ([Obsolete]: S-nail will always use line-buffered output, to
85               gain line-buffered input even in batch mode enable batch mode
86               via -#.)
87
88     -b addr, --bcc=..
89               (Send mode) Send a blind carbon copy to recipient addr.  The
90               option may be used multiple times.  Also see the section On
91               sending mail, and non-interactive mode.
92
93     -C "field: body", --custom-header=..
94               Create a custom header which persists for an entire session.  A
95               custom header consists of the field name followed by a colon
96               ‘:’ and the field content body, for example ‘-C "Blah: Neminem
97               laede; imo omnes, quantum potes, juva"’.  Standard header field
98               names cannot be overwritten by custom headers.  Runtime ad‐
99               justable custom headers are available via the variable
100               customhdr, and in (Compose mode) ~^, one of the COMMAND
101               ESCAPES, as well as digmsg are the most flexible and powerful
102               options to manage message headers.  This option may be used
103               multiple times.
104
105     -c addr, --cc=..
106               (Send mode) Just like -b, except it places the argument in the
107               list of carbon copies.
108
109     -D, --disconnected
110               [Option] Startup with disconnected set.
111
112     -d, --debug
113               Enter a debug-only sandbox mode by setting the internal vari‐
114               able debug; the same can be achieved via ‘-S debug’ or ‘set
115               debug’.  Also see -v.
116
117     -E, --discard-empty-messages
118               (Send mode) set skipemptybody and thus discard messages with an
119               empty message part body, successfully.
120
121     -e, --check-and-exit
122               Just check if mail is present (in the system inbox or the one
123               specified via -f): if yes, return an exit status of zero, a
124               non-zero value otherwise.  To restrict the set of mails to con‐
125               sider in this evaluation a message specification can be added
126               with the option -L.  Quickrun: does not open an interactive
127               session.
128
129     -F        (Send mode) Save the message to send in a file named after the
130               local part of the first recipient's address (instead of in
131               record).
132
133     -f, --file
134               Read in the contents of the user's secondary mailbox MBOX (or
135               the specified file) for processing; when S-nail is quit, it
136               writes undeleted messages back to this file (but be aware of
137               the hold option).  The optional file argument will undergo some
138               special Filename transformations (as via folder).  Note that
139               file is not an argument to the flag -f, but is instead taken
140               from the command line after option processing has been com‐
141               pleted.  In order to use a file that starts with a hyphen-mi‐
142               nus, prefix with a relative path, as in ‘./-hyphenbox.mbox’.
143
144     -H, --header-summary
145               Display a summary of headers for the given folder (depending on
146               -u, inbox or MAIL, or as specified via -f), then exit.  A con‐
147               figurable summary view is available via the option -L.  This
148               mode does not honour showlast.  Quickrun: does not open an in‐
149               teractive session.
150
151     -h, --help
152               Show a brief usage summary; use --long-help for a list long op‐
153               tions.
154
155     -i        set ignore to ignore tty interrupt signals.
156
157     -L spec, --search=..
158               Display a summary of headers of all messages that match the
159               given spec in the folder found by the same algorithm used by
160               -H, then exit.  See the section Specifying messages for the
161               format of spec.  This mode does not honour showlast.
162
163               If the -e option has been given in addition no header summary
164               is produced, but S-nail will instead indicate via its exit sta‐
165               tus whether spec matched any messages (‘0’) or not (‘1’); note
166               that any verbose output is suppressed in this mode and must in‐
167               stead be enabled explicitly (see -v).  Quickrun: does not open
168               an interactive session.
169
170     -M type   (Send mode) Will flag standard input with the MIME
171               ‘Content-Type:’ set to the given known type (HTML mail and MIME
172               attachments, The mime.types files) and use it as the main mes‐
173               sage body.  [v15 behaviour may differ] Using this option will
174               bypass processing of message-inject-head and
175               message-inject-tail.  Also see -q, -m, -t.
176
177     -m file   (Send mode) MIME classify the specified file and use it as the
178               main message body.  [v15 behaviour may differ] Using this op‐
179               tion will bypass processing of message-inject-head and
180               message-inject-tail.  Also see -q, -M, -t.
181
182     -N, --no-header-summary
183               inhibit the initial display of message headers when reading
184               mail or editing a mailbox folder by calling unset for the in‐
185               ternal variable header.
186
187     -n        Standard flag that inhibits reading the system wide s-nail.rc
188               upon startup.  The option -: allows more control over the
189               startup sequence; also see Resource files.
190
191     -q file, --quote-file=..
192               (Send mode) Initialize the message body with the contents of
193               file, which may be standard input ‘-’ only in non-interactive
194               context.  Also see -M, -m, -t.
195
196     -R, --read-only
197               Any mailbox folder aka folder opened will be in read-only mode.
198
199     -r from-addr, --from-address=..
200               The RFC 5321 reverse-path used for relaying and delegating mes‐
201               sages to its destination(s), for example to report delivery er‐
202               rors, is normally derived from the address which appears in the
203               from header (or, if that contains multiple addresses, in
204               sender).  A file-based aka local executable mta (Mail-Transfer-
205               Agent), however, instead uses the local identity of the initi‐
206               ating user.
207
208               When this command line option is used the given single ad‐
209               dressee from-addr will be assigned to the internal variable
210               from, but in addition the command line option -f from-addr will
211               be passed to a file-based mta whenever a message is sent.
212               Shall from-addr include a user name the address components will
213               be separated and the name part will be passed to a file-based
214               mta individually via -F name.  Even though not a recipient the
215               ‘shquote’ expandaddr flag is supported.
216
217               If an empty string is passed as from-addr then the content of
218               the variable from (or, if that contains multiple addresses,
219               sender) will be evaluated and used for this purpose whenever
220               the file-based mta is contacted.  By default, without -r that
221               is, neither -f nor -F command line options are used when con‐
222               tacting a file-based MTA, unless this automatic deduction is
223               enforced by setting the internal variable r-option-implicit.
224
225               Remarks: many default installations and sites disallow overrid‐
226               ing the local user identity like this unless either the MTA has
227               been configured accordingly or the user is member of a group
228               with special privileges.  Passing an invalid address will cause
229               an error.
230
231     -S var[=value], --set=..
232               set (or, with a prefix string ‘no’, as documented in INTERNAL
233               VARIABLES, unset) variable and optionally assign value, if sup‐
234               ported; [v15 behaviour may differ] the entire expression is
235               evaluated as if specified within dollar-single-quotes (see
236               Shell-style argument quoting) if the internal variable
237               v15-compat is set.  If the operation fails the program will
238               exit if any of errexit or posix are set.  Settings established
239               via -S cannot be changed from within Resource files or an ac‐
240               count switch initiated by -A.  They will become mutable again
241               before commands registered via -X are executed.
242
243     -s subject, --subject=..
244               (Send mode) Specify the subject of the message to be sent.
245               Newline (NL) and carriage-return (CR) bytes are invalid and
246               will be normalized to space (SP) characters.
247
248     -T "field: addr", --target=..
249               (Send mode) Add addr to the list of receivers targeted by
250               field, for now supported are only ‘bcc’, ‘cc’, ‘fcc’, and ‘to’.
251               Field and body (address) are separated by a colon ‘:’ and op‐
252               tionally blank (space, tabulator) characters.  The ‘shquote’
253               expandaddr flag is supported.  addr is parsed like a message
254               header address line, as if it would be part of a template mes‐
255               sage fed in via -t, and the same modifier suffix is supported.
256               This option may be used multiple times.
257
258     -t, --template
259               (Send mode) The text message given (on standard input) is ex‐
260               pected to contain, separated from the message body by an empty
261               line, one or multiple plain text message headers.  [v15 behav‐
262               iour may differ] Readily prepared MIME mail messages cannot be
263               passed.  Headers can span multiple consecutive lines if follow
264               lines start with any amount of whitespace.  A line starting
265               with the number sign ‘#’ in the first column is ignored.  Mes‐
266               sage recipients can be given via the message headers ‘To:’,
267               ‘Cc:’, ‘Bcc:’ (the ‘?single’ modifier enforces treatment as a
268               single addressee, for example ‘To?single: exa, <m@ple>’) or
269               ‘Fcc:’, they will be added to any recipients specified on the
270               command line, and are likewise subject to expandaddr validity
271               checks.  If a message subject is specified via ‘Subject:’ then
272               it will be used in favour of one given on the command line.
273
274               More optional headers are ‘Reply-To:’ (possibly overriding
275               reply-to), ‘Sender:’ (sender), ‘From:’ (from and / or option
276               -r).  ‘Message-ID:’, ‘In-Reply-To:’, ‘References:’ and
277               ‘Mail-Followup-To:’, by default created automatically dependent
278               on message context, will be used if specified (a special ad‐
279               dress massage will however still occur for the latter).  Any
280               other custom header field (also see -C, customhdr and ~^) is
281               passed through entirely unchanged, and in conjunction with the
282               options -~ or -# it is possible to embed COMMAND ESCAPES.  Also
283               see -M, -m, -q.
284
285     -u user, --inbox-of=..
286               Initially read the primary system mailbox of user, appropriate
287               privileges presumed; effectively identical to ‘-f %user’.
288
289     -V, --version
290               Show S-nails version and exit.  The command version will also
291               show the list of features: ‘$ s-nail -:/ -Xversion -Xx’.
292
293     -v, --verbose
294               sets the internal variable verbose to enable logging of infor‐
295               mational context messages.  (Increases level of verbosity when
296               used multiple times.)  Also see -d.
297
298     -X cmd, --startup-cmd=..
299               Add the given (or multiple for a multiline argument) cmd to a
300               list of commands to be executed before normal operation starts.
301               The commands will be evaluated as a unit, just as via source.
302               Correlates with -# and errexit.
303
304     -Y cmd, --cmd=..
305               Add the given (or multiple for a multiline argument) cmd to a
306               list of commands to be executed after normal operation has
307               started.  The commands will be evaluated successively in the
308               given order, and as if given on the program's standard input —
309               before interactive prompting begins in interactive mode, after
310               standard input has been consumed otherwise.
311
312     -~, --enable-cmd-escapes
313               Enable COMMAND ESCAPES in (Compose mode) even in non-interac‐
314               tive use cases.  This can for example be used to automatically
315               format the composed message text before sending the message:
316
317                     $ ( echo 'line    one. Word.     Word2.';\
318                         echo '~| /usr/bin/fmt -tuw66' ) |\
319                       LC_ALL=C s-nail -d~:/ -Sttycharset=utf-8 bob@exam.ple
320
321     -#, --batch-mode
322               Enables batch mode: standard input is made line buffered, the
323               complete set of (interactive) commands is available, processing
324               of COMMAND ESCAPES is enabled in Compose mode, and diverse
325               INTERNAL VARIABLES are adjusted for batch necessities, exactly
326               as if done via -S: emptystart, noerrexit, noheader, noposix,
327               quiet, sendwait, typescript-mode as well as MAIL, MBOX and
328               inbox (the latter three to /dev/null).  Also, the values of
329               COLUMNS and LINES are looked up, and acted upon.  The following
330               prepares an email message in a batched dry run:
331
332                     $ for name in bob alice@exam.ple lisa@exam.ple; do
333                         printf 'mail %s\n~s ubject\nText\n~.\n' "${name}"
334                       done |
335                       LC_ALL=C s-nail -#:x -Smta=test \
336                         -X'alias bob bob@exam.ple'
337
338     -., --end-options
339               This flag forces termination of option processing in order to
340               prevent “option injection” (attacks).  It also forcefully puts
341               S-nail into send mode, see On sending mail, and non-interactive
342               mode.
343
344     If the setting of expandargv allows their recognition all mta-option ar‐
345     guments given at the end of the command line after a ‘--’ separator will
346     be passed through to a file-based mta (Mail-Transfer-Agent) and persist
347     for the entire session.  expandargv constraints do not apply to the con‐
348     tent of mta-arguments.  Command line receiver address handling supports
349     the ‘shquote’ constraint of expandaddr, for more please see On sending
350     mail, and non-interactive mode.
351
352           $ s-nail -#:/ -X 'addrcodec enc Hey, ho <silver@go>' -Xx
353
354   A starter
355     S-nail is a direct descendant of BSD Mail, itself a successor to the Re‐
356     search UNIX mail which “was there from the start” according to HISTORY.
357     It thus represents the user side of the UNIX mail system, whereas the
358     system side (Mail-Transfer-Agent, MTA) was traditionally taken by
359     sendmail(8) (and most MTAs provide a binary of this name for compatibil‐
360     ity reasons).  If the [Option]al SMTP mta is included in the features of
361     S-nail then the system side is not a mandatory precondition for mail de‐
362     livery.
363
364     S-nail strives for compliance with the POSIX mailx(1) standard, but
365     posix, one of the INTERNAL VARIABLES, or its ENVIRONMENTal equivalent
366     POSIXLY_CORRECT, needs to be set to adjust behaviour to be almost on par.
367     Almost, because there is one important difference: POSIX Shell-style
368     argument quoting is ([v15 behaviour may differ] increasingly) used in‐
369     stead of the Old-style argument quoting that the standard documents,
370     which is believed to be a feature.  The builtin as well as the (default)
371     global s-nail.rc Resource files already bend the standard imposed set‐
372     tings a bit.
373
374     For example, hold and keepsave are set in order to suppress the automatic
375     moving of messages to the secondary mailbox MBOX that would otherwise oc‐
376     cur (see Message states), and keep to not remove empty system MBOX mail‐
377     box files (or all empty such files in posix mode) to avoid mangling of
378     file permissions when files eventually get recreated.
379
380     To enter interactive mode even if the initial mailbox is empty emptystart
381     is set, editheaders to allow editing of headers as well as fullnames to
382     not strip down addresses in Compose mode, and quote to include the mes‐
383     sage that is being responded to when replying, which is indented by an
384     indentprefix that also deviates from standard imposed settings.
385     mime-counter-evidence is fully enabled, too.  It sets followup-to-honour
386     and reply-to-honour to comply with reply address desires.
387
388     Credentials and other settings are easily addressable by grouping them
389     via account.  The file mode creation mask can be managed with umask.
390     Files and shell pipe output can be sourced for evaluation, also during
391     startup from within the Resource files.  Informational context can be
392     available by setting verbose or debug (as via -v, -d).
393
394   On sending mail, and non-interactive mode
395     To send a message to one or more people, using a local or built-in mta
396     (Mail-Transfer-Agent) transport to actually deliver the generated mail
397     message, S-nail can be invoked with arguments which are the names of peo‐
398     ple to whom the mail will be sent, and the command line options -b and -c
399     can be used to add (blind) carbon copy receivers:
400
401           # Via test MTA
402           $ echo Hello, world | s-nail -:/ -Smta=test -s test $LOGNAME
403
404           # Via sendmail(1) MTA
405           $ </dev/null s-nail -:x -s test $LOGNAME
406
407           # Debug dry-run mode:
408           $ </dev/null LC_ALL=C s-nail -d -:/ \
409              -Sttycharset=utf8 -Sfullnames \
410              -b bcc@exam.ple -c cc@exam.ple -. \
411              '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
412
413           # With SMTP (no real sending due to -d debug dry-run)
414           $ LC_ALL=C s-nail -d -:/ -Sv15-compat -Sttycharset=utf8 \
415               -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=none \
416               -S from=scriptreply@exam.ple \
417               -a /etc/mail.rc --end-options \
418               eric@exam.ple < /tmp/letter.txt
419
420     Email addresses and plain user names are subject to alternates filtering,
421     names only are first expanded through alias and mta-aliases.  An address
422     in angle brackets consisting only of a valid local user ‘<name>’ will be
423     converted to a fully qualified address if either hostname is not set, or
424     set to a non-empty value; if set to the empty value the conversion is
425     left up to the mta.  By setting expandaddr fine-grained control of recip‐
426     ient address types other than user names and network addresses is possi‐
427     ble.  Recipients are classified as follows: any name that starts with a
428     vertical bar ‘|’ character specifies a command pipe – the command string
429     following the ‘|’ is executed and the message is sent to its standard in‐
430     put; likewise, any name that consists only of hyphen-minus ‘-’ or starts
431     with the character solidus ‘/’ or the character sequence dot solidus ‘./’
432     is treated as a file, regardless of the remaining content.  Any other
433     name which contains a commercial at ‘@’ character is a network address;
434     Any other name which starts with a plus sign ‘+’ character is a mailbox
435     name; Any other name which contains a solidus ‘/’ character but no excla‐
436     mation mark ‘!’ or percent sign ‘%’ character before is also a mailbox
437     name; What remains is treated as a network address.  This classification
438     can be avoided by using a ‘Fcc:’ header, see Compose mode.
439
440           $ echo bla | s-nail -Sexpandaddr -s test ./mbox.mbox
441           $ echo bla | s-nail -Sexpandaddr -s test '|cat >> ./mbox.mbox'
442           $ echo safe | LC_ALL=C \
443               s-nail -:/ -Smta=test -Sv15-compat -Sttycharset=utf8 \
444                 --set mime-force-sendout --set fullnames \
445                 -S expandaddr=fail,-all,+addr,failinvaddr -s test \
446                 --end-options 'Imagine John <cold@turk.ey>'
447
448     Before messages are sent they undergo editing in Compose mode.  But many
449     settings are static and can be set more generally.  The envelope sender
450     address for example is defined by from, explicitly defining an originat‐
451     ing hostname may be desirable, especially with the built-in SMTP Mail-
452     Transfer-Agent mta.  Character sets for outgoing message and MIME part
453     content are configurable via sendcharsets, whereas input data is assumed
454     to be in ttycharset.  Message data will be passed over the wire in a
455     mime-encoding, and MIME parts aka attachments need a mimetype, usually
456     taken out of The mime.types files.  Saving copies of sent messages in a
457     record mailbox may be desirable – as for most mailbox folder targets
458     Filename transformations will be performed.
459
460     For the purpose of arranging a complete environment of settings that can
461     be switched to with a single command or command line option there are
462     accounts.  Alternatively a flat configuration could be possible, making
463     use of so-called variable chains which automatically pick ‘USER@HOST’ or
464     ‘HOST’ context-dependent variants some variables support: for example ad‐
465     dressing ‘Folder pop3://yaa@exam.ple’ would find
466     pop3-no-apop-yaa@exam.ple, pop3-no-apop-exam.ple and pop3-no-apop in or‐
467     der.  For more please see On URL syntax and credential lookup and
468     INTERNAL VARIABLES.
469
470     To avoid environmental noise scripts should create a script-local envi‐
471     ronment, ideally with the command line options -: to disable configura‐
472     tion files in conjunction with repetitions of -S to specify variables:
473
474           $ env LC_ALL=C s-nail -:/ \
475               -Sv15-compat \
476               -Sttycharset=utf-8 -Smime-force-sendout \
477               -Sexpandaddr=fail,-all,failinvaddr \
478               -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=login \
479               -S from=scriptreply@exam.ple \
480               -s 'Subject to go' -a attachment_file \
481               -Sfullnames -. \
482               'Recipient 1 <rec1@exam.ple>' rec2@exam.ple \
483               < content_file
484
485     As shown, scripts producing messages can “fake” a locale environment, the
486     above specifies the all-compatible 7-bit clean LC_ALL “C”, but will none‐
487     theless take and send UTF-8 in the message text by using ttycharset.  If
488     character set conversion is compiled in (features includes the term
489     ‘,+iconv,’) invalid (according to ttycharset) character input data would
490     normally cause errors; setting mime-force-sendout will instead, as a last
491     resort, classify the input as binary data, and therefore allow message
492     creation to be successful.  (Such content can then be inspected either by
493     installing a pipe-TYPE/SUBTYPE handler for ‘application/octet-stream’, or
494     possibly automatically through mime-counter-evidence).
495
496     In interactive mode, introduced soon, messages can be sent by calling the
497     mail command with a list of recipient addresses:
498
499           $ s-nail -:/ -Squiet -Semptystart -Sfullnames -Smta=test
500           "/var/spool/mail/user": 0 messages
501           ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
502           ...
503           ? # Will do the right thing (tm)
504           ? m rec1@exam.ple rec2@exam.ple
505
506   Compose mode
507     If standard input is a terminal rather than the message to be sent, the
508     user is expected to type in the message contents.  In compose mode lines
509     beginning with the character ‘~’ (in fact the value of escape) are spe‐
510     cial – these are so-called COMMAND ESCAPES which can be used to read in
511     files, process shell commands, add and edit attachments and more.  For
512     example ~v or ~e will start the VISUAL text EDITOR, respectively, to re‐
513     vise the message in its current state, ~h allows editing of the most im‐
514     portant message headers, with the potent ~^ custom headers can be cre‐
515     ated, for example (more specifically than with -C and customhdr).  [Op‐
516     tion]ally ~? gives an overview of most other available command escapes.
517
518     To create file-carbon-copies the special recipient header ‘Fcc:’ may be
519     used as often as desired, for example via ~^.  Its entire value (or body
520     in standard terms) is interpreted as a folder target, after having been
521     subject to Filename transformations: this is the only way to create a
522     file-carbon-copy without introducing an ambiguity regarding the interpre‐
523     tation of the address, file names with leading vertical bars or commer‐
524     cial ats can be used.  Like all other recipients ‘Fcc:’ is subject to the
525     checks of expandaddr.  Any local file and pipe command addressee honours
526     the setting of mbox-fcc-and-pcc.
527
528     Once finished with editing the command escape ~. (see there) will call
529     hooks, insert automatic injections and receivers, leave compose mode and
530     send the message once it is completed.  Aborting letter composition is
531     possible with either of ~x or ~q, the latter of which will save the mes‐
532     sage in the file denoted by DEAD unless nosave is set.  And unless
533     ignoreeof is set the effect of ~. can also be achieved by typing end-of-
534     transmission (EOT) via ‘control-D’ (‘^D’) at the beginning of an empty
535     line, and ~q is always reachable by typing end-of-text (ETX) twice via
536     ‘control-C’ (‘^C’).
537
538     The compose mode hooks on-compose-enter, on-compose-splice,
539     on-compose-leave and on-compose-cleanup may be set to defined macros and
540     provide reliable and increasingly powerful mechanisms to perform auto‐
541     mated message adjustments dependent on message context, for example addi‐
542     tion of message signatures (message-inject-head, message-inject-tail) or
543     creation of additional receiver lists (also by setting autocc, autobcc).
544     To achieve that the command digmsg may be used in order to query and ad‐
545     just status of message(s).  The splice hook can also make use of COMMAND
546     ESCAPES.  ([v15 behaviour may differ] The compose mode hooks work for
547     forward, mail, reply and variants; resend and Resend only provide the
548     hooks on-resend-enter and on-resend-cleanup, which are pretty restricted
549     due to the nature of the operation.)
550
551   On reading mail, and more on interactive mode
552     When invoked without addressees S-nail enters interactive mode in which
553     mails may be read.  When used like that the user's system inbox (for more
554     on mailbox types please see the command folder) is read in and a one line
555     header of each message therein is displayed if the variable header is
556     set.  The visual style of this summary of headers can be adjusted through
557     the variable headline and the possible sorting criterion via autosort.
558     Scrolling through screenfuls of headers can be performed with the command
559     z.  If the initially opened mailbox is empty S-nail will instead exit im‐
560     mediately (after displaying a message) unless the variable emptystart is
561     set.
562
563     At the prompt the command list will give a listing of all available com‐
564     mands and help will [Option]ally give a summary of some common ones.  If
565     the [Option]al documentation strings are available (see features) one can
566     type ‘help X’ (or ‘?X’) and see the actual expansion of ‘X’ and what its
567     purpose is, i.e., commands can be abbreviated (note that POSIX defines
568     some abbreviations, so that the alphabetical order of commands does not
569     necessarily relate to the abbreviations; it is however possible to define
570     overwrites with commandalias).  These commands can also produce a more
571     verbose output.
572
573     Messages are given numbers (starting at 1) which uniquely identify mes‐
574     sages; the current message – the “dot” – will either be the first new
575     message, or the first unread message, or the first message of the mail‐
576     box; the internal variable showlast will instead cause usage of the last
577     message for this purpose.  The command headers will display a screenful
578     of header summaries containing the “dot”, whereas from will display only
579     the summaries of the given messages, defaulting to the “dot”.
580
581     Message content can be displayed with the command type (‘t’, alias
582     print).  Here the variable crt controls whether and when S-nail will use
583     the configured PAGER for display instead of directly writing to the user
584     terminal screen, the sole difference to the command more, which will al‐
585     ways use the PAGER.  The command top will instead only show the first
586     toplines of a message (maybe even compressed if topsqueeze is set).  Mes‐
587     sage display experience may improve by setting and adjusting
588     mime-counter-evidence, and also see HTML mail and MIME attachments.
589
590     By default the current message (“dot”) is displayed, but like with many
591     other commands it is possible to give a fancy message specification (see
592     Specifying messages), for example ‘t:u’ will display all unread messages,
593     ‘t.’ will display the “dot”, ‘t 1 5’ will type the messages 1 and 5, ‘t
594     1-5’ will type the messages 1 through 5, and ‘t-’ and ‘t+’ will display
595     the previous and the next message, respectively.  The command search (a
596     more substantial alias for from) will display a header summary of the
597     given message specification list instead of their content; the following
598     will search for subjects:
599
600           ? from '@Some subject to search for'
601
602     In the default setup all header fields of a message will be typed, but
603     fields can be white- or blacklisted for a variety of applications by us‐
604     ing the command headerpick, e.g., to restrict their display to a very re‐
605     stricted set for type: ‘headerpick type retain from to cc subject’.  In
606     order to display all header fields of a message regardless of currently
607     active ignore or retain lists, use the commands Type and Top; Show will
608     show the raw message content.  Note that historically the global
609     s-nail.rc not only adjusts the list of displayed headers, but also sets
610     crt.  ([v15 behaviour may differ] A yet somewhat restricted) Reliable
611     scriptable message inspection is available via digmsg.
612
613     Dependent upon the configuration a line editor (see the section On
614     terminal control and line editor) aims at making the user experience with
615     the many COMMANDS a bit nicer.  When reading the system inbox, or when -f
616     (or folder) specified a mailbox explicitly prefixed with the special ‘%:’
617     modifier (to propagate it to a primary system mailbox), then messages
618     which have been read (see Message states) will be automatically moved to
619     a secondary mailbox, the user's MBOX file, when the mailbox is left, ei‐
620     ther by changing the active mailbox or by quitting S-nail – this auto‐
621     matic moving from a system- or primary- to the secondary mailbox is not
622     performed when the variable hold is set.  Messages can also be explicitly
623     moved to other mailboxes, whereas copy keeps the original message.  write
624     can be used to write out data content of specific parts of messages.
625
626     After examining a message the user can reply ‘r’ to the sender and all
627     recipients (which will also be placed in ‘To:’ unless recipients-in-cc is
628     set), or Reply ‘R’ exclusively to the sender(s).  To comply with with the
629     receivers desired reply address the quadoptions followup-to-honour and
630     reply-to-honour should usually be set.  The commands Lreply and Lfollowup
631     know how to apply a special addressee massage, see Mailing lists.  Depen‐
632     dent on the presence and value of quote the message being replied to will
633     be included in a quoted form.  forwarding a message will allow editing
634     the new message: the original message will be contained in the message
635     body, adjusted according to headerpick.  It is possible to resend or
636     Resend messages: the former will add a series of ‘Resent-’ headers,
637     whereas the latter will not; different to newly created messages editing
638     is not possible and no copy will be saved even with record unless the ad‐
639     ditional variable record-resent is set.  When sending, replying or for‐
640     warding messages comments and full names will be stripped from recipient
641     addresses unless the internal variable fullnames is set.
642
643     Of course messages can be delete ‘d’, and they can spring into existence
644     again via undelete, or when the S-nail session is ended via the exit or
645     xit commands to perform a quick program termation.  To end a mail pro‐
646     cessing session regularly and perform a full program exit one may issue
647     the command quit.  It will, among others, move read messages to the
648     secondary mailbox MBOX as necessary, discard deleted messages in the cur‐
649     rent mailbox, and update the [Option]al (see features) line editor
650     history-file.  By the way, whenever the main event loop is about to look
651     out for the next input line it will trigger the hook on-main-loop-tick.
652
653   HTML mail and MIME attachments
654     HTML-only messages become more and more common, and many messages come
655     bundled with a bouquet of MIME (Multipurpose Internet Mail Extensions)
656     parts and attachments.  To get a notion of MIME types there is a built-in
657     default set, onto which the content of The mime.types files will be added
658     (as configured and allowed by mimetypes-load-control).  Types can also
659     become registered and listed with the command mimetype.  To improve in‐
660     teraction with the faulty MIME part declarations of real life
661     mime-counter-evidence will allow verification of the given assertion, and
662     the possible provision of an alternative, better MIME type.  Note plain
663     text parts will always be preferred in ‘multipart/alternative’ MIME mes‐
664     sages unless mime-alternative-favour-rich is set.
665
666     Whereas a simple HTML-to-text filter for displaying HTML messages is [Op‐
667     tion]ally supported (indicated by ‘,+filter-html-tagsoup,’ in features),
668     MIME types other than plain text cannot be handled directly.  To deal
669     with specific non-text MIME types or file extensions programs need to be
670     registered which either prepare (re-)integrable plain text versions of
671     their input (a mode which is called copiousoutput), or display the con‐
672     tent externally, for example in a graphical window: the latter type is
673     only considered by and for the command mimeview.
674
675     To install a handler program for a MIME type an according
676     pipe-TYPE/SUBTYPE variable needs to be set; to define a handler for a
677     file extension pipe-EXTENSION can be used – these handlers take prece‐
678     dence.  [Option]ally mail user agent configuration is supported (see The
679     Mailcap files), and will be queried for display or quote handlers after
680     the former ones.  Type-markers registered via mimetype are the last pos‐
681     sible source for information how to handle a MIME type.
682
683     For example, to display HTML messages integrated via the text browsers
684     lynx(1) or elinks(1), register a MathML MIME type and enable its plain
685     text display, and to open PDF attachments in an external PDF viewer,
686     asynchronously and with some other magic attached:
687
688           ? if "$features" !% ,+filter-html-tagsoup,
689           ?   #set pipe-text/html='?* elinks -force-html -dump 1'
690           ?   set pipe-text/html='?* lynx -stdin -dump -force_html'
691           ?   # Display HTML as plain text instead
692           ?   #set pipe-text/html=?t
693           ? endif
694
695           ? mimetype ?t application/mathml+xml mathml
696
697           ? wysh set pipe-application/pdf='?&=? \
698               trap "rm -f \"${MAILX_FILENAME_TEMPORARY}\"" EXIT;\
699               trap "trap \"\" INT QUIT TERM; exit 1" INT QUIT TERM;\
700               mupdf "${MAILX_FILENAME_TEMPORARY}"'
701
702           ? define showhtml {
703           ?   \localopts yes
704           ?   \set mime-alternative-favour-rich pipe-text/html=?h?
705           ?   \type "$@"
706           ? }
707           ? \commandalias html \\call showhtml
708
709   Mailing lists
710     Known or subscribed-to mailing lists may be flagged in the summary of
711     headers (headline format character ‘%L’), and will gain special treatment
712     when sending mails: the variable followup-to-honour will ensure that a
713     ‘Mail-Followup-To:’ header is honoured when a message is being replied to
714     (reply, followup, Lreply, Lfollowup), and followup-to controls creation
715     of this header when creating mails, if the necessary user setup (from,
716     sender); is available; then, it may also be created automatically, for
717     example when list-replying via Lreply or Lfollowup, when followup or
718     reply is used and the messages ‘Mail-Followup-To:’ is honoured etc.
719
720     The commands mlist and mlsubscribe manage S-nails notion of which ad‐
721     dresses are mailing lists.  With the [Option]al regular expression sup‐
722     port any address which contains any of the magic regular expression char‐
723     acters (‘^[*+?|$’; see re_format(7) or regex(7), dependent on the host
724     system) will be compiled and used as one, possibly matching many ad‐
725     dresses.  It is not possible to escape the “magic”: in order to match
726     special characters as-is, bracket expressions must be used, for example
727search @subject@'[[]open bracket'’.
728
729           ? set followup-to followup-to-honour=ask-yes \
730               reply-to-honour=ask-yes
731           ? mlist a1@b1.c1 a2@b2.c2 '.*@lists\.c3$'
732           ? mlsubscribe a4@b4.c4 exact@lists.c3
733
734     Known and subscribed lists differ in that for the latter the users ad‐
735     dress is not part of a generated ‘Mail-Followup-To:’.  There are excep‐
736     tions, for example if multiple lists are addressed and not all have the
737     subscription attribute.  When replying to a message its list address
738     (‘List-Post:’ header) is automatically and temporarily treated like a
739     known mlist; dependent on the variable reply-to-honour an existing
740     ‘Reply-To:’ is used instead (if it is a single address on the same domain
741     as ‘List-Post:’) in order to accept a list administrator's wish that is
742     supposed to have been manifested like that.
743
744     For convenience and compatibility with mail programs that do not honour
745     the non-standard M-F-T, an automatic user entry in the carbon-copy ‘Cc:’
746     address list of generated message can be created by setting
747     followup-to-add-cc.  This entry will be added whenever the user will be
748     placed in the ‘Mail-Followup-To:’ list, and is not a regular addressee
749     already.  reply-to-swap-in tries to deal with the address rewriting that
750     many mailing-lists nowadays perform to work around DKIM / DMARC etc.
751     standard imposed problems.
752
753   Signed and encrypted messages with S/MIME
754     [Option] S/MIME provides two central mechanisms: message signing and mes‐
755     sage encryption.  A signed message contains some data in addition to the
756     regular text.  The data can be used to verify that the message has been
757     sent using a valid certificate, that the sender address matches that in
758     the certificate, and that the message text has not been altered.  Signing
759     a message does not change its regular text; it can be read regardless of
760     whether the recipients software is able to handle S/MIME.  It is thus
761     usually possible to sign all outgoing messages if so desired.
762
763     Encryption, in contrast, makes the message text invisible for all people
764     except those who have access to the secret decryption key.  To encrypt a
765     message, the specific recipients public encryption key must be known.  It
766     is therefore not possible to send encrypted mail to people unless their
767     key has been retrieved from either previous communication or public key
768     directories.  Because signing is performed with private keys, and encryp‐
769     tion with public keys, messages should always be signed before being en‐
770     crypted.
771
772     A central concept to S/MIME is that of the certification authority (CA).
773     A CA is a trusted institution that issues certificates.  For each of
774     these certificates it can be verified that it really originates from the
775     CA, provided that the CA's own certificate is previously known.  A set of
776     CA certificates is usually delivered and installed together with the
777     cryptographical library that is used on the local system.  Therefore rea‐
778     sonable security for S/MIME on the Internet is provided if the source
779     that provides that library installation is trusted.  It is also possible
780     to use a specific pool of trusted certificates.  If this is desired,
781     smime-ca-no-defaults should be set to avoid using the default certificate
782     pool, and smime-ca-file and/or smime-ca-dir should be pointed to a
783     trusted pool of certificates.  A certificate cannot be more secure than
784     the method its CA certificate has been retrieved with.
785
786     This trusted pool of certificates is used by the command verify to ensure
787     that the given S/MIME messages can be trusted.  If so, verified sender
788     certificates that were embedded in signed messages can be saved locally
789     with the command certsave, and used by S-nail to encrypt further communi‐
790     cation with these senders:
791
792           ? certsave FILENAME
793           ? set smime-encrypt-USER@HOST=FILENAME \
794               smime-cipher-USER@HOST=AES256
795
796     To sign outgoing messages, in order to allow receivers to verify the ori‐
797     gin of these messages, a personal S/MIME certificate is required.  S-nail
798     supports password-protected personal certificates (and keys), see
799     smime-sign-cert.  The section On URL syntax and credential lookup gives
800     an overview of the possible sources of user credentials, and S/MIME step
801     by step shows examplarily how a private S/MIME certificate can be ob‐
802     tained.  In general, if such a private key plus certificate “pair” is
803     available, all that needs to be done is to set some variables:
804
805           ? set smime-sign-cert=ME@exam.ple.paired \
806               smime-sign-digest=SHA512 \
807               smime-sign from=myname@my.host
808
809     Variables of interest for S/MIME in general are smime-ca-dir,
810     smime-ca-file, smime-ca-flags, smime-ca-no-defaults, smime-crl-dir,
811     smime-crl-file.  For S/MIME signing of interest are smime-sign,
812     smime-sign-cert, smime-sign-include-certs and smime-sign-digest.  Addi‐
813     tional variables of interest for S/MIME en- and decryption: smime-cipher
814     and smime-encrypt-USER@HOST.  Variables of secondary interest may be
815     content-description-smime-message and
816     content-description-smime-signature.  S/MIME is available if ‘,+smime,’
817     is included in features.
818
819     [v15 behaviour may differ] Note that neither S/MIME signing nor encryp‐
820     tion applies to message subjects or other header fields yet.  Thus they
821     may not contain sensitive information for encrypted messages, and cannot
822     be trusted even if the message content has been verified.  When sending
823     signed messages, it is recommended to repeat any important header infor‐
824     mation in the message text.
825
826   On URL syntax and credential lookup
827     For accessing protocol-specific resources Uniform Resource Locators (URL,
828     RFC 3986) have become omnipresent.  Here they are expected in a
829     “normalized” variant, not used in data exchange, but only meant as a com‐
830     pact, easy-to-use way of defining and representing information in a well-
831     known notation; as such they do not conform to any real standard.  Op‐
832     tional parts are placed in brackets ‘[]’, optional either because there
833     also exist other ways to define the information, or because the part is
834     protocol specific.  ‘/path’ for example is used by the [Option]al Maildir
835     folder type and the IMAP protocol, but not by POP3.  If ‘USER’ and
836     ‘PASSWORD’ are included in an URL server specification, URL percent en‐
837     coded (RFC 3986) forms are needed, generable with urlcodec.
838
839           PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
840
841     Often INTERNAL VARIABLES exist in multiple versions, called “variable
842     chains” in this document: the plain ‘variable’ as well as ‘variable-HOST’
843     and ‘variable-USER@HOST’.  If a port was specified ‘HOST’ really means
844     ‘server:port’, not ‘server’.  And this ‘USER’ is never in URL percent en‐
845     coded form.  For example, whether the hypothetical ‘smtp://wings%3Aof
846     @a.dove’ including user and password was used, or whether it was
847     ‘smtp://a.dove’ and it came from a different source, to lookup the chain
848     tls-config-pairs first ‘tls-config-pairs-wings:of@a.dove’ is looked up,
849     then ‘tls-config-pairs-a.dove’, before finally looking up the plain vari‐
850     able.
851
852     The logic to collect (an accounts) credential information is as follows:
853
854     A user is always required.  If no ‘USER’ has been given in the URL
855         the variables user-HOST and user are looked up.  Afterwards, when en‐
856         forced by the [Option]al variables netrc-lookup-HOST or netrc-lookup,
857         The .netrc file of the user will be searched for a ‘HOST’ specific
858         entry which provides a ‘login’ name: only unambiguous entries are
859         used (one possible matching entry for ‘HOST’).
860
861         If there is still no ‘USER’ then the verified LOGNAME, known to be a
862         valid user on the current host, is used.
863
864     Authentication: unless otherwise noted the chain
865         PROTOCOL-auth-USER@HOST, PROTOCOL-auth-HOST, PROTOCOL-auth is
866         checked, falling back to a protocol-specific default as necessary.
867
868     If no ‘PASSWORD’ has been given in the URL, then if the ‘USER’ has
869         been found through the [Option]al netrc-lookup, that may have also
870         provided the password.  Otherwise the chain password-USER@HOST,
871         password-HOST, password is looked up.
872
873         Thereafter the (now complete) [Option]al chain
874         netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup is checked,
875         if set the netrc cache is searched for a password only (multiple user
876         accounts for a single machine may exist as well as a fallback entry
877         without user but with a password).
878
879         If at that point there is still no password available, but the (pro‐
880         tocols') chosen authentication type requires a password, then in in‐
881         teractive mode the user will be prompted on the terminal.
882
883     Note: S/MIME verification works relative to the values found in the
884     ‘From:’ (or ‘Sender:’) header field(s), which means the values of
885     smime-sign, smime-sign-cert, smime-sign-include-certs and
886     smime-sign-digest will not be looked up using the ‘USER’ and ‘HOST’
887     chains from above, but instead use the corresponding values from the mes‐
888     sage that is being worked on.  If no address matches we assume and use
889     the setting of from.  In unusual cases multiple and different ‘USER’ and
890     ‘HOST’ combinations may therefore be involved – on the other hand those
891     unusual cases become possible.  The usual case is as short as:
892
893           set mta=smtp://USER:PASS@HOST smtp-use-starttls \
894               smime-sign smime-sign-cert=+smime.pair \
895               from=myname@my.host
896
897     The section EXAMPLES contains complete example configurations.
898
899   Encrypted network communication
900     [Option] SSL (Secure Sockets Layer) aka its successor TLS (Transport
901     Layer Security) are protocols which aid in securing communication by pro‐
902     viding a safely initiated and encrypted network connection.  A central
903     concept of TLS are certificates: as part of each network connection setup
904     a (set of) certificates will be exchanged through which the identity of
905     the network peer can be cryptographically verified; if possible the
906     TLS/SNI (ServerNameIndication) extension will be enabled to allow servers
907     fine-grained control over the certificates being used.  A locally in‐
908     stalled pool of trusted certificates will then be inspected, and verifi‐
909     cation will succeed if it contains a(n in)direct signer of the presented
910     certificate(s).
911
912     The local pool of trusted so-called CA (Certification Authority) certifi‐
913     cates is usually delivered with and used along the TLS library.  A custom
914     pool of trusted certificates can be selected by pointing tls-ca-file
915     and/or (with special preparation) tls-ca-dir to the desired location;
916     setting tls-ca-no-defaults in addition will avoid additional inspection
917     of the default pool.  A certificate cannot be more secure than the method
918     its CA certificate has been retrieved with.  For inspection or other pur‐
919     poses, the certificate of a server (as seen when connecting to it) can be
920     fetched with the command tls (port can usually be the protocol name, too,
921     and tls-verify is taken into account here):
922
923           $ s-nail -vX 'tls certchain SERVER-URL[:PORT]; x'
924
925     A local pool of CA certificates is not strictly necessary, however,
926     server certificates can also be verified via their fingerprint.  For this
927     a message digest will be calculated and compared against the variable
928     chain tls-fingerprint, and verification will succeed if the fingerprint
929     matches.  The message digest (algorithm) can be configured via the vari‐
930     able chain tls-fingerprint-digest; tls can again be used:
931
932           $ s-nail -X 'wysh set verbose; tls fingerprint SERVER-URL[:PORT]; x'
933
934     It depends on the used protocol whether encrypted communication is possi‐
935     ble, and which configuration steps have to be taken to enable it.  Some
936     protocols, like POP3S, are implicitly encrypted, others, like POP3, can
937     upgrade a plain text connection if so requested.  For example, to use the
938     ‘STLS’ that POP3 offers (a member of) the variable (chain)
939     pop3-use-starttls needs to be set, with convenience via shortcut:
940
941           shortcut encpop1 pop3s://pop1.exam.ple
942
943           shortcut encpop2 pop3://pop2.exam.ple
944           set pop3-use-starttls-pop2.exam.ple
945
946           set mta=smtps://smtp.exam.ple:465
947           set mta=smtp://smtp.exam.ple smtp-use-starttls
948
949     Normally that is all there is to do, given that TLS libraries try to pro‐
950     vide safe defaults, plenty of knobs however exist to adjust settings.
951     For example certificate verification settings can be fine-tuned via
952     tls-ca-flags, and the TLS configuration basics are accessible via
953     tls-config-pairs, for example to control protocol versions or cipher
954     lists.  In the past hints on how to restrict the set of protocols to
955     highly secure ones were indicated, but as of the time of this writing the
956     list of protocols or ciphers may need to become relaxed in order to be
957     able to connect to some servers; the following example allows connecting
958     to a “Lion” that uses OpenSSL 0.9.8za from June 2014 (refer to INTERNAL
959     VARIABLES for more on variable chains):
960
961           wysh set tls-config-pairs-lion@exam.ple='MinProtocol=TLSv1.1,\
962               CipherString=TLSv1.2:!aNULL:!eNULL:\
963                 ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\
964                 DHE-RSA-AES256-SHA:@STRENGTH'
965
966     The OpenSSL program ciphers(1) should be referred to when creating a cus‐
967     tom cipher list.  Variables of interest for TLS in general are
968     tls-ca-dir, tls-ca-file, tls-ca-flags, tls-ca-no-defaults,
969     tls-config-file, tls-config-module, tls-config-pairs, tls-crl-dir,
970     tls-crl-file, tls-rand-file as well as tls-verify.  Also see
971     tls-features.  TLS is available if ‘+tls’ is included in features.
972
973   Character sets
974     [Option] The user's locale environment is detected by looking at the
975     LC_ALL environment variable.  The internal variable ttycharset will be
976     set to the detected terminal character set accordingly, and will thus
977     show up in the output of commands like set and varshow.  This character
978     set will be targeted when trying to display data, and user input data is
979     expected to be in this character set, too.
980
981     When creating messages their character input data is classified.  7-bit
982     clean text data and attachments will be classified as charset-7bit.
983     8-bit data will [Option]ally be converted into members of sendcharsets
984     until a character set conversion succeeds.  charset-8bit is the implied
985     default last member of this list.  If no 8-bit character set is capable
986     to represent input data, no message will be sent, and its text will op‐
987     tionally be saved in DEAD.  If that is not acceptable, for example in
988     script environments, mime-force-sendout can be set to force sending of
989     non-convertible data as ‘application/octet-stream’ classified binary con‐
990     tent instead: like this receivers still have the option to inspect mes‐
991     sage content (for example via mime-counter-evidence).  If the [Option]al
992     character set conversion is not available (features misses ‘,+iconv,’),
993     ttycharset is the only supported character set for non 7-bit clean data,
994     and it is simply assumed it can be used to exchange 8-bit messages.
995
996     ttycharset may also be given an explicit value to send mail in a com‐
997     pletely “faked” locale environment, which can be used to generate and
998     send for example 8-bit UTF-8 input data in a pure 7-bit US-ASCII
999     ‘LC_ALL=C’ environment (an example of this can be found in the section On
1000     sending mail, and non-interactive mode).  Due to lack of programming in‐
1001     terfaces reading mail will not really work as expected in a faked envi‐
1002     ronment: whereas ttycharset might be addressable, any output will be made
1003     safely printable, as via vexpr makeprint, according to the actual locale
1004     environment, which is not affected by ttycharset.
1005
1006     Classifying 7-bit clean data as charset-7bit is a problem if the input
1007     character set (ttycharset) is a multibyte character set that is itself
1008     7-bit clean.  For example, the Japanese character set ISO-2022-JP is, but
1009     is capable to encode the rich set of Japanese Kanji, Hiragana and
1010     Katakana characters: in order to notify receivers of this character set
1011     the mail message must be MIME encoded so that the character set
1012     ISO-2022-JP can be advertised, otherwise an invalid email message would
1013     result!  To achieve this, the variable charset-7bit can be set to
1014     ISO-2022-JP.  (Today a better approach regarding email is the usage of
1015     UTF-8, which uses 8-bit bytes for non-US-ASCII data.)
1016
1017     When replying to a message and the variable reply-in-same-charset is set,
1018     the character set of the message being replied to is tried first as a
1019     target character set (still being a subject of charsetalias filtering,
1020     however).  Another opportunity is sendcharsets-else-ttycharset to reflect
1021     the user's locale environment automatically, it will treat ttycharset as
1022     an implied member of (an unset) sendcharsets.
1023
1024     [Option] When reading messages, their text data is converted into
1025     ttycharset as necessary in order to display them on the user's terminal.
1026     Unprintable characters and invalid byte sequences are detected and re‐
1027     placed by substitution characters.  Character set mappings for source
1028     character sets can be established with charsetalias, which may be handy
1029     to work around faulty or incomplete character set catalogues (one could
1030     for example add a missing LATIN1 to ISO-8859-1 mapping), or to enforce
1031     treatment of one character set as another one (“interpret LATIN1 as
1032     CP1252”).  Also see charset-unknown-8bit to deal with another hairy as‐
1033     pect of message interpretation.
1034
1035     In general, if a message saying “cannot convert from a to b” appears, ei‐
1036     ther some characters are not appropriate for the currently selected (ter‐
1037     minal) character set, or the needed conversion is not supported by the
1038     system.  In the first case, it is necessary to set an appropriate
1039     LC_CTYPE locale and/or the variable ttycharset.  The best results are
1040     usually achieved when running in a UTF-8 locale on a UTF-8 capable termi‐
1041     nal, in which case the full Unicode spectrum of characters is available.
1042     In this setup characters from various countries can be displayed, while
1043     it is still possible to use more simple character sets for sending to re‐
1044     tain maximum compatibility with older mail clients.
1045
1046     On the other hand the POSIX standard defines a locale-independent 7-bit
1047     “portable character set” that should be used when overall portability is
1048     an issue, the even more restricted subset named “portable filename
1049     character set” consists of A-Z, a-z, 0-9, period ‘.’, underscore ‘_’ and
1050     hyphen-minus ‘-’.
1051
1052   Message states
1053     S-nail differentiates in between several message states; the current
1054     state will be reflected in the summary of headers if the attrlist of the
1055     configured headline allows, and Specifying messages dependent on their
1056     state is possible.  When operating on the system inbox, or in any other
1057     primary system mailbox, special actions, like the automatic moving of
1058     messages to the secondary mailbox MBOX, may be applied when the mailbox
1059     is left (also implicitly by program termination, unless the command exit
1060     was used) – however, because this may be irritating to users which are
1061     used to “more modern” mail-user-agents, the provided global s-nail.rc
1062     template sets the internal hold and keepsave variables in order to sup‐
1063     press this behaviour.
1064
1065     ‘new’     Message has neither been viewed nor moved to any other state.
1066               Such messages are retained even in the primary system mailbox.
1067
1068     ‘unread’  Message has neither been viewed nor moved to any other state,
1069               but the message was present already when the mailbox has been
1070               opened last: Such messages are retained even in the primary
1071               system mailbox.
1072
1073     ‘read’    The message has been processed by one of the following com‐
1074               mands: ~f, ~m, ~F, ~M, copy, mbox, next, pipe, Print, print,
1075               top, Type, type, undelete.  The commands dp and dt will always
1076               try to automatically “step” and type the “next” logical mes‐
1077               sage, and may thus mark multiple messages as read, the delete
1078               command will do so if the internal variable autoprint is set.
1079
1080               Except when the exit command is used, messages that are in a
1081               primary system mailbox and are in ‘read’ state when the mailbox
1082               is left will be saved in the secondary mailbox MBOX unless the
1083               internal variable hold it set.
1084
1085     ‘deleted’ The message has been processed by one of the following com‐
1086               mands: delete, dp, dt.  Only undelete can be used to access
1087               such messages.
1088
1089     ‘preserved’ The message has been processed by a preserve command and it
1090               will be retained in its current location.
1091
1092     ‘saved’   The message has been processed by one of the following com‐
1093               mands: save or write.  Unless when the exit command is used,
1094               messages that are in a primary system mailbox and are in
1095               ‘saved’ state when the mailbox is left will be deleted; they
1096               will be saved in the secondary mailbox MBOX when the internal
1097               variable keepsave is set.
1098
1099     In addition to these message states, flags which otherwise have no tech‐
1100     nical meaning in the mail system except allowing special ways of address‐
1101     ing them when Specifying messages can be set on messages.  These flags
1102     are saved with messages and are thus persistent, and are portable between
1103     a set of widely used MUAs.
1104
1105     answered  Mark messages as having been answered.
1106
1107     draft     Mark messages as being a draft.
1108
1109     flag      Mark messages which need special attention.
1110
1111   Specifying messages
1112     [Only new quoting rules] COMMANDS which take Message list arguments, such
1113     as search, type, copy, and delete, can perform actions on a number of
1114     messages at once.  Specifying invalid messages, or using illegal syntax,
1115     will cause errors to be reported through the INTERNAL VARIABLES !, ^ERR
1116     and companions, as well as the command exit status ?.
1117
1118     For example, ‘delete 1 2’ deletes the messages 1 and 2, whereas ‘delete
1119     1-5’ will delete the messages 1 through 5.  In sorted or threaded mode
1120     (see the sort command), ‘delete 1-5’ will delete the messages that are
1121     located between (and including) messages 1 through 5 in the
1122     sorted/threaded order, as shown in the headers summary.
1123
1124     Errors can for example be ^ERR-BADMSG when requesting an invalid message,
1125     ^ERR-NOMSG if no applicable message can be found, ^ERR-CANCELED for miss‐
1126     ing informational data (mostly thread-related).  ^ERR-INVAL for invalid
1127     syntax as well as ^ERR-IO for input/output errors can happen.  The fol‐
1128     lowing special message names exist:
1129
1130     .         The current message, the so-called “dot”.
1131
1132     ;         The message that was previously the current message; needs to
1133               be quoted.
1134
1135     ,         The parent message of the current message, that is the message
1136               with the Message-ID given in the ‘In-Reply-To:’ field or the
1137               last entry of the ‘References:’ field of the current message.
1138
1139     -         The previous undeleted message, or the previous deleted message
1140               for the undelete command; In sorted or ‘thread’ed mode, the
1141               previous such message in the according order.
1142
1143     +         The next undeleted message, or the next deleted message for the
1144               undelete command; In sorted or ‘thread’ed mode, the next such
1145               message in the according order.
1146
1147     ^         The first undeleted message, or the first deleted message for
1148               the undelete command; In sorted or ‘thread’ed mode, the first
1149               such message in the according order.
1150
1151     $         The last message; In sorted or ‘thread’ed mode, the last such
1152               message in the according order.  Needs to be quoted.
1153
1154     &x        In ‘thread’ed sort mode, selects the message addressed with x,
1155               where x is any other message specification, and all messages
1156               from the thread that begins at it.  Otherwise it is identical
1157               to x.  If x is omitted, the thread beginning with the current
1158               message is selected.
1159
1160     *         All messages.
1161
1162     `         All messages that were included in the Message list arguments
1163               of the previous command; needs to be quoted.  (A convenient way
1164               to read all new messages is to select them via ‘from :n’, as
1165               below, and then to read them in order with the default command
1166next — simply by successively typing ‘`’; for this to work
1167               showlast must be set.)
1168
1169     x-y       An inclusive range of message numbers.  Selectors that may also
1170               be used as endpoints include any of .;-+^$.
1171
1172     address   A case-insensitive “any substring matches” search against the
1173               ‘From:’ header, which will match addresses (too) even if
1174               showname is set (and POSIX says “any address as shown in a
1175               header summary shall be matchable in this form”); However, if
1176               the allnet variable is set, only the local part of the address
1177               is evaluated for the comparison, not ignoring case, and the
1178               setting of showname is completely ignored.  For finer control
1179               and match boundaries use the ‘@’ search expression.
1180
1181     /string   All messages that contain string in the subject field (case ig‐
1182               nored according to locale).  See also the searchheaders vari‐
1183               able.  If string is empty, the string from the previous speci‐
1184               fication of that type is used again.
1185
1186     [@name-list]@expr
1187               All messages that contain the given case-insensitive search
1188               expression;  If the [Option]al regular expression support is
1189               available expr will be interpreted as (an extended) one if any
1190               of the magic regular expression characters is seen.  If the op‐
1191               tional @name-list part is missing the search is restricted to
1192               the subject field body, but otherwise name-list specifies a
1193               comma-separated list of header fields to search, for example
1194
1195                     '@to,from,cc@Someone i ought to know'
1196
1197               In order to search for a string that includes a ‘@’ (commercial
1198               at) character the name-list is effectively non-optional, but
1199               may be given as the empty string.  Also, specifying an empty
1200               search expression will effectively test for existence of the
1201               given header fields.  Some special header fields may be abbre‐
1202               viated: ‘f’, ‘t’, ‘c’, ‘b’ and ‘s’ will match ‘From’, ‘To’,
1203               ‘Cc’, ‘Bcc’ and ‘Subject’, respectively and case-insensitively.
1204               [Option]ally, and just like expr, name-list will be interpreted
1205               as (an extended) regular expression if any of the magic regular
1206               expression characters is seen.
1207
1208               The special names ‘header’ or ‘<’ can be used to search in (all
1209               of) the header(s) of the message, and the special names ‘body’
1210               or ‘>’ and ‘text’ or ‘=’ will perform full text searches –
1211               whereas the former searches only the body, the latter also
1212               searches the message header ([v15 behaviour may differ] this
1213               mode yet brute force searches over the entire decoded content
1214               of messages, including administrativa strings).
1215
1216               This specification performs full text comparison, but even with
1217               regular expression support it is almost impossible to write a
1218               search expression that safely matches only a specific address
1219               domain.  To request that the body content of the header is
1220               treated as a list of addresses, and to strip those down to the
1221               plain email address which the search expression is to be
1222               matched against, prefix the effective name-list with a tilde
1223               ‘~’:
1224
1225                     '@~f,c@@a\.safe\.domain\.match$'
1226
1227     :c        All messages of state or with matching condition ‘c’, where ‘c’
1228               is one or multiple of the following colon modifiers:
1229
1230               a         answered messages (cf. the variable markanswered).
1231               d         ‘deleted’ messages (for the undelete and from com‐
1232                         mands only).
1233               f         flagged messages.
1234               L         Messages with receivers that match mlsubscribed ad‐
1235                         dresses.
1236               l         Messages with receivers that match mlisted addresses.
1237               n         ‘new’ messages.
1238               o         Old messages (any not in state ‘read’ or ‘new’).
1239               r         ‘read’ messages.
1240               S         [Option] Messages with unsure spam classification
1241                         (see Handling spam).
1242               s         [Option] Messages classified as spam.
1243               t         Messages marked as draft.
1244               u         ‘unread’ messages.
1245
1246     [Option] IMAP-style SEARCH expressions may also be used.  These consist
1247     of keywords and criterions, and because Message list arguments are split
1248     into tokens according to Shell-style argument quoting it is necessary to
1249     quote the entire IMAP search expression in order to ensure that it re‐
1250     mains a single token.  This addressing mode is available with all types
1251     of mailbox folders; S-nail will perform the search locally as necessary.
1252     Strings must be enclosed by double quotation marks ‘"’ in their entirety
1253     if they contain whitespace or parentheses; within the quotes, only re‐
1254     verse solidus ‘\’ is recognized as an escape character.  All string
1255     searches are case-insensitive.  When the description indicates that the
1256     “envelope” representation of an address field is used, this means that
1257     the search string is checked against both a list constructed as
1258
1259           '("name" "source" "local-part" "domain-part")'
1260
1261     for each address, and the addresses without real names from the respec‐
1262     tive header field.  These search expressions can be nested using paren‐
1263     theses, see below for examples.
1264
1265     (criterion)
1266               All messages that satisfy the given criterion.
1267     (criterion1 criterion2 ... criterionN)
1268               All messages that satisfy all of the given criteria.
1269     (or criterion1 criterion2)
1270               All messages that satisfy either criterion1 or criterion2, or
1271               both.  To connect more than two criteria using ‘or’ specifica‐
1272               tions have to be nested using additional parentheses, as with
1273               ‘(or a (or b c))’, since ‘(or a b c)’ really means ‘((a or b)
1274               and c)’.  For a simple ‘or’ operation of independent criteria
1275               on the lowest nesting level, it is possible to achieve similar
1276               effects by using three separate criteria, as with ‘(a) (b)
1277               (c)’.
1278     (not criterion)
1279               All messages that do not satisfy criterion.
1280     (bcc "string")
1281               All messages that contain string in the envelope representation
1282               of the ‘Bcc:’ field.
1283     (cc "string")
1284               All messages that contain string in the envelope representation
1285               of the ‘Cc:’ field.
1286     (from "string")
1287               All messages that contain string in the envelope representation
1288               of the ‘From:’ field.
1289     (subject "string")
1290               All messages that contain string in the ‘Subject:’ field.
1291     (to "string")
1292               All messages that contain string in the envelope representation
1293               of the ‘To:’ field.
1294     (header name "string")
1295               All messages that contain string in the specified ‘Name:’
1296               field.
1297     (body "string")
1298               All messages that contain string in their body.
1299     (text "string")
1300               All messages that contain string in their header or body.
1301     (larger size)
1302               All messages that are larger than size (in bytes).
1303     (smaller size)
1304               All messages that are smaller than size (in bytes).
1305     (before date)
1306               All messages that were received before date, which must be in
1307               the form ‘d[d]-mon-yyyy’, where ‘d’ denotes the day of the
1308               month as one or two digits, ‘mon’ is the name of the month –
1309               one of ‘Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec’, and
1310               ‘yyyy’ is the year as four digits, for example ‘28-Dec-2012’.
1311     (on date)
1312               All messages that were received on the specified date.
1313     (since date)
1314               All messages that were received since the specified date.
1315     (sentbefore date)
1316               All messages that were sent on the specified date.
1317     (senton date)
1318               All messages that were sent on the specified date.
1319     (sentsince date)
1320               All messages that were sent since the specified date.
1321     ()        The same criterion as for the previous search.  This specifica‐
1322               tion cannot be used as part of another criterion.  If the pre‐
1323               vious command line contained more than one independent crite‐
1324               rion then the last of those criteria is used.
1325
1326   On terminal control and line editor
1327     [Option] Terminal control through one of the standard UNIX libraries,
1328     Termcap Access Library (libtermcap, -ltermcap) or Terminal Information
1329     Library (libterminfo, -lterminfo), may be available.  For the TERMinal
1330     defined in the environment interactive usage aspects, for example
1331     Coloured display, and insight of cursor and function keys for the Mailx-
1332     Line-Editor (MLE), will be enhanced or enabled.  Library interaction can
1333     be disabled on a per-invocation basis via termcap-disable, whereas the
1334     internal variable termcap is always used as a preferred source of termi‐
1335     nal capabilities.  (For a usage example see the FAQ entry Not
1336     "defunctional", but the editor key does not work.)
1337
1338     [Option] The built-in Mailx-Line-Editor (MLE) should work in all environ‐
1339     ments which comply to the ISO C standard ISO/IEC 9899/AMD1:1995
1340     (“ISO C90, Amendment 1”), and will support wide glyphs if possible (the
1341     necessary functionality had been removed from ISO C, but was included in
1342     X/Open Portability Guide Issue 4 (“XPG4”)).  Usage of a line editor in
1343     interactive mode can be prevented by setting line-editor-disable.  Espe‐
1344     cially if the [Option]al terminal control support is missing setting en‐
1345     tries in termcap will help shall the MLE misbehave, see there for more.
1346     The MLE can support a little bit of colour.
1347
1348     [Option] If the history feature is available then input from line editor
1349     prompts will be saved in a history list that can be searched in and be
1350     expanded from.  Such saving can be prevented by prefixing input with any
1351     amount of whitespace.  Aspects of history, like allowed content and maxi‐
1352     mum size, as well as whether history shall be saved persistently, can be
1353     configured with the internal variables history-file, history-gabby,
1354     history-gabby-persist and history-size.  There also exists the macro hook
1355     on-history-addition which can be used to apply finer control on what en‐
1356     ters history.
1357
1358     The MLE supports a set of editing and control commands.  By default (as)
1359     many (as possible) of these will be assigned to a set of single-letter
1360     control codes, which should work on any terminal (and can be generated by
1361     holding the “control” key while pressing the key of desire, for example
1362     ‘control-D’).  If the [Option]al bind command is available then the MLE
1363     commands can also be accessed freely by assigning the command name, which
1364     is shown in parenthesis in the list below, to any desired key-sequence,
1365     and the MLE will instead and also use bind to establish its built-in key
1366     bindings (more of them if the [Option]al terminal control is available),
1367     an action which can then be suppressed completely by setting
1368     line-editor-no-defaults.  Shell-style argument quoting notation is used
1369     in the following:
1370
1371     ‘\cA’     Go to the start of the line (mle-go-home).
1372     ‘\cB’     Move the cursor backward one character (mle-go-bwd).
1373     ‘\cC’     raise(3) ‘SIGINT’ (mle-raise-int).
1374     ‘\cD’     Forward delete the character under the cursor; quits S-nail if
1375               used on the empty line unless the internal variable ignoreeof
1376               is set (mle-del-fwd).
1377     ‘\cE’     Go to the end of the line (mle-go-end).
1378     ‘\cF’     Move the cursor forward one character (mle-go-fwd).
1379     ‘\cG’     Cancel current operation, full reset.  If there is an active
1380               history search or tabulator expansion then this command will
1381               first reset that, reverting to the former line content; thus a
1382               second reset is needed for a full reset in this case
1383               (mle-reset).
1384     ‘\cH’     Backspace: backward delete one character (mle-del-bwd).
1385     ‘\cI’     [Only new quoting rules] Horizontal tabulator: try to expand
1386               the word before the cursor, supporting the usual Filename
1387               transformations (mle-complete; this is affected by
1388               mle-quote-rndtrip and line-editor-cpl-word-breaks).
1389     ‘\cJ’     Newline: commit the current line (mle-commit).
1390     ‘\cK’     Cut all characters from the cursor to the end of the line
1391               (mle-snarf-end).
1392     ‘\cL’     Repaint the line (mle-repaint).
1393     ‘\cN’     [Option] Go to the next history entry (mle-hist-fwd).
1394     ‘\cO’     ([Option]ally context-dependent) Invokes the command dt.
1395     ‘\cP’     [Option] Go to the previous history entry (mle-hist-bwd).
1396     ‘\cQ’     Toggle roundtrip mode shell quotes, where produced, on and off
1397               (mle-quote-rndtrip).  This setting is temporary, and will be
1398               forgotten once the command line is committed; also see shcodec.
1399     ‘\cR’     [Option] Complete the current line from (the remaining) older
1400               history entries (mle-hist-srch-bwd).
1401     ‘\cS’     [Option] Complete the current line from (the remaining) newer
1402               history entries (mle-hist-srch-fwd).
1403     ‘\cT’     Paste the snarf buffer (mle-paste).
1404     ‘\cU’     The same as ‘\cA’ followed by ‘\cK’ (mle-snarf-line).
1405     ‘\cV’     Prompts for a Unicode character (hexadecimal number without
1406               prefix, see vexpr) to be inserted (mle-prompt-char).  Note this
1407               command needs to be assigned to a single-letter control code in
1408               order to become recognized and executed during input of a key-
1409               sequence (only three single-letter control codes can be used
1410               for that shortcut purpose); this control code is then special-
1411               treated and thus cannot be part of any other sequence (because
1412               it will trigger the mle-prompt-char function immediately).
1413     ‘\cW’     Cut the characters from the one preceding the cursor to the
1414               preceding word boundary (mle-snarf-word-bwd).
1415     ‘\cX’     Move the cursor forward one word boundary (mle-go-word-fwd).
1416     ‘\cY’     Move the cursor backward one word boundary (mle-go-word-bwd).
1417     ‘\cZ’     raise(3) ‘SIGTSTP’ (mle-raise-tstp).
1418     ‘\c[’     Escape: reset a possibly used multibyte character input state
1419               machine and [Option]ally a lingering, incomplete key binding
1420               (mle-cancel).  This command needs to be assigned to a single-
1421               letter control code in order to become recognized and executed
1422               during input of a key-sequence (only three single-letter con‐
1423               trol codes can be used for that shortcut purpose).  This con‐
1424               trol code may also be part of a multi-byte sequence, but if a
1425               sequence is active and the very control code is currently also
1426               an expected input, then the active sequence takes precedence
1427               and will consume the control code.
1428     ‘\c\’     ([Option]ally context-dependent) Invokes the command ‘z+’.
1429     ‘\c]’     ([Option]ally context-dependent) Invokes the command ‘z$’.
1430     ‘\c^’     ([Option]ally context-dependent) Invokes the command ‘z0’.
1431     ‘\c_’     Cut the characters from the one after the cursor to the suc‐
1432               ceeding word boundary (mle-snarf-word-fwd).
1433     ‘\c?’     Backspace: mle-del-bwd.
1434mle-bell: ring the audible bell.
1435     –         [Option] mle-clear-screen: move the cursor home and clear the
1436               screen.
1437mle-fullreset: different to mle-reset this will immediately re‐
1438               set a possibly active search etc.
1439mle-go-screen-bwd: move the cursor backward one screen width.
1440mle-go-screen-fwd: move the cursor forward one screen width.
1441     –         mle-raise-quit: raise(3) ‘SIGQUIT’.
1442
1443   Coloured display
1444     [Option] Colours and font attributes through ANSI a.k.a. ISO 6429 SGR
1445     (select graphic rendition) escape sequences are optionally supported.
1446     Usage of colours and font attributes solely depends upon the capability
1447     of the detected terminal type (TERM), and as fine-tuned through termcap.
1448     Colours and font attributes can be managed with the multiplexer command
1449     colour, and uncolour removes the given mappings.  Setting colour-disable
1450     suppresses usage of colour and font attribute sequences, while leaving
1451     established mappings unchanged.
1452
1453     Whether actually applicable colour and font attribute sequences should
1454     also be generated when output is going to be paged through the external
1455     PAGER (also see crt) depends upon the setting of colour-pager, because
1456     pagers usually need to be configured in order to support ISO escape se‐
1457     quences.  Knowledge of some widely used pagers is however built-in, and
1458     in a clean environment it is often enough to simply set colour-pager;
1459     please refer to that variable for more on this topic.
1460
1461     It might make sense to conditionalize colour setup on interactive mode
1462     via if (‘terminal’ indeed means “interactive”):
1463
1464           if terminal && "$features" =% ,+colour,
1465             colour iso view-msginfo ft=bold,fg=green
1466             colour iso view-header ft=bold,fg=red (from|subject) # regex
1467             colour iso view-header fg=red
1468
1469             uncolour iso view-header from,subject
1470             colour iso view-header ft=bold,fg=magenta,bg=cyan
1471             colour 256 view-header ft=bold,fg=208,bg=230 "subject,from"
1472             colour mono view-header ft=bold
1473             colour mono view-header ft=bold,ft=reverse subject,from
1474           endif
1475
1476   Handling spam
1477     [Option] S-nail can make use of several spam interfaces for the purpose
1478     of identification of, and, in general, dealing with spam messages.  A
1479     precondition of most commands in order to function is that the
1480     spam-interface variable is set to one of the supported interfaces.
1481     Specifying messages that have been identified as spam is possible via
1482     their (volatile) ‘is-spam’ state by using the ‘:s’ and ‘:S’ specifica‐
1483     tions, and their attrlist entries will be used when displaying the
1484     headline in the summary of headers.
1485
1486     •   spamrate rates the given messages and sets their ‘is-spam’ flag ac‐
1487         cordingly.  If the spam interface offers spam scores these can be
1488         shown in headline by using the format ‘%$’.
1489
1490     •   spamham, spamspam and spamforget will interact with the Bayesian fil‐
1491         ter of the chosen interface and learn the given messages as “ham” or
1492         “spam”, respectively; the last command can be used to cause
1493         “unlearning” of messages; it adheres to their current ‘is-spam’ state
1494         and thus reverts previous teachings.
1495
1496     •   spamclear and spamset will simply set and clear, respectively, the
1497         mentioned volatile ‘is-spam’ message flag, without any interface in‐
1498         teraction.
1499
1500     The spamassassin(1) based spam-interface ‘spamc’ requires a running in‐
1501     stance of the spamd(1) server in order to function, started with the op‐
1502     tion --allow-tell shall Bayesian filter learning be possible.
1503
1504           $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
1505           $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \
1506               --daemonize [--local] [--allow-tell]
1507
1508     Thereafter S-nail can make use of these interfaces:
1509
1510           $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1511               -Sspamc-command=/usr/local/bin/spamc \
1512               -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
1513           or
1514           $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1515               -Sspamc-command=/usr/local/bin/spamc \
1516               -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
1517
1518     Using the generic filter approach allows usage of programs like
1519     bogofilter(1).  Here is an example, requiring it to be accessible via
1520     PATH:
1521
1522           $ s-nail -Sspam-interface=filter -Sspam-maxsize=500000 \
1523               -Sspamfilter-ham="bogofilter -n" \
1524               -Sspamfilter-noham="bogofilter -N" \
1525               -Sspamfilter-nospam="bogofilter -S" \
1526               -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \
1527               -Sspamfilter-spam="bogofilter -s" \
1528               -Sspamfilter-rate-scanscore="1;^(.+)$"
1529
1530     Because messages must exist on local storage in order to be scored (or
1531     used for Bayesian filter training), it is possibly a good idea to perform
1532     the local spam check last.  Spam can be checked automatically when open‐
1533     ing specific folders by setting a specialized form of the internal vari‐
1534     able folder-hook.
1535
1536           define spamdelhook {
1537             # Server side DCC
1538             spamset (header x-dcc-brand-metrics "bulk")
1539             # Server-side spamassassin(1)
1540             spamset (header x-spam-flag "YES")
1541             del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
1542             move :S +maybe-spam
1543             spamrate :u
1544             del :s
1545             move :S +maybe-spam
1546           }
1547           set folder-hook-SOMEFOLDER=spamdelhook
1548
1549     See also the documentation for the variables spam-interface,
1550     spam-maxsize, spamc-command, spamc-arguments, spamc-user, spamfilter-ham,
1551     spamfilter-noham, spamfilter-nospam, spamfilter-rate and
1552     spamfilter-rate-scanscore.
1553

COMMANDS

1555     S-nail reads input in lines.  An unquoted reverse solidus ‘\’ at the end
1556     of a command line “escapes” the newline character: it is discarded and
1557     the next line of input is used as a follow-up line, with all leading
1558     whitespace removed; once an entire line is completed, the whitespace
1559     characters space, tabulator, newline as well as those defined by the
1560     variable ifs are removed from the beginning and end.  Placing any white‐
1561     space characters at the beginning of a line will prevent a possible addi‐
1562     tion of the command line to the [Option]al history.
1563
1564     The beginning of such input lines is then scanned for the name of a known
1565     command: command names may be abbreviated, in which case the first com‐
1566     mand that matches the given prefix will be used.  Command modifiers may
1567     prefix a command in order to modify its behaviour.  A name may also be a
1568     commandalias, which will become expanded until no more expansion is pos‐
1569     sible.  Once the command that shall be executed is known, the remains of
1570     the input line will be interpreted according to command-specific rules,
1571     documented in the following.
1572
1573     This behaviour is different to the sh(1)ell, which is a programming lan‐
1574     guage with syntactic elements of clearly defined semantics, and therefore
1575     capable to sequentially expand and evaluate individual elements of a
1576     line.  ‘? set one=value two=$one’ for example will never possibly assign
1577     value to one, because the variable assignment is performed no sooner but
1578     by the command (set), long after the expansion happened.
1579
1580     A list of all commands in lookup order is dumped by the command list.
1581     [Option]ally the command help (or ?), when given an argument, will show a
1582     documentation string for the command matching the expanded argument, as
1583     in ‘?t’, which should be a shorthand of ‘?type’; with these documentation
1584     strings both commands support a more verbose listing mode which includes
1585     the argument type of the command and other information which applies; a
1586     handy suggestion might thus be:
1587
1588           ? define __xv {
1589             # Before v15: need to enable sh(1)ell-style on _entire_ line!
1590             localopts yes;wysh set verbose;ignerr eval "${@}";return ${?}
1591           }
1592           ? commandalias xv '\call __xv'
1593           ? xv help set
1594
1595   Command modifiers
1596     Commands may be prefixed by none to multiple command modifiers.  Some
1597     command modifiers can be used with a restricted set of commands only, the
1598     verbose version of list will ([Option]ally) show which modifiers apply.
1599
1600     The modifier reverse solidus \, to be placed first, prevents
1601         commandalias expansions on the remains of the line, for example
1602         ‘\echo’ will always evaluate the command echo, even if an (com‐
1603         mand)alias of the same name exists.  commandalias content may itself
1604         contain further command modifiers, including an initial reverse
1605         solidus to prevent further expansions.
1606
1607     The modifier ignerr indicates that any error generated by the follow‐
1608         ing command should be ignored by the state machine and not cause a
1609         program exit with enabled errexit or for the standardized exit cases
1610         in posix mode.  ?, one of the INTERNAL VARIABLES, will be set to the
1611         real exit status of the command regardless.
1612
1613     •   local will alter the called command to apply changes only temporar‐
1614         ily, local to block-scope, and can thus only be used inside of a
1615         defined macro or an account definition.  Specifying it implies the
1616         modifier wysh.  Local variables will not be inherited by macros
1617         deeper in the call chain, and all local settings will be garbage col‐
1618         lected once the local scope is left.  To record and unroll changes in
1619         the global scope use the command localopts.
1620
1621     •   scope does yet not implement any functionality.
1622
1623     •   u does yet not implement any functionality.
1624
1625     Some commands support the vput modifier: if used, they expect the
1626         name of a variable, which can itself be a variable, i.e., shell ex‐
1627         pansion is applied, as their first argument, and will place their
1628         computation result in it instead of the default location (it is usu‐
1629         ally written to standard output).
1630
1631         The given name will be tested for being a valid sh(1) variable name,
1632         and may therefore only consist of upper- and lowercase characters,
1633         digits, and the underscore; the hyphen-minus may be used as a non-
1634         portable extension; digits may not be used as first, hyphen-minus may
1635         not be used as last characters.  In addition the name may either not
1636         be one of the known INTERNAL VARIABLES, or must otherwise refer to a
1637         writable (non-boolean) value variable.  The actual put operation may
1638         fail nonetheless, for example if the variable expects a number argu‐
1639         ment only a number will be accepted.  Any error during these opera‐
1640         tions causes the command as such to fail, and the error number ! will
1641         be set to ^ERR-NOTSUP, the exit status ? should be set to ‘-1’, but
1642         some commands deviate from the latter, which is documented.
1643
1644     Last, but not least, the modifier wysh can be used for some old and
1645         established commands to choose the new Shell-style argument quoting
1646         rules over the traditional Old-style argument quoting.  This modifier
1647         is implied if v15-compat is set to a non-empty value.
1648
1649   Old-style argument quoting
1650     [v15 behaviour may differ] This section documents the traditional and
1651     POSIX standardized style of quoting non-message list arguments to com‐
1652     mands which expect this type of arguments: whereas still used by the ma‐
1653     jority of such commands, the new Shell-style argument quoting may be
1654     available even for those via wysh, one of the Command modifiers.  None‐
1655     theless care must be taken, because only new commands have been designed
1656     with all the capabilities of the new quoting rules in mind, which can,
1657     for example generate control characters.
1658
1659           An argument can be enclosed between paired double-quotes
1660               ‘"argument"’ or single-quotes ‘'argument'’; any whitespace,
1661               shell word expansion, or reverse solidus characters (except as
1662               described next) within the quotes are treated literally as part
1663               of the argument.  A double-quote will be treated literally
1664               within single-quotes and vice versa.  Inside such a quoted
1665               string the actually used quote character can be used nonethe‐
1666               less by escaping it with a reverse solidus ‘\’, as in
1667               ‘"y\"ou"’.
1668
1669           An argument that is not enclosed in quotes, as above, can usu‐
1670               ally still contain space characters if those spaces are reverse
1671               solidus escaped, as in ‘you\ are’.
1672
1673           A reverse solidus outside of the enclosing quotes is discarded
1674               and the following character is treated literally as part of the
1675               argument.
1676
1677   Shell-style argument quoting
1678     sh(1)ell-style, and therefore POSIX standardized, argument parsing and
1679     quoting rules are used by most commands.  [v15 behaviour may differ] Most
1680     new commands only support these new rules and are flagged [Only new quot‐
1681     ing rules], some elder ones can use them with the command modifier wysh;
1682     in the future only this type of argument quoting will remain.
1683
1684     A command line is parsed from left to right and an input token is com‐
1685     pleted whenever an unquoted, otherwise ignored, metacharacter is seen.
1686     Metacharacters are vertical bar |, ampersand &, semicolon ;, as well as
1687     all characters from the variable ifs, and / or space, tabulator, newline.
1688     The additional metacharacters left and right parenthesis (, ) and less-
1689     than and greater-than signs <, > that the sh(1) supports are not used,
1690     and are treated as ordinary characters: for one these characters are a
1691     vivid part of email addresses, and it seems highly unlikely that their
1692     function will become meaningful to S-nail.
1693
1694           Compatibility  note:  [v15  behaviour  may differ] Please note that
1695           even many new-style commands do not yet honour ifs to  parse  their
1696           arguments:  whereas  the sh(1)ell is a language with syntactic ele‐
1697           ments of clearly defined  semantics,  S-nail  parses  entire  input
1698           lines and decides on a per-command base what to do with the rest of
1699           the line.  This also means that whenever an unknown command is seen
1700           all that S-nail can do is cancellation of the processing of the re‐
1701           mains of the line.
1702
1703           It also often depends on an actual subcommand of a multiplexer com‐
1704           mand  how  the rest of the line should be treated, and until v15 we
1705           are not capable to  perform  this  deep  inspection  of  arguments.
1706           Nonetheless,  at least the following commands which work with posi‐
1707           tional parameters fully support ifs for an almost  shell-compatible
1708           field splitting: call, call_if, read, vpospar, xcall.
1709
1710     Any unquoted number sign ‘#’ at the beginning of a new token starts a
1711     comment that extends to the end of the line, and therefore ends argument
1712     processing.  An unquoted dollar sign ‘$’ will cause variable expansion of
1713     the given name, which must be a valid sh(1)ell-style variable name (see
1714     vput): INTERNAL VARIABLES as well as ENVIRONMENT (shell) variables can be
1715     accessed through this mechanism, brace enclosing the name is supported
1716     (i.e., to subdivide a token).
1717
1718     Whereas the metacharacters space, tabulator, newline only complete an in‐
1719     put token, vertical bar |, ampersand & and semicolon ; also act as con‐
1720     trol operators and perform control functions.  For now supported is semi‐
1721     colon ;, which terminates a single command, therefore sequencing the com‐
1722     mand line and making the remainder of the line a subject to reevaluation.
1723     With sequencing, multiple command argument types and quoting rules may
1724     therefore apply to a single line, which can become problematic before
1725     v15: e.g., the first of the following will cause surprising results.
1726
1727           ? echo one; set verbose; echo verbose=$verbose.
1728           ? echo one; wysh set verbose; echo verbose=$verbose.
1729
1730     Quoting is a mechanism that will remove the special meaning of metachar‐
1731     acters and reserved words, and will prevent expansion.  There are four
1732     quoting mechanisms: the escape character, single-quotes, double-quotes
1733     and dollar-single-quotes:
1734
1735           The literal value of any character can be preserved by preced‐
1736               ing it with the escape character reverse solidus ‘\’.
1737
1738           Arguments which are enclosed in ‘'single-quotes'’ retain their
1739               literal value.  A single-quote cannot occur within single-
1740               quotes.
1741
1742           The literal value of all characters enclosed in ‘"double-
1743               quotes"’ is retained, with the exception of dollar sign ‘$’,
1744               which will cause variable expansion, as above, backquote (grave
1745               accent) ‘`’, (which not yet means anything special), reverse
1746               solidus ‘\’, which will escape any of the characters dollar
1747               sign ‘$’ (to prevent variable expansion), backquote (grave ac‐
1748               cent) ‘`’, double-quote ‘"’ (to prevent ending the quote) and
1749               reverse solidus ‘\’ (to prevent escaping, i.e., to embed a re‐
1750               verse solidus character as-is), but has no special meaning oth‐
1751               erwise.
1752
1753           Arguments enclosed in ‘$'dollar-single-quotes'’ extend normal
1754               single quotes in that reverse solidus escape sequences are ex‐
1755               panded as follows:
1756
1757               ‘\a’    bell control character (ASCII and ISO-10646 BEL).
1758               ‘\b’    backspace control character (ASCII and ISO-10646 BS).
1759               ‘\E’    escape control character (ASCII and ISO-10646 ESC).
1760               ‘\e’    the same.
1761               ‘\f’    form feed control character (ASCII and ISO-10646 FF).
1762               ‘\n’    line feed control character (ASCII and ISO-10646 LF).
1763               ‘\r’    carriage return control character (ASCII and ISO-10646
1764                       CR).
1765               ‘\t’    horizontal tabulator control character (ASCII and
1766                       ISO-10646 HT).
1767               ‘\v’    vertical tabulator control character (ASCII and
1768                       ISO-10646 VT).
1769               ‘\\’    emits a reverse solidus character.
1770               ‘\'’    single quote.
1771               ‘\"’    double quote (escaping is optional).
1772               ‘\NNN’  eight-bit byte with the octal value ‘NNN’ (one to three
1773                       octal digits), optionally prefixed by an additional
1774                       ‘0’.  A 0 byte will suppress further output for the
1775                       quoted argument.
1776               ‘\xHH’  eight-bit byte with the hexadecimal value ‘HH’ (one or
1777                       two hexadecimal characters, no prefix, see vexpr).  A 0
1778                       byte will suppress further output for the quoted argu‐
1779                       ment.
1780               ‘\UHHHHHHHH’
1781                       the Unicode / ISO-10646 character with the hexadecimal
1782                       codepoint value ‘HHHHHHHH’ (one to eight hexadecimal
1783                       characters) — note that Unicode defines the maximum
1784                       codepoint ever to be supported as ‘0x10FFFF’ (in planes
1785                       of ‘0xFFFF’ characters each).  This escape is only sup‐
1786                       ported in locales that support Unicode (see Character
1787                       sets), in other cases the sequence will remain unex‐
1788                       panded unless the given code point is ASCII compatible
1789                       or (if the [Option]al character set conversion is
1790                       available) can be represented in the current locale.
1791                       The character NUL will suppress further output for the
1792                       quoted argument.
1793               ‘\uHHHH’
1794                       Identical to ‘\UHHHHHHHH’ except it takes only one to
1795                       four hexadecimal characters.
1796               ‘\cX’   Emits the non-printable (ASCII and compatible) C0 con‐
1797                       trol codes 0 (NUL) to 31 (US), and 127 (DEL).  Print‐
1798                       able representations of ASCII control codes can be cre‐
1799                       ated by mapping them to a different, visible part of
1800                       the ASCII character set.  Adding the number 64 achieves
1801                       this for the codes 0 to 31, here 7 (BEL): ‘7 + 64 = 71
1802                       = G’.  The real operation is a bitwise logical XOR with
1803                       64 (bit 7 set, see vexpr), thus also covering code 127
1804                       (DEL), which is mapped to 63 (question mark):
1805                       ‘? vexpr ^ 127 64’.
1806
1807                       Whereas historically circumflex notation has often been
1808                       used for visualization purposes of control codes, as in
1809                       ‘^G’, the reverse solidus notation has been standard‐
1810                       ized: ‘\cG’.  Some control codes also have standardized
1811                       (ISO-10646, ISO C) aliases, as shown above (‘\a’, ‘\n’,
1812                       ‘\t’ etc) : whenever such an alias exists it will be
1813                       used for display purposes.  The control code NUL
1814                       (‘\c@’, a non-standard extension) will suppress further
1815                       output for the remains of the token (which may extend
1816                       beyond the current quote), or, depending on the con‐
1817                       text, the remains of all arguments for the current com‐
1818                       mand.
1819               ‘\$NAME’
1820                       Non-standard extension: expand the given variable name,
1821                       as above.  Brace enclosing the name is supported.
1822               ‘\`{command}’
1823                       Not yet supported, just to raise awareness: Non-stan‐
1824                       dard extension.
1825
1826     Caveats:
1827
1828           ? echo 'Quotes '${HOME}' and 'tokens" differ!"# no comment
1829           ? echo Quotes ${HOME} and tokens differ! # comment
1830           ? echo Don"'"t you worry$'\x21' The sun shines on us. $'\u263A'
1831
1832   Message list arguments
1833     Many commands operate on message list specifications, as documented in
1834     Specifying messages.  The argument input is first split into individual
1835     tokens via Shell-style argument quoting, which are then interpreted as
1836     the mentioned specifications.  If no explicit message list has been spec‐
1837     ified, many commands will search for and use the next message forward
1838     that satisfies the commands' requirements, and if there are no messages
1839     forward of the current message, the search proceeds backwards; if there
1840     are no good messages at all to be found, an error message is shown and
1841     the command is aborted.  The verbose output of the command list will in‐
1842     dicate whether a command searches for a default message, or not.
1843
1844   Raw data arguments for codec commands
1845     A special set of commands, which all have the string “codec” in their
1846     name, like addrcodec, shcodec, urlcodec, take raw string data as input,
1847     which means that the content of the command input line is passed com‐
1848     pletely unexpanded and otherwise unchanged: like this the effect of the
1849     actual codec is visible without any noise of possible shell quoting rules
1850     etc., i.e., the user can input one-to-one the desired or questionable
1851     data.  To gain a level of expansion, the entire command line can be
1852     evaluated first, for example
1853
1854           ? vput shcodec res encode /usr/Schönes Wetter/heute.txt
1855           ? echo $res
1856           $'/usr/Sch\u00F6nes Wetter/heute.txt'
1857           ? shcodec d $res
1858           $'/usr/Sch\u00F6nes Wetter/heute.txt'
1859           ? eval shcodec d $res
1860           /usr/Schönes Wetter/heute.txt
1861
1862   Filename transformations
1863     Filenames, where expected, and unless documented otherwise, are subse‐
1864     quently subject to the following filename transformations, in sequence:
1865
1866           If the given name is a registered shortcut, it will be replaced
1867               with the expanded shortcut.  This step is mostly taken for
1868               folders only.
1869
1870           The filename is matched against the following patterns or
1871               strings.  But for plus +file folder expansion this step is
1872               mostly taken for folders only.
1873
1874               #      (Number sign) is expanded to the previous file.
1875               %      (Percent sign) is replaced by the invoking user's pri‐
1876                      mary system mailbox, which either is the (itself expand‐
1877                      able) inbox if that is set, the standardized absolute
1878                      pathname indicated by MAIL if that is set, or a built-in
1879                      compile-time default otherwise.  When opening a folder
1880                      the used name is actively checked for being a primary
1881                      mailbox, first against inbox, then against MAIL.
1882               %user  Expands to the primary system mailbox of user (and never
1883                      the value of inbox, regardless of its actual setting).
1884               &      (Ampersand) is replaced with the invoking user's sec‐
1885                      ondary mailbox, the MBOX.
1886               +file  Refers to a file in the folder directory (if that vari‐
1887                      able is set).
1888               %:filespec Expands to the same value as filespec, but has spe‐
1889                      cial meaning when used with, for example, the command
1890                      folder: the file will be treated as a primary system
1891                      mailbox by, among others, the mbox and save commands,
1892                      meaning that messages that have been read in the current
1893                      session will be moved to the MBOX mailbox instead of
1894                      simply being flagged as read.
1895
1896           Meta expansions may be applied to the resulting filename, as
1897               allowed by the operation and applicable to the resulting access
1898               protocol (also see On URL syntax and credential lookup).  For
1899               the file-protocol, a leading tilde ‘~’ character will be re‐
1900               placed by the expansion of HOME, except when followed by a
1901               valid user name, in which case the home directory of the given
1902               user is used instead.
1903
1904               A shell expansion as if specified in double-quotes (see
1905               Shell-style argument quoting) may be applied, so that any oc‐
1906               currence of ‘$VARIABLE’ (or ‘${VARIABLE}’) will be replaced by
1907               the expansion of the variable, if possible; INTERNAL VARIABLES
1908               as well as ENVIRONMENT (shell) variables can be accessed
1909               through this mechanism.
1910
1911               Shell pathname wildcard pattern expansions (glob(7)) may be ap‐
1912               plied as documented.  If the fully expanded filename results in
1913               multiple pathnames and the command is expecting only one file,
1914               an error results.
1915
1916               In interactive context, in order to allow simple value accep‐
1917               tance (via “ENTER”), arguments will usually be displayed in a
1918               properly quoted form, so a file ‘diet\ is \curd.txt’ may be
1919               displayed as ‘'diet\ is \curd.txt'’.
1920
1921   Commands
1922     The following commands are available:
1923
1924     !         Executes the SHELL command which follows, replacing unescaped
1925               exclamation marks with the previously executed command if the
1926               internal variable bang is set.  This command supports vput as
1927               documented in Command modifiers, and manages the error number
1928               !.  A 0 or positive exit status ? reflects the exit status of
1929               the command, negative ones that an error happened before the
1930               command was executed, or that the program did not exit cleanly,
1931               but maybe due to a signal: the error number is ^ERR-CHILD,
1932               then.
1933
1934               In conjunction with the vput modifier the following special
1935               cases exist: a negative exit status occurs if the collected
1936               data could not be stored in the given variable, which is a
1937               ^ERR-NOTSUP error that should otherwise not occur.
1938               ^ERR-CANCELED indicates that no temporary file could be created
1939               to collect the command output at first glance.  In case of
1940               catchable out-of-memory situations ^ERR-NOMEM will occur and
1941               S-nail will try to store the empty string, just like with all
1942               other detected error conditions.
1943
1944     #         The comment-command causes the entire line to be ignored.
1945               Note: this really is a normal command which' purpose is to dis‐
1946               card its arguments, not a “comment-start” indicating special
1947               character, which means that for example trailing comments on a
1948               line are not possible (except for commands which use
1949               Shell-style argument quoting).
1950
1951     +         Goes to the next message in sequence and types it (like
1952               “ENTER”).
1953
1954     -         Display the preceding message, or the n'th previous message if
1955               given a numeric argument n.
1956
1957     =         Shows the message number of the current message (the “dot”)
1958               when used without arguments, that of the given list otherwise.
1959               Output numbers will be separated from each other with the first
1960               character of ifs, and followed by the first character of if-ws,
1961               if that is not empty and not identical to the first.  If that
1962               results in no separation at all a space character is used.
1963               This command supports vput (see Command modifiers), and manages
1964               the error number !.
1965
1966     ?         [Option] Show a brief summary of commands.  [Option] Given an
1967               argument a synopsis for the command in question is shown in‐
1968               stead; commands can be abbreviated in general and this command
1969               can be used to see the full expansion of an abbreviation in‐
1970               cluding the synopsis, try, for example ‘?h’, ‘?hel’ and ‘?help’
1971               and see how the output changes.  To avoid that aliases are re‐
1972               solved the modifier \ can be prepended to the argument, but
1973               note it must be quoted.  This mode also supports a more verbose
1974               output, which will provide the information documented for list.
1975
1976     |         A synonym for the pipe command.
1977
1978     account, unaccount
1979               (ac, una) Creates, selects or lists (an) account(s).  Accounts
1980               are special incarnations of defined macros and group commands
1981               and variable settings which together usually arrange the envi‐
1982               ronment for the purpose of creating an email account.  Differ‐
1983               ent to normal macros settings which are covered by localopts 
1984               here by default enabled! – will not be reverted before the
1985               account is changed again.  The special account ‘null’ (case-in‐
1986               sensitive) always exists, and all but it can be deleted by the
1987               latter command, and in one operation with the special name ‘*’.
1988               Also for all but it a possibly set on-account-cleanup hook is
1989               called once they are left, also for program exit.
1990
1991               Without arguments a listing of all defined accounts is shown.
1992               With one argument the given account is activated: the system
1993               inbox of that account will be activated (as via folder), a pos‐
1994               sibly installed folder-hook will be run, and the internal vari‐
1995               able account will be updated.  The two argument form behaves
1996               identical to defining a macro as via define.  Important set‐
1997               tings for accounts include folder, from, hostname, inbox, mta,
1998               password and user (On URL syntax and credential lookup), as
1999               well as things like tls-config-pairs (Encrypted network
2000               communication), and protocol specifics like imap-auth,
2001               pop3-auth, smtp-auth.
2002
2003                     account myisp {
2004                       set folder=~/mail inbox=+syste.mbox record=+sent.mbox
2005                       set from='(My Name) myname@myisp.example'
2006                       set mta=smtp://mylogin@smtp.myisp.example
2007                     }
2008
2009     addrcodec
2010               Perform email address codec transformations on raw-data argu‐
2011               ment, rather according to email standards (RFC 5322; [v15 be‐
2012               haviour may differ] will furtherly improve).  Supports vput
2013               (see Command modifiers), and manages the error number !.  The
2014               first argument must be either [+[+[+]]]e[ncode], d[ecode],
2015               s[kin] or skinl[ist] and specifies the operation to perform on
2016               the rest of the line.
2017
2018               Decoding will show how a standard-compliant MUA will display
2019               the given argument, which should be an email address.  Please
2020               be aware that most MUAs have difficulties with the address
2021               standards, and vary wildly when (comments) in parenthesis,
2022               “double-quoted” strings, or quoted-pairs, as below, become in‐
2023               volved.  [v15 behaviour may differ] S-nail currently does not
2024               perform decoding when displaying addresses.
2025
2026               Skinning is identical to decoding but only outputs the plain
2027               address, without any string, comment etc. components.  Another
2028               difference is that it may fail with the error number ! set to
2029               ^ERR-INVAL if decoding fails to find a(n) (valid) email ad‐
2030               dress, in which case the unmodified input will be output again.
2031
2032               skinlist first performs a skin operation, and thereafter checks
2033               a valid address for whether it is a registered mailing list
2034               (see mlist and mlsubscribe), eventually reporting that state in
2035               the error number ! as ^ERR-EXIST.  (This state could later be‐
2036               come overwritten by an I/O error, though.)
2037
2038               Encoding supports four different modes, lesser automated ver‐
2039               sions can be chosen by prefixing one, two or three plus signs:
2040               the standard imposes a special meaning on some characters,
2041               which thus have to be transformed to so-called quoted-pairs by
2042               pairing them with a reverse solidus ‘\’ in order to remove the
2043               special meaning; this might change interpretation of the entire
2044               argument from what has been desired, however!  Specify one plus
2045               sign to remark that parenthesis shall be left alone, two for
2046               not turning double quotation marks into quoted-pairs, and three
2047               for also leaving any user-specified reverse solidus alone.  The
2048               result will always be valid, if a successful exit status is re‐
2049               ported ([v15 behaviour may differ] the current parser fails
2050               this assertion for some constructs).  [v15 behaviour may dif‐
2051               fer] Addresses need to be specified in between angle brackets
2052               ‘<’, ‘>’ if the construct becomes more difficult, otherwise the
2053               current parser will fail; it is not smart enough to guess
2054               right.
2055
2056                     ? addrc enc "Hey, you",<diet@exam.ple>\ out\ there
2057                     "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2058                     ? addrc d "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2059                     "Hey, you", \ out\ there <diet@exam.ple>
2060                     ? addrc s "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2061                     diet@exam.ple
2062
2063     alias, unalias
2064               [Only new quoting rules](a, una) Define or list, and remove,
2065               respectively, address aliases, which are a method of creating
2066               personal distribution lists that map a single name to none to
2067               multiple receivers, to be expanded after Compose mode is left;
2068               the expansion correlates with metoo.  The latter command re‐
2069               moves all given aliases, the special name asterisk ‘*’ will re‐
2070               move all existing aliases.  When used without arguments the
2071               former shows a list of all currently known aliases, with one
2072               argument only the target(s) of the given one.  When given two
2073               arguments, hyphen-minus ‘-’ being the first, the target(s) of
2074               the second is/are expanded recursively.
2075
2076               In all other cases the given alias is newly defined, or will be
2077               appended to: arguments must either be themselves valid alias
2078               names, or any other address type (see On sending mail, and non-
2079               interactive mode).  Recursive expansion of aliases can be pre‐
2080               vented by prefixing the desired argument with the modifier re‐
2081               verse solidus \.  A valid alias name conforms to mta-aliases
2082               syntax, but follow-up characters can also be the number sign
2083               ‘#’, colon ‘:’, commercial at ‘@,’ exclamation mark ‘!’, period
2084               ‘.’ as well as “any character that has the high bit set”.  The
2085               dollar sign ‘$’ may be the last character.  The number sign ‘#’
2086               may need Shell-style argument quoting.
2087
2088               [v15 behaviour may differ] Unfortunately the colon is currently
2089               not supported, as it interferes with normal address parsing
2090               rules.  [v15 behaviour may differ] Such high bit characters
2091               will likely cause warnings at the moment for the same reasons
2092               why colon is unsupported; also, in the future locale dependent
2093               character set validity checks will be performed.
2094
2095                     ? alias cohorts  bill jkf mark kridle@ucbcory ~/cohorts.mbox
2096                     ? alias mark  mark@exam.ple
2097                     ? set mta-aliases=/etc/aliases
2098
2099     alternates, unalternates
2100               [Only new quoting rules] (alt) Manage a list of alternate ad‐
2101               dresses or names of the active user, members of which will be
2102               removed from recipient lists (except one).  There is a set of
2103               implicit alternates which is formed of the values of LOGNAME,
2104               from, sender and reply-to.  from will not be used if sender is
2105               set.  The latter command removes the given list of alternates,
2106               the special name ‘*’ will discard all existing alternate names.
2107
2108               The former command manages the error number !.  It shows the
2109               current set of alternates when used without arguments; in this
2110               mode only it also supports vput (see Command modifiers).  Oth‐
2111               erwise the given arguments (after being checked for validity)
2112               are appended to the list of alternate names; in posix mode they
2113               replace that list instead.
2114
2115     answered, unanswered
2116               Take a message lists and mark each message as (not) having been
2117               answered.  Messages will be marked answered when being replyd
2118               to automatically if the markanswered variable is set.  See the
2119               section Message states.
2120
2121     bind, unbind
2122               [Option][Only new quoting rules] The bind command extends the
2123               MLE (see On terminal control and line editor) with freely con‐
2124               figurable key bindings.  The latter command removes from the
2125               given context the given key binding, both of which may be spec‐
2126               ified as a wildcard ‘*’, so that ‘unbind * *’ will remove all
2127               bindings of all contexts.  Due to initialization order unbind‐
2128               ing will not work for built-in key bindings upon program
2129               startup, however: please use line-editor-no-defaults for this
2130               purpose instead.
2131
2132               With zero arguments, or with a context name the former command
2133               shows all key bindings (of the given context; an asterisk ‘*’
2134               will iterate over all contexts); a more verbose listing will be
2135               produced if either of debug or verbose are set.  With two or
2136               more arguments a specific binding is shown, or (re)established:
2137               the first argument is the context to which the binding shall
2138               apply, the second argument is a comma-separated list of the
2139               “keys” which form the binding.  Further arguments will be
2140               joined to form the expansion, and cause the binding to be cre‐
2141               ated or updated.  To indicate that a binding shall not be auto-
2142               committed, but that the expansion shall instead be furtherly
2143               editable by the user, a commercial at ‘@’ (that will be re‐
2144               moved) can be placed last in the expansion, from which leading
2145               and trailing whitespace will finally be removed.  Reverse
2146               solidus cannot be used as the last character of expansion.  An
2147               empty expansion will be rejected.
2148
2149               Contexts define when a binding applies, i.e., a binding will
2150               not be seen unless the context for which it is defined for is
2151               currently active.  This is not true for the shared binding
2152               ‘base’, which is the foundation for all other bindings and as
2153               such always applies, its bindings, however, only apply secon‐
2154               darily.  The available contexts are the shared ‘base’, the
2155               ‘default’ context which is used in all not otherwise documented
2156               situations, and ‘compose’, which applies only to Compose mode.
2157
2158               Bindings are specified as a comma-separated list of byte-se‐
2159               quences, where each list entry corresponds to one “key”
2160               (press).  Byte sequence boundaries will be forcefully termi‐
2161               nated after bind-inter-byte-timeout milliseconds, whereas key
2162               sequences can be timed out via bind-inter-key-timeout.  A list
2163               entry may, indicated by a leading colon character ‘:’, also re‐
2164               fer to the name of a terminal capability; several dozen names
2165               are compiled in and may be specified either by their
2166               terminfo(5), or, if existing, by their termcap(5) name, regard‐
2167               less of the actually used [Option]al terminal control library.
2168               But any capability may be used, as long as the name is resolv‐
2169               able by the [Option]al control library, or was defined via the
2170               internal variable termcap.  Input sequences are not case-nor‐
2171               malized, an exact match is required to update or remove a bind‐
2172               ing.  It is advisable to use an initial escape or other control
2173               character (like ‘\cA’) for user (as opposed to purely terminal
2174               capability based) bindings in order to avoid ambiguities; it
2175               also reduces search time.  Examples:
2176
2177                     ? bind base a,b echo one
2178                     ? bind base $'\E',d mle-snarf-word-fwd # Esc(ape)
2179                     ? bind base $'\E',$'\c?' mle-snarf-word-bwd # Esc,Delete
2180                     ? bind default $'\cA',:khome,w 'echo Editable binding@'
2181                     ? bind default a,b,c rm -irf / @  # Also editable
2182                     ? bind default :kf1 File %
2183                     ? bind compose :kf1 ~v
2184
2185               Note that the entire comma-separated list is first parsed
2186               (over) as a shell-token with whitespace as the field separator,
2187               then parsed and expanded for real with comma as the field sepa‐
2188               rator, therefore whitespace needs to be properly quoted, see
2189               Shell-style argument quoting.  Using Unicode reverse solidus
2190               escape sequences renders a binding defunctional if the locale
2191               does not support Unicode (see Character sets), and using termi‐
2192               nal capabilities does so if no (corresponding) terminal control
2193               support is (currently) available.  Adding, deleting or modify‐
2194               ing a key binding invalidates the internal prebuilt lookup
2195               tree, it will be recreated as necessary: this process will be
2196               visualized in most verbose as well as in debug mode.
2197
2198               The following terminal capability names are built-in and can be
2199               used in terminfo(5) or (if available) the two-letter termcap(5)
2200               notation.  See the respective manual for a list of capabili‐
2201               ties.  The program infocmp(1) can be used to show all the capa‐
2202               bilities of TERM or the given terminal type; using the -x flag
2203               will also show supported (non-standard) extensions.
2204
2205               kbs or kb       Backspace.
2206               kdch1 or kD     Delete character.
2207               kDC or *4       — shifted variant.
2208               kel or kE       Clear to end of line.
2209               kext or @9      Exit.
2210               kich1 or kI     Insert character.
2211               kIC or #3       — shifted variant.
2212               khome or kh     Home.
2213               kHOM or #2      — shifted variant.
2214               kend or @7      End.
2215               knp or kN       Next page.
2216               kpp or kP       Previous page.
2217               kcub1 or kl     Left cursor (with more modifiers: see below).
2218               kLFT or #4      — shifted variant.
2219               kcuf1 or kr     Right cursor (ditto).
2220               kRIT or %i      — shifted variant.
2221               kcud1 or kd     Down cursor (ditto).
2222               kDN             — shifted variant (only terminfo).
2223               kcuu1 or ku     Up cursor (ditto).
2224               kUP             — shifted variant (only terminfo).
2225               kf0 or k0       Function key 0.  Add one for each function key
2226                               up to kf9 and k9, respectively.
2227               kf10 or k;      Function key 10.
2228               kf11 or F1      Function key 11.  Add one for each function key
2229                               up to kf19 and F9, respectively.
2230
2231               Some terminals support key-modifier combination extensions,
2232               e.g., ‘Alt+Shift+xy’.  For example, the delete key, kdch1: in
2233               its shifted variant, the name is mutated to kDC, then a number
2234               is appended for the states ‘Alt’ (kDC3), ‘Shift+Alt’ (kDC4),
2235               ‘Control’ (kDC5), ‘Shift+Control’ (kDC6), ‘Alt+Control’ (kDC7),
2236               finally ‘Shift+Alt+Control’ (kDC8).  The same for the left cur‐
2237               sor key, kcub1: KLFT, KLFT3, KLFT4, KLFT5, KLFT6, KLFT7, KLFT8.
2238
2239     call      [Only new quoting rules] Calls the given macro, which must have
2240               been created via define (see there for more), otherwise an
2241               ^ERR-NOENT error occurs.  Calling macros recursively will at
2242               some time excess the stack size limit, causing a hard program
2243               abortion; if recursively calling a macro is the last command of
2244               the current macro, consider to use the command xcall, which
2245               will first release all resources of the current macro before
2246               replacing the current macro with the called one.
2247
2248     call_if   Identical to call if the given macro has been created via
2249               define, but does not fail nor warn if the macro does not exist.
2250
2251     cd        Synonym for chdir.
2252
2253     certsave  [Option] Only applicable to S/MIME signed messages.  Takes an
2254               optional message list and a filename and saves the certificates
2255               contained within the message signatures to the named file in
2256               both human-readable and PEM format.  The certificates can later
2257               be used to send encrypted messages to the respective message
2258               senders by setting smime-encrypt-USER@HOST variables.
2259
2260     charsetalias, uncharsetalias
2261               [Only new quoting rules] Manage alias mappings for (conversion
2262               of) Character sets.  Alias processing is not performed for
2263               INTERNAL VARIABLES, for example charset-8bit, and mappings are
2264               ineffective if character set conversion is not available
2265               (features does not announce ‘,+iconv,’).  Expansion happens re‐
2266               cursively for cases where aliases point to other aliases
2267               (built-in loop limit: 8).
2268
2269               The latter command deletes all aliases given as arguments, or
2270               all at once when given the asterisk ‘*’.  The former shows the
2271               list of all currently defined aliases if used without argu‐
2272               ments, or the target of the given single argument; when given
2273               two arguments, hyphen-minus ‘-’ being the first, the second is
2274               instead expanded recursively.  In all other cases the given ar‐
2275               guments are treated as pairs of character sets and their de‐
2276               sired target alias name, creating new or updating already ex‐
2277               isting aliases.
2278
2279     chdir     [Only new quoting rules](ch) Change the working directory to
2280               HOME or the given argument.  Synonym for cd.
2281
2282     collapse, uncollapse
2283               Only applicable to ‘thread’ed sort mode.  Takes a message list
2284               and makes all replies to these messages invisible in header
2285               summaries, except for ‘new’ messages and the “dot”.  Also when
2286               a message with collapsed replies is displayed, all of these are
2287               automatically uncollapsed.  The latter command undoes collaps‐
2288               ing.
2289
2290     colour, uncolour
2291               [Option][Only new quoting rules] Manage colour mappings of and
2292               for a Coloured display.  Without arguments the former shows all
2293               currently defined mappings.  Otherwise a colour type is ex‐
2294               pected (case-insensitively), it must be one of ‘256’ for
2295               256-colour terminals, ‘8’, ‘ansi’ or ‘iso’ for the standard
2296               8-colour ANSI / ISO 6429 colour palette, and ‘1’ or ‘mono’ for
2297               monochrome terminals, which only support (some) font at‐
2298               tributes.  Without further arguments the list of all currently
2299               defined mappings of the given type is shown (here the special
2300               ‘all’ or ‘*’ also show all currently defined mappings).
2301
2302               Otherwise the second argument defines the mappable slot, the
2303               third argument a (comma-separated list of) colour and font at‐
2304               tribute specification(s), and the optionally supported fourth
2305               argument can be used to specify a precondition: if conditioned
2306               mappings exist they are tested in (creation) order unless a
2307               (case-insensitive) match has been found, and the default map‐
2308               ping (if any has been established) will only be chosen as a
2309               last resort.  The types of available preconditions depend on
2310               the mappable slot, the following of which exist:
2311
2312               Mappings prefixed with ‘mle-’ are used for the [Option]al
2313               built-in Mailx-Line-Editor (MLE, see On terminal control and
2314               line editor) and do not support preconditions.
2315
2316               mle-position   This mapping is used for the position indicator
2317                              that is visible when a line cannot be fully dis‐
2318                              played on the screen.
2319               mle-prompt     Used for the prompt.
2320               mle-error      Used for the occasionally appearing error indi‐
2321                              cator that is joined onto prompt.  [v15 behav‐
2322                              iour may differ] Also used for error messages
2323                              written on standard error .
2324
2325               Mappings prefixed with ‘sum-’ are used in header summaries, and
2326               they all understand the preconditions ‘dot’ (the current mes‐
2327               sage) and ‘older’ for elder messages (only honoured in conjunc‐
2328               tion with datefield-markout-older).
2329
2330               sum-dotmark    This mapping is used for the “dotmark” that can
2331                              be created with the ‘%>’ or ‘%<’ formats of the
2332                              variable headline.
2333               sum-header     For the complete header summary line except the
2334                              “dotmark” and the thread structure.
2335               sum-thread     For the thread structure which can be created
2336                              with the ‘%i’ format of the variable headline.
2337
2338               Mappings prefixed with ‘view-’ are used when displaying mes‐
2339               sages.
2340
2341               view-from_     This mapping is used for so-called ‘From_’
2342                              lines, which are MBOX file format specific
2343                              header lines (also see mbox-rfc4155).
2344               view-header    For header lines.  A comma-separated list of
2345                              headers to which the mapping applies may be
2346                              given as a precondition; if the [Option]al regu‐
2347                              lar expression support is available then if any
2348                              of the magic regular expression characters is
2349                              seen the precondition will be evaluated as (an
2350                              extended) one.
2351               view-msginfo   For the introductional message info line.
2352               view-partinfo  For MIME part info lines.
2353
2354               The following (case-insensitive) colour definitions and font
2355               attributes are understood, multiple of which can be specified
2356               in a comma-separated list:
2357
2358               ft=  a font attribute: ‘bold’, ‘reverse’ or ‘underline’.  It is
2359                    possible (and often applicable) to specify multiple font
2360                    attributes for a single mapping.
2361
2362               fg=  foreground colour attribute, in order (numbers 0 - 7)
2363                    ‘black’, ‘red’, ‘green’, ‘brown’, ‘blue’, ‘magenta’,
2364                    ‘cyan’ or ‘white’.  To specify a 256-colour mode a decimal
2365                    number colour specification in the range 0 to 255, inclu‐
2366                    sive, is supported, and interpreted as follows:
2367
2368                    0 - 7      the standard ISO 6429 colours, as above.
2369                    8 - 15     high intensity variants of the standard
2370                               colours.
2371                    16 - 231   216 colours in tuples of 6.
2372                    232 - 255  grayscale from black to white in 24 steps.
2373
2374                          #!/bin/sh -
2375                          fg() { printf "\033[38;5;${1}m($1)"; }
2376                          bg() { printf "\033[48;5;${1}m($1)"; }
2377                          i=0
2378                          while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
2379                          printf "\033[0m\n"
2380                          i=0
2381                          while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
2382                          printf "\033[0m\n"
2383
2384               bg=  background colour attribute (see fg= for possible values).
2385
2386               The command uncolour will remove for the given colour type (the
2387               special type ‘*’ selects all) the given mapping; if the op‐
2388               tional precondition argument is given only the exact tuple of
2389               mapping and precondition is removed.  The special name ‘*’ will
2390               remove all mappings (no precondition allowed), thus ‘uncolour *
2391               *’ will remove all established mappings.
2392
2393     commandalias, uncommandalias
2394               [Only new quoting rules] Define or list, and remove, respec‐
2395               tively, command aliases.  An (command)alias can be used every‐
2396               where a normal command can be used, but always takes prece‐
2397               dence: any arguments that are given to the command alias are
2398               joined onto the alias expansion, and the resulting string forms
2399               the command line that is, in effect, executed.  The latter com‐
2400               mand removes all given aliases, the special name asterisk ‘*’
2401               will remove all existing aliases.  When used without arguments
2402               the former shows a list of all currently known aliases, with
2403               one argument only the expansion of the given one.
2404
2405               With two or more arguments a command alias is defined or up‐
2406               dated: the first argument is the name under which the remaining
2407               command line should be accessible, the content of which can be
2408               just about anything.  An alias may itself expand to another
2409               alias, but to avoid expansion loops further expansion will be
2410               prevented if an alias refers to itself or if an expansion depth
2411               limit is reached.  Explicit expansion prevention is available
2412               via reverse solidus \, one of the Command modifiers.
2413
2414                     ? commandalias xx
2415                     s-nail: `commandalias': no such alias: xx
2416                     ? commandalias xx echo hello,
2417                     ? commandalias xx
2418                     commandalias xx 'echo hello,'
2419                     ? xx
2420                     hello,
2421                     ? xx world
2422                     hello, world
2423
2424     Copy      (C) Similar to copy, but copy the messages to a file named af‐
2425               ter the local part of the sender of the first message instead
2426               of taking a filename argument; outfolder is inspected to decide
2427               on the actual storage location.
2428
2429     copy      (c) Copy messages to the named file and do not mark them as be‐
2430               ing saved; otherwise identical to save.
2431
2432     csop      [Only new quoting rules] A multiplexer command which provides
2433               C-style string operations on 8-bit bytes without a notion of
2434               locale settings and character sets, effectively assuming ASCII
2435               data.  For numeric and other operations refer to vexpr.  vput,
2436               one of the Command modifiers, is supported.  The error result
2437               is ‘-1’ for usage errors and numeric results, the empty string
2438               otherwise; missing data errors, as for unsuccessful searches,
2439               result in the ! error number being set to ^ERR-NODATA.  Where
2440               the question mark ‘?’ modifier suffix is supported, a case-in‐
2441               sensitive (ASCII mapping) operation mode is supported; the key‐
2442               word ‘case’ is optional so that ‘find?’ and ‘find?case’ are
2443               identical.
2444
2445               length    Queries the length of the given argument.
2446
2447               hash, hash32 Calculates a hash value of the given argument.
2448                         The latter will return a 32-bit result regardless of
2449                         host environment.  ‘?’ modifier suffix is supported.
2450                         These use Chris Torek's hash algorithm, the resulting
2451                         hash value is bit mixed as shown by Bret Mulvey.
2452
2453               find      Search for the second in the first argument.  Shows
2454                         the resulting 0-based offset shall it have been
2455                         found.  ‘?’ modifier suffix is supported.
2456
2457               substring Creates a substring of its first argument.  The op‐
2458                         tional second argument is the 0-based starting off‐
2459                         set, a negative one counts from the end; the optional
2460                         third argument specifies the length of the desired
2461                         result, a negative length leaves off the given number
2462                         of bytes at the end of the original string; by de‐
2463                         fault the entire string is used.  This operation
2464                         tries to work around faulty arguments (set verbose
2465                         for error logs), but reports them via the error num‐
2466                         ber ! as ^ERR-OVERFLOW.
2467
2468               trim      Trim away whitespace characters from both ends of the
2469                         argument.
2470
2471               trim-front Trim away whitespace characters from the begin of
2472                         the argument.
2473
2474               trim-end  Trim away whitespace characters from the end of the
2475                         argument.
2476
2477     cwd       Show the name of the current working directory, as reported by
2478               getcwd(3).  Supports vput (see Command modifiers).  The return
2479               status is tracked via ?.
2480
2481     Decrypt   [Option] For unencrypted messages this command is identical to
2482               Copy; Encrypted messages are first decrypted, if possible, and
2483               then copied.
2484
2485     decrypt   [Option] For unencrypted messages this command is identical to
2486               copy; Encrypted messages are first decrypted, if possible, and
2487               then copied.
2488
2489     define, undefine
2490               The latter command deletes the given macro, the special name
2491               ‘*’ will discard all existing macros.  Deletion of (a) macro(s)
2492               can be performed from within running (a) macro(s), including
2493               self-deletion.  Without arguments the former command prints the
2494               current list of macros, including their content, otherwise it
2495               defines a macro, replacing an existing one of the same name as
2496               applicable.
2497
2498               A defined macro can be invoked explicitly by using the call,
2499               call_if and xcall commands, or implicitly if a macro hook is
2500               triggered, for example a folder-hook.  Execution of a macro
2501               body can be stopped from within by calling return.
2502
2503               Temporary macro block-scope variables can be created or deleted
2504               with the local command modifier in conjunction with the com‐
2505               mands set and unset, respectively.  To enforce unrolling of
2506               changes made to (global) INTERNAL VARIABLES the command
2507               localopts can be used instead; its covered scope depends on how
2508               (i.e., “as what”: normal macro, folder hook, hook, account
2509               switch) the macro is invoked.
2510
2511               Inside a called macro, the given positional parameters are im‐
2512               plicitly local to the macro's scope, and may be accessed via
2513               the variables *, @, # and 1 and any other positive unsigned
2514               decimal number less than or equal to #.  Positional parameters
2515               can be shifted, or become completely replaced, removed etc. via
2516               vpospar.  A helpful command for numeric computation and string
2517               evaluations is vexpr, csop offers C-style byte string opera‐
2518               tions.
2519
2520                     define name {
2521                       command1
2522                       command2
2523                       ...
2524                       commandN
2525                     }
2526
2527                     define exmac {
2528                       echo Parameter 1 of ${#} is ${1}, all: ${*} / ${@}
2529                       return 1000 0
2530                     }
2531                     call exmac Hello macro exmac!
2532                     echo ${?}/${!}/${^ERRNAME}
2533
2534     delete, undelete
2535               (d, u) Marks the given message list as being or not being
2536               ‘deleted’, respectively; if no argument has been specified then
2537               the usual search for a visible message is performed, as docu‐
2538               mented for Message list arguments, showing only the next input
2539               prompt if the search fails.  Deleted messages will neither be
2540               saved in the secondary mailbox MBOX nor will they be available
2541               for most other commands.  If the autoprint variable is set, the
2542               new “dot” or the last message restored, respectively, is auto‐
2543               matically typed; also see dp, dt.
2544
2545     digmsg    [Only new quoting rules] Digging (information out of) messages
2546               is possible through digmsg objects, which can be created for
2547               the given message number; in Compose mode the hyphen-minus ‘-’
2548               will instead open the message that is being composed.  If a hy‐
2549               phen-minus is given as the optional third argument then output
2550               will be generated on the standard output channel instead of be‐
2551               ing subject to consumption by the readall (or read and readsh)
2552               command(s).  Note: output must be consumed before normal pro‐
2553               cessing can continue; for digmsg objects this means each com‐
2554               mand output has to be read until the end of file (EOF) state
2555               occurs.
2556
2557               The objects may be removed again by giving the same identifier
2558               used for creation; this step could be omitted: objects will be
2559               automatically closed when the active folder (mailbox) or the
2560               compose mode is left, respectively.  In all other use cases the
2561               second argument is an object identifier, and the third and all
2562               following arguments are interpreted as via ~^ (see COMMAND
2563               ESCAPES):
2564
2565                     ? vput = msgno; digmsg create $msgno
2566                     ? digmsg $msgno header list;   readall x;   echon $x
2567                     210 Subject From To Message-ID References In-Reply-To
2568                     ? digmsg $msgno header show Subject;readall x;echon $x
2569                     212 Subject
2570                     'Hello, world'
2571
2572                     ? digmsg remove $msgno
2573
2574     discard   (di) Identical to ignore.  Superseded by the multiplexer
2575               headerpick.
2576
2577     dp, dt    Delete the given messages and automatically type the new “dot”
2578               if one exists, regardless of the setting of autoprint.
2579
2580     dotmove   Move the “dot” up or down by one message when given ‘+’ or ‘-’
2581               argument, respectively.
2582
2583     draft, undraft
2584               Take message lists and mark each given message as being draft,
2585               or not being draft, respectively, as documented in the section
2586               Message states.
2587
2588     echo      [Only new quoting rules](ec) Print the given strings, equiva‐
2589               lent to the shell utility echo(1), that is, Shell-style
2590               argument quoting expansion is performed and, different to the
2591               otherwise identical echon, a trailing newline is echoed.  vput
2592               as documented in Command modifiers is supported, and the error
2593               number ! is managed: if data is stored in a variable then the
2594               return value reflects the length of the result string in case
2595               of success and is ‘-1’ on error.
2596
2597               Remarks: this command traditionally (in BSD Mail) also per‐
2598               formed Filename transformations, which is standard incompatible
2599               and hard to handle because quoting transformation patterns is
2600               not possible; the subcommand file-expand of vexpr can be used
2601               to expand filenames.
2602
2603     echoerr   [Only new quoting rules] Identical to echo, but the message is
2604               written to standard error, and prefixed by log-prefix.  Also
2605               see echoerrn.  In interactive sessions the [Option]al message
2606               ring queue for errors will be used instead, if available and
2607               vput was not used.
2608
2609     echon     [Only new quoting rules] Identical to echo, but does not write
2610               or store a trailing newline.
2611
2612     echoerrn  [Only new quoting rules] Identical to echoerr, but does not
2613               write or store a trailing newline.
2614
2615     edit      (e) Point the text EDITOR at each message from the given list
2616               in turn.  Modified contents are discarded unless the
2617               writebackedited variable is set, and are not used unless the
2618               mailbox can be written to and the editor returns a successful
2619               exit status.  visual can be used instead for a more display
2620               oriented editor.
2621
2622     elif      Part of the if (see there for more), elif, else, endif condi‐
2623               tional — if the condition of a preceding if was false, check
2624               the following condition and execute the following block if it
2625               evaluates true.
2626
2627     else      (el) Part of the if (see there for more), elif, else, endif
2628               conditional — if none of the conditions of the preceding if and
2629               elif commands was true, the else block is executed.
2630
2631     endif     (en) Marks the end of an if (see there for more), elif, else,
2632               endif conditional execution block.
2633
2634     environ   [Only new quoting rules] There is a strict separation in be‐
2635               tween INTERNAL VARIABLES and the program ENVIRONMENT, which is
2636               inherited by child processes.  Some variables of the latter are
2637               however vivid for program operation, their purpose is known,
2638               therefore they have been integrated transparently into handling
2639               of the former, as accessible via set and unset.  To integrate
2640               any other environment variable, and/or to export internal vari‐
2641               ables into the process environment where they normally are not,
2642               a link needs to become established with this command, for exam‐
2643               ple
2644
2645                     environ link PERL5LIB TZ
2646
2647               Afterwards changing such variables with set will cause auto‐
2648               matic updates of the environment, too.  Sufficient system sup‐
2649               port provided (it was in BSD as early as 1987, and is standard‐
2650               ized since Y2K) removing such variables with unset will remove
2651               them also from the environment, but in any way the knowledge
2652               they ever have been linked will be lost.  This implies that
2653               localopts may cause loss of such links.
2654
2655               The subcommand unlink removes an existing link without other‐
2656               wise touching variables, the set and unset subcommands are
2657               identical to set and unset, but additionally update the program
2658               environment accordingly; removing a variable breaks any freely
2659               established link.
2660
2661     errors    [Option] As console user interfaces at times scroll error mes‐
2662               sages by too fast and/or out of scope, data can additionally be
2663               sent to an error queue manageable by this command: show or no
2664               argument will display and clear the queue, clear will only
2665               clear it.  As the queue becomes filled with errors-limit en‐
2666               tries the eldest entries are being dropped.  There are also the
2667               variables ^ERRQUEUE-COUNT and ^ERRQUEUE-EXISTS.
2668
2669     eval      [Only new quoting rules] Construct a command by concatenating
2670               the arguments, separated with a single space character, and
2671               then evaluate the result.  This command passes through the exit
2672               status ? and error number ! of the evaluated command; also see
2673               call.
2674
2675                     define xxx {
2676                       echo "xxx arg <$1>"
2677                       shift
2678                       if $# -gt 0
2679                         \xcall xxx "$@"
2680                       endif
2681                     }
2682                     define yyy {
2683                       eval "$@ ' ball"
2684                     }
2685                     call yyy '\call xxx' "b\$'\t'u ' "
2686                     call xxx arg <b      u>
2687                     call xxx arg <  >
2688                     call xxx arg <ball>
2689
2690     exit      (ex or x) Exit from S-nail without changing the active mailbox
2691               and skip any saving of messages in the secondary mailbox MBOX,
2692               as well as a possibly tracked line editor history-file.  A pos‐
2693               sibly set on-account-cleanup will be invoked, however.  The op‐
2694               tional status number argument will be passed through to
2695               exit(3).  [v15 behaviour may differ] For now it can happen that
2696               the given status will be overwritten, later this will only oc‐
2697               cur if a later error needs to be reported onto an otherwise
2698               success indicating status.
2699
2700     File      (Fi) Like folder, but open the mailbox read-only.
2701
2702     file      (fi) See folder.
2703
2704     filetype, unfiletype
2705               [Only new quoting rules] Define, list, and remove, respec‐
2706               tively, file handler hooks, which provide (shell) commands that
2707               enable S-nail to load and save MBOX files from and to files
2708               with the registered file extensions, as shown and described for
2709               folder.  The extensions are used case-insensitively, yet the
2710               auto-completion feature of for example folder will only work
2711               case-sensitively.  An intermediate temporary file will be used
2712               to store the expanded data.  The latter command will remove
2713               hooks for all given extensions, asterisk ‘*’ will remove all
2714               existing handlers.
2715
2716               When used without arguments the former shows a list of all cur‐
2717               rently defined file hooks, with one argument the expansion of
2718               the given alias.  Otherwise three arguments are expected, the
2719               first specifying the file extension for which the hook is
2720               meant, and the second and third defining the load- and save
2721               commands to deal with the file type, respectively, both of
2722               which must read from standard input and write to standard out‐
2723               put.  Changing hooks will not affect already opened mailboxes
2724               ([v15 behaviour may differ] except below).  [v15 behaviour may
2725               differ] For now too much work is done, and files are oftened
2726               read in twice where once would be sufficient: this can cause
2727               problems if a filetype is changed while such a file is opened;
2728               this was already so with the built-in support of .gz etc. in
2729               Heirloom, and will vanish in v15.  [v15 behaviour may differ]
2730               For now all handler strings are passed to the SHELL for
2731               evaluation purposes; in the future a ‘!’ prefix to load and
2732               save commands may mean to bypass this shell instance: placing a
2733               leading space will avoid any possible misinterpretations.
2734
2735                     ? filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
2736                         gz 'gzip -dc' 'gzip -c'  xz 'xz -dc' 'xz -zc' \
2737                         zst 'zstd -dc' 'zstd -19 -zc' \
2738                         zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2739                     ? set record=+sent.zst.pgp
2740
2741     flag, unflag
2742               Take message lists and mark the messages as being flagged, or
2743               not being flagged, respectively, for urgent/special attention.
2744               See the section Message states.
2745
2746     Folder    (Fold) Like folder, but open the mailbox read-only.
2747
2748     folder    (fold) Open a new, or show status information of the current
2749               mailbox.  If an argument is given, changes (such as deletions)
2750               will be written out, a new mailbox will be opened, the internal
2751               variables mailbox-resolved and mailbox-display will be updated,
2752               a set according folder-hook is executed, and optionally a sum‐
2753               mary of headers is displayed if the variable header is set.
2754
2755               Filename transformations will be applied to the name argument,
2756               and ‘protocol://’ prefixes are, i.e., URL (see On URL syntax
2757               and credential lookup) syntax is understood, as in
2758               ‘mbox:///tmp/somefolder’.  If a protocol prefix is used the
2759               mailbox type is fixated, otherwise opening none-existing
2760               folders uses the protocol defined in newfolders.
2761
2762               For the protocols mbox and file (MBOX database), as well as eml
2763               (electronic mail message [v15 behaviour may differ] read-only)
2764               the list of all registered filetypes is traversed to check
2765               whether hooks shall be used to load (and save) data from (and
2766               to) the given name.  Changing hooks will not affect already
2767               opened mailboxes.  For example, the following creates hooks for
2768               the gzip(1) compression tool and a combined compressed and en‐
2769               crypted format:
2770
2771                     ? filetype \
2772                         gzip 'gzip -dc' 'gzip -c' \
2773                         zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2774
2775               For historic reasons filetypes provide limited (case-sensitive)
2776               auto-completion capabilities.  For example ‘mbox.gz’ will be
2777               found for ‘? file mbox’, provided that corresponding handlers
2778               are installed.  It will neither find ‘mbox.GZ’ nor ‘mbox.Gz’
2779               however, but an explicit ‘? file mbox.GZ’ will find and use the
2780               handler for ‘gz’.  [v15 behaviour may differ] The latter mode
2781               can only be used for MBOX files.
2782
2783               EML files consist of only one mail message, [v15 behaviour may
2784               differ] and can only be opened read-only.  When reading MBOX
2785               files tolerant POSIX rules are used by default.  Invalid mes‐
2786               sage boundaries that can be found quite often in historic MBOX
2787               files will be complained about (even more with debug): in this
2788               case the method described for mbox-rfc4155 can be used to cre‐
2789               ate a valid MBOX database from the invalid input.
2790
2791               MBOX databases and EML files will always be protected via file-
2792               region locks (fcntl(2)) during file operations to protect
2793               against concurrent modifications.  [Option] An MBOX inbox
2794               (MAIL) or primary system mailbox will also be protected by so-
2795               called dotlock files, the traditional way of mail spool file
2796               locking: for any file ‘x’ a lock file ‘x.lock’ will be created
2797               during the synchronization, in the same directory and with the
2798               same user and group identities as the file of interest — as
2799               necessary created by an external privileged dotlock helper.
2800               dotlock-disable disables dotlock files.  Also see FAQ: Howto
2801               handle stale dotlock files.
2802
2803               [Option] If no protocol has been fixated, and name refers to a
2804               directory with the subdirectories ‘tmp’, ‘new’ and ‘cur’, then
2805               it is treated as a folder in “Maildir” format.  The maildir
2806               format stores each message in its own file, and has been de‐
2807               signed so that file locking is not necessary when reading or
2808               writing files.
2809
2810               [Option]ally URLs can be used to access network resources, se‐
2811               curely via Encrypted network communication, if so supported.
2812               Network communication socket timeouts are configurable via
2813               socket-connect-timeout.  All network traffic may be proxied
2814               over a SOCKS server via socks-proxy.
2815
2816                     [v15-compat]
2817                     protocol://[user[:password]@]host[:port][/path]
2818                     [no v15-compat] protocol://[user@]host[:port][/path]
2819
2820               [Option]ally supported network protocols are pop3 (POP3) and
2821               pop3s (POP3 with TLS encrypted transport), imap and imaps.  The
2822               [/path] part is valid only for IMAP; there it defaults to
2823               INBOX.  Network URLs require a special encoding as documented
2824               in the section On URL syntax and credential lookup.
2825
2826     folders   Lists the names of all folders below the given argument or
2827               folder.  For file-based protocols LISTER will be used for dis‐
2828               play purposes.
2829
2830     Followup, followup
2831               (Compose mode)(F,fo) Similar to Reply, and reply, respectively,
2832               but save the message in a file named after the local part of
2833               the (first) recipient's address, possibly overwriting record,
2834               and honouring outfolder.  Also see Copy and Save.
2835
2836     Forward   (Compose mode) Similar to forward, but saves the message in a
2837               file named after the local part of the recipient's address (in‐
2838               stead of in record).
2839
2840     forward   (Compose mode) Take a message list and the address of a recipi‐
2841               ent, subject to fullnames, to whom the messages are sent.  The
2842               text of the original message is included in the new one, en‐
2843               closed by the values of forward-inject-head and
2844               forward-inject-tail.  content-description-forwarded-message is
2845               inspected.  The list of included headers can be filtered with
2846               the ‘forward’ slot of the white- and blacklisting command
2847               headerpick.  Only the first part of a multipart message is in‐
2848               cluded but for forward-as-attachment.
2849
2850               This may generate the errors ^ERR-DESTADDRREQ if no receiver
2851               has been specified, or was rejected by expandaddr policy,
2852               ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
2853               character set conversion fails, and ^ERR-INVAL for other er‐
2854               rors.  It can also fail with errors of Specifying messages.
2855               Any error stops processing of further messages.
2856
2857     from      (f) Takes a list of message specifications and displays a sum‐
2858               mary of their message headers, exactly as via headers, making
2859               the first message of the result the new “dot” (the last message
2860               if showlast is set).  An alias of this command is search.  Also
2861               see Specifying messages.
2862
2863     Fwd       [Obsolete] Alias for Forward.
2864
2865     fwd       [Obsolete] Alias for forward.
2866
2867     fwdignore
2868               [Obsolete] Superseded by the multiplexer headerpick.
2869
2870     fwdretain
2871               [Obsolete] Superseded by the multiplexer headerpick.
2872
2873     ghost, unghost
2874               [Obsolete] Replaced by commandalias, uncommandalias.
2875
2876     headerpick, unheaderpick
2877               [Only new quoting rules] Multiplexer command to manage white-
2878               and blacklisting selections of header fields for a variety of
2879               applications.  Without arguments the set of contexts that have
2880               settings is displayed.  When given arguments, the first argu‐
2881               ment is the context to which the command applies, one of (case-
2882               insensitive) ‘type’ for display purposes (for example type),
2883               ‘save’ for selecting which headers shall be stored persistently
2884               when save, copy, move or even decrypting messages (note that
2885               MIME related etc. header fields should not be ignored in order
2886               to not destroy usability of the message in this case),
2887               ‘forward’ for stripping down messages when forwarding message
2888               (has no effect if forward-as-attachment is set), and ‘top’ for
2889               defining user-defined set of fields for the command top.
2890
2891               The current settings of the given context are displayed if it
2892               is the only argument.  A second argument denotes the type of
2893               restriction that is to be chosen, it may be (a case-insensitive
2894               prefix of) ‘retain’ or ‘ignore’ for white- and blacklisting
2895               purposes, respectively.  Establishing a whitelist suppresses
2896               inspection of the corresponding blacklist.
2897
2898               If no further argument is given the current settings of the
2899               given type will be displayed, otherwise the remaining arguments
2900               specify header fields, which [Option]ally may be given as regu‐
2901               lar expressions, to be added to the given type.  The special
2902               wildcard field (asterisk, ‘*’) will establish a (fast) short‐
2903               hand setting which covers all fields.
2904
2905               The latter command always takes three or more arguments and can
2906               be used to remove selections, i.e., from the given context, the
2907               given type of list, all the given headers will be removed, the
2908               special argument ‘*’ will remove all headers.
2909
2910     headers   (h) Show the current group of headers, the size of which de‐
2911               pends on the variable screen in interactive mode, and the for‐
2912               mat of which can be defined with headline.  If a message-speci‐
2913               fication is given the group of headers containing the first
2914               message therein is shown and the message at the top of the
2915               screen becomes the new “dot”; the last message is targeted if
2916               showlast is set.
2917
2918     help      (hel) A synonym for ?.
2919
2920     history   [Option] Without arguments or when given show all history en‐
2921               tries are shown (this mode also supports a more verbose out‐
2922               put).  load will replace the list of entries with the content
2923               of history-file, and save will dump all entries to said file,
2924               replacing former content, and clear will delete all entries.
2925               The argument can also be a signed decimal NUMBER, which will
2926               select and evaluate the respective history entry, and move it
2927               to the top of the history; a negative number is used as an off‐
2928               set to the current command so that ‘-1’ will select the last
2929               command, the history top, whereas delete will delete all given
2930               entries (:NUMBER:).  Also see On terminal control and line
2931               editor.
2932
2933     hold      (ho, also preserve) Takes a message list and marks each message
2934               therein to be saved in the user's system inbox instead of in
2935               the secondary mailbox MBOX.  Does not override the delete com‐
2936               mand.  S-nail deviates from the POSIX standard with this com‐
2937               mand, because a next command issued after hold will display the
2938               following message, not the current one.
2939
2940     if        (i) Part of the if, elif, else, endif conditional execution
2941               construct — if the given condition is true then the encapsu‐
2942               lated block is executed.  The POSIX standard only supports the
2943               (case-insensitive) conditions ‘r’eceive and ‘s’end, the remain‐
2944               ing are non-portable extensions.  [v15 behaviour may differ] In
2945               conjunction with the wysh command prefix(es) Shell-style
2946               argument quoting and more test operators are available.
2947
2948                     if receive
2949                       commands ...
2950                     else
2951                       commands ...
2952                     endif
2953
2954               Further (case-insensitive) one-argument conditions are
2955               ‘t’erminal which evaluates to true in interactive terminal ses‐
2956               sions (running with standard input or standard output attached
2957               to a terminal, and none of the “quickrun” command line options
2958               -e, -H and -L have been used), as well as any boolean value
2959               (see INTERNAL VARIABLES for textual boolean representations) to
2960               mark an enwrapped block as “never execute” or “always execute”.
2961               (Remarks: condition syntax errors skip all branches until
2962               endif.)
2963
2964               [no v15-compat] and without wysh: It is possible to check
2965               INTERNAL VARIABLES as well as ENVIRONMENT variables for exis‐
2966               tence or compare their expansion against a user given value or
2967               another variable by using the ‘$’ (“variable next”) conditional
2968               trigger character; a variable on the right hand side may be
2969               signalled using the same mechanism.  Variable names may be en‐
2970               closed in a pair of matching braces.  When this mode has been
2971               triggered, several operators are available ([v15-compat] and
2972               wysh: they are always available, and there is no trigger: vari‐
2973               ables will have been expanded by the shell-compatible parser
2974               before the if etc. command sees them).
2975
2976               [v15-compat] Two argument conditions.  Variables can be tested
2977               for existence and expansion: ‘-N’ will test whether the given
2978               variable exists, so that ‘-N editalong’ will evaluate to true
2979               when editalong is set, whereas ‘-Z editalong’ will if it is
2980               not.  ‘-n "$editalong"’ will be true if the variable is set and
2981               expands to a non-empty string, ‘-z $'\$editalong'’ only if the
2982               expansion is empty, whether the variable exists or not.  The
2983               remaining conditions take three arguments.
2984
2985               Integer operators treat the arguments on the left and right
2986               hand side of the operator as integral numbers and compare them
2987               arithmetically.  It is an error if any of the operands is not a
2988               valid integer, an empty argument (which implies it had been
2989               quoted) is treated as if it were 0.  Via the question mark ‘?’
2990               modifier suffix a saturated operation mode is available where
2991               numbers will linger at the minimum or maximum possible value,
2992               instead of overflowing (or trapping), the keyword ‘saturated’
2993               is optional, ‘==?’, ‘==?satu’ and ‘==?saturated’ are therefore
2994               identical.  Available operators are ‘-lt’ (less than), ‘-le’
2995               (less than or equal to), ‘-eq’ (equal), ‘-ne’ (not equal),
2996               ‘-ge’ (greater than or equal to), and ‘-gt’ (greater than).
2997
2998               String and regular expression data operators compare the left
2999               and right hand side according to their textual content.  Unset
3000               variables are treated as the empty string.  Via the question
3001               mark ‘?’ modifier suffix a case-insensitive operation mode is
3002               available, the keyword ‘case’ is optional, ‘==?’ and ‘==?case’
3003               are identical.
3004
3005               Available string operators are ‘<’ (less than), ‘<=’ (less than
3006               or equal to), ‘==’ (equal), ‘!=’ (not equal), ‘>=’ (greater
3007               than or equal to), ‘>’ (greater than), ‘=%’ (is substring of)
3008               and ‘!%’ (is not substring of).  By default these operators
3009               work on bytes and (therefore) do not take into account charac‐
3010               ter set specifics.  If the case-insensitivity modifier has been
3011               used, case is ignored according to the rules of the US-ASCII
3012               encoding, i.e., bytes are still compared.
3013
3014               When the [Option]al regular expression support is available,
3015               the additional string operators ‘=~’ and ‘!~’ can be used.
3016               They treat the right hand side as an extended regular expres‐
3017               sion that is matched according to the active locale (see
3018               Character sets), i.e., character sets should be honoured cor‐
3019               rectly.
3020
3021               Conditions can be joined via AND-OR lists (where the AND opera‐
3022               tor is ‘&&’ and the OR operator is ‘||’), which have equal
3023               precedence and will be evaluated with left associativity, thus
3024               using the same syntax that is known for the sh(1).  It is also
3025               possible to form groups of conditions and lists by enclosing
3026               them in pairs of brackets ‘[ ... ]’, which may be interlocked
3027               within each other, and also be joined via AND-OR lists.
3028
3029               The results of individual conditions and entire groups may be
3030               modified via unary operators: the unary operator ‘!’ will re‐
3031               verse the result.
3032
3033                     wysh set v15-compat=yes # with value: automatic "wysh"!
3034                     if -N debug;echo *debug* set;else;echo not;endif
3035                     if "$ttycharset" == UTF-8 || "$ttycharset" ==?cas UTF8
3036                       echo ttycharset is UTF-8, the former case-sensitive!
3037                     endif
3038                     set t1=one t2=one
3039                     if [ "${t1}" == "${t2}" ]
3040                       echo These two variables are equal
3041                     endif
3042                     if "$features" =% ,+regex, && "$TERM" =~?case ^xterm.*
3043                       echo ..in an X terminal
3044                     endif
3045                     if [ [ true ] && [ [ "${debug}" != '' ] || \
3046                         [ "$verbose" != '' ] ] ]
3047                       echo Noisy, noisy
3048                     endif
3049                     if true && [ -n "$debug" || -n "${verbose}" ]
3050                       echo Left associativity, as is known from the shell
3051                     endif
3052
3053     ignore    (ig) Identical to discard.  Superseded by the multiplexer
3054               headerpick.
3055
3056     list      Shows the names of all available commands, in command lookup
3057               order.  [Option] In conjunction with a set variable verbose ad‐
3058               ditional information will be provided for each command: the ar‐
3059               gument type will be indicated, the documentation string will be
3060               shown, and the set of command flags will show up:
3061
3062               ‘`local'’    command supports the command modifier local.
3063               ‘`vput'’     command supports the command modifier vput.
3064               ‘*!*’        the error number is tracked in !.
3065               ‘needs-box’  whether the command needs an active mailbox, a
3066                            folder.
3067               ‘ok:’        indicators whether command is ...
3068                            ‘batch/interactive’
3069                                          usable in interactive or batch mode
3070                                          (-#).
3071                            ‘send-mode’   usable in send mode.
3072                            ‘subprocess’  allowed to be used when running in a
3073                                          subprocess instance, for example
3074                                          from within a macro that is called
3075                                          via on-compose-splice.
3076               ‘not ok:’    indicators whether command is not ...
3077                            ‘compose mode’  available in Compose mode.
3078                            ‘startup’       available during program startup,
3079                                            like in Resource files.
3080               ‘gabby’      The command produces history-gabby history en‐
3081                            tries.
3082
3083     localopts
3084               Enforce change localization of environ (linked) ENVIRONMENT as
3085               well as (global) INTERNAL VARIABLES, meaning that their state
3086               will be reverted to the former one once the “covered scope” is
3087               left.  Just like the command modifier local, which provides
3088               block-scope localization for some commands (instead), it can
3089               only be used inside of macro definition blocks introduced by
3090               account or define.  The covered scope of an account is left
3091               once a different account is activated, and some macros, notably
3092               folder-hooks, use their own specific notion of covered scope,
3093               here it will be extended until the folder is left again.
3094
3095               This setting stacks up: i.e., if ‘macro1’ enables change local‐
3096               ization and calls ‘macro2’, which explicitly resets localiza‐
3097               tion, then any value changes within ‘macro2’ will still be re‐
3098               verted when the scope of ‘macro1’ is left.  (Caveats: if in
3099               this example ‘macro2’ changes to a different account which sets
3100               some variables that are already covered by localizations, their
3101               scope will be extended, and in fact leaving the account will
3102               (thus) restore settings in (likely) global scope which actually
3103               were defined in a local, macro private context!)
3104
3105               This command takes one or two arguments, the optional first one
3106               specifies an attribute that may be one of scope, which refers
3107               to the current scope and is thus the default, call, which
3108               causes any macro that is being called to be started with local‐
3109               ization enabled by default, as well as call-fixate, which (if
3110               enabled) disallows any called macro to turn off localization:
3111               like this it can be ensured that once the current scope regains
3112               control, any changes made in deeper levels have been reverted.
3113               The latter two are mutually exclusive, and neither affects
3114               xcall.  The (second) argument is interpreted as a boolean
3115               (string, see INTERNAL VARIABLES) and states whether the given
3116               attribute shall be turned on or off.
3117
3118                     define temporary_settings {
3119                       set possibly_global_option1
3120                       localopts on
3121                       set localized_option1
3122                       set localized_option2
3123                       localopts scope off
3124                       set possibly_global_option2
3125                     }
3126
3127     Lfollowup, Lreply
3128               (Compose mode) Reply to messages that come in via known (mlist)
3129               or subscribed (mlsubscribe) mailing lists, or pretend to do so
3130               (see Mailing lists): on top of the usual followup and reply,
3131               respectively, functionality this will actively resort and even
3132               remove message recipients in order to generate a message that
3133               is supposed to be sent to a mailing list.  For example it will
3134               also implicitly generate a ‘Mail-Followup-To:’ header if that
3135               seems useful, regardless of the setting of the variable
3136               followup-to.  For more documentation please refer to On sending
3137               mail, and non-interactive mode.
3138
3139               This may generate the errors ^ERR-DESTADDRREQ if no receiver
3140               has been specified, ^ERR-PERM if some addressees where rejected
3141               by expandaddr, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a
3142               necessary character set conversion fails, and ^ERR-INVAL for
3143               other errors.  It can also fail with errors of Specifying
3144               messages.  Occurrence of some of the errors depend on the value
3145               of expandaddr.  Any error stops processing of further messages.
3146
3147     Mail      (Compose mode) Similar to mail, but saves the message in a file
3148               named after the local part of the first recipient's address
3149               (instead of in record).
3150
3151     mail      (Compose mode)(m) Takes a (list of) recipient address(es) as
3152               (an) argument(s), or asks on standard input if none were given;
3153               then collects the remaining mail content and sends it out.  Un‐
3154               less the internal variable fullnames is set recipient addresses
3155               will be stripped from comments, names etc.  For more documenta‐
3156               tion please refer to On sending mail, and non-interactive mode.
3157
3158               This may generate the errors ^ERR-DESTADDRREQ if no receiver
3159               has been specified, ^ERR-PERM if some addressees where rejected
3160               by expandaddr, ^ERR-NOTSUP if multiple messages have been spec‐
3161               ified, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a neces‐
3162               sary character set conversion fails, and ^ERR-INVAL for other
3163               errors.  It can also fail with errors of Specifying messages.
3164               Occurrence of some of the errors depend on the value of
3165               expandaddr.
3166
3167     mailcap   [Option] When used without arguments or if show has been given
3168               the content of The Mailcap files cache is shown, (re-)initial‐
3169               izing it first (as necessary.  If the argument is load then the
3170               cache will only be (re-)initialized, and clear will remove its
3171               contents.  Note that S-nail will try to load the files only
3172               once, use ‘mailcap clear’ to unlock further attempts.  Loading
3173               and parsing can be made more verbose.
3174
3175     mbox      (mb) The given message list is to be sent to the secondary
3176               mailbox MBOX when S-nail is quit; this is the default action
3177               unless the variable hold is set.  [v15 behaviour may differ]
3178               This command can only be used in a primary system mailbox.
3179
3180     mimetype, unmimetype
3181               [Only new quoting rules] Without arguments the content of the
3182               MIME type cache will displayed; a more verbose listing will be
3183               produced if either of debug or verbose are set.  When given ar‐
3184               guments they will be joined, interpreted as shown in The
3185               mime.types files (also see HTML mail and MIME attachments), and
3186               the resulting entry will be added (prepended) to the cache.  In
3187               any event MIME type sources are loaded first as necessary –
3188               mimetypes-load-control can be used to fine-tune which sources
3189               are actually loaded.
3190
3191               The latter command deletes all specifications of the given MIME
3192               type, thus ‘? unmimetype text/plain’ will remove all registered
3193               specifications for the MIME type ‘text/plain’.  The special
3194               name ‘*’ will discard all existing MIME types, just as will
3195               ‘reset’, but which also reenables cache initialization via
3196               mimetypes-load-control.
3197
3198     mimeview  [v15 behaviour may differ] Only available in interactive mode,
3199               this command allows execution of external MIME type handlers
3200               which do not integrate into the normal type output (see HTML
3201               mail and MIME attachments).  ([v15 behaviour may differ] No
3202               syntax to directly address parts, this restriction may vanish.)
3203               The user will be asked for each non-text part of the given mes‐
3204               sage in turn whether the registered handler shall be used to
3205               display the part.
3206
3207     mlist, unmlist
3208               [Only new quoting rules] Manage the list of known Mailing
3209               lists; subscriptions are controlled via mlsubscribe.  The lat‐
3210               ter command deletes all given arguments, or all at once when
3211               given the asterisk ‘*’.  The former shows the list of all cur‐
3212               rently known lists if used without arguments, otherwise the
3213               given arguments will become known.  [Option] In the latter
3214               case, arguments which contain any of the magic regular
3215               expression characters will be interpreted as one, possibly
3216               matching many addresses; these will be sequentially matched via
3217               linked lists instead of being looked up in a dictionary.
3218
3219     mlsubscribe, unmlsubscribe
3220               Building upon the command pair mlist, unmlist, but only manag‐
3221               ing the subscription attribute of mailing lists.  (The former
3222               will also create not yet existing mailing lists.)
3223
3224     Move      Similar to move, but move the messages to a file named after
3225               the local part of the sender of the first message instead of
3226               taking a filename argument; outfolder is inspected to decide on
3227               the actual storage location.
3228
3229     move      Acts like copy but marks the messages for deletion if they were
3230               transferred successfully.
3231
3232     More      Like more, but also displays header fields which would not pass
3233               the headerpick selection, and all MIME parts.  Identical to
3234               Page.
3235
3236     more      Invokes the PAGER on the given messages, even in non-interac‐
3237               tive mode and as long as the standard output is a terminal.
3238               Identical to page.
3239
3240     mtaaliases
3241               [Option] When used without arguments or if show has been given
3242               the content of the mta-aliases cache is shown, (re-)initializ‐
3243               ing it first (as necessary).  If the argument is load then the
3244               cache will only be (re-)initialized, and clear will remove its
3245               contents.
3246
3247     netrc     [Option] When used without arguments, or when the argument was
3248               show the content of the ~/.netrc cache is shown, initializing
3249               it as necessary.  If the argument is load then the cache will
3250               be (re)loaded, whereas clear removes it.  Loading and parsing
3251               can be made more verbose.  lookup will query the cache for the
3252               URL given as the second argument (‘[USER@]HOST’).  See
3253               netrc-lookup, netrc-pipe and the section On URL syntax and
3254               credential lookup; the section The .netrc file documents the
3255               file format in detail.
3256
3257     newmail   Checks for new mail in the current folder without committing
3258               any changes before.  If new mail is present, a message is
3259               shown.  If the header variable is set, the headers of each new
3260               message are also shown.  This command is not available for all
3261               mailbox types.
3262
3263     next      (n) (like ‘+’ or “ENTER”) Goes to the next message in sequence
3264               and types it.  With an argument list, types the next matching
3265               message.
3266
3267     New       Same as Unread.
3268
3269     new       Same as unread.
3270
3271     noop      If the current folder is accessed via a network connection, a
3272               “NOOP” command is sent, otherwise no operation is performed.
3273
3274     Page      Like page, but also displays header fields which would not pass
3275               the headerpick selection, and all MIME parts.  Identical to
3276               More.
3277
3278     page      Invokes the PAGER on the given messages, even in non-interac‐
3279               tive mode and as long as the standard output is a terminal.
3280               Identical to more.
3281
3282     Pipe      Like pipe but also pipes header fields which would not pass the
3283               headerpick selection, and all parts of MIME
3284               ‘multipart/alternative’ messages.
3285
3286     pipe      (pi) Takes an optional message list and shell command (that de‐
3287               faults to cmd), and pipes the messages through the command.  If
3288               the page variable is set, every message is followed by a form‐
3289               feed character.
3290
3291     preserve  (pre) A synonym for hold.
3292
3293     Print     (P) Alias for Type.
3294
3295     print     (p) Research UNIX equivalent of type.
3296
3297     quit      (q) Terminates the session, saving all undeleted, unsaved mes‐
3298               sages in the current secondary mailbox MBOX, preserving all
3299               messages marked with hold or preserve or never referenced in
3300               the system inbox, and removing all other messages from the
3301               primary system mailbox.  If new mail has arrived during the
3302               session, the message “You have new mail” will be shown.  If
3303               given while editing a mailbox file with the command line option
3304               -f, then the edit file is rewritten.  A return to the shell is
3305               effected, unless the rewrite of edit file fails, in which case
3306               the user can escape with the exit command.  The optional status
3307               number argument will be passed through to exit(3).  [v15 behav‐
3308               iour may differ] For now it can happen that the given status
3309               will be overwritten, later this will only occur if a later er‐
3310               ror needs to be reported onto an otherwise success indicating
3311               status.
3312
3313     read      [Only new quoting rules] Read a line from standard input, or
3314               the channel set active via readctl, and assign the data, which
3315               will be split as indicated by ifs, to the given variables.  The
3316               variable names are checked by the same rules as documented for
3317               vput, and the same error codes will be seen in !; the exit sta‐
3318               tus ? indicates the number of bytes read, it will be ‘-1’ with
3319               the error number ! set to ^ERR-BADF in case of I/O errors, or
3320               ^ERR-NONE upon End-Of-File.  If there are more fields than
3321               variables, assigns successive fields to the last given vari‐
3322               able.  If there are less fields than variables, assigns the
3323               empty string to the remains.
3324
3325                     ? read a b c
3326                        H  e  l  l  o
3327                     ? echo "<$a> <$b> <$c>"
3328                     <H> <e> <l  l  o>
3329                     ? wysh set ifs=:; read a b c;unset ifs
3330                     hey2.0,:"'you    ",:world!:mars.:
3331                     ? echo $?/$^ERRNAME / <$a><$b><$c>
3332                     0/NONE / <hey2.0,><"'you    ",><world!:mars.:><><>
3333
3334     readsh    [Only new quoting rules] Like read, but splits on shell token
3335               boundaries (see Shell-style argument quoting) rather than at
3336               ifs.  [v15 behaviour may differ] Could become a commandalias,
3337               maybe ‘read --tokenize --’.
3338
3339     readall   [Only new quoting rules] Read anything from standard input, or
3340               the channel set active via readctl, and assign the data to the
3341               given variable.  The variable name is checked by the same rules
3342               as documented for vput, and the same error codes will be seen
3343               in !; the exit status ? indicates the number of bytes read, it
3344               will be ‘-1’ with the error number ! set to ^ERR-BADF in case
3345               of I/O errors, or ^ERR-NONE upon End-Of-File.  [v15 behaviour
3346               may differ] The input data length is restricted to 31-bits.
3347
3348     readctl   [Only new quoting rules] Manages input channels for read,
3349               readsh and readall, to be used to avoid complicated or imprac‐
3350               ticable code, like calling read from within a macro in non-in‐
3351               teractive mode.  Without arguments, or when the first argument
3352               is show, a listing of all known channels is printed.  Channels
3353               can otherwise be created, and existing channels can be set ac‐
3354               tive and removed by giving the string used for creation.
3355
3356               The channel name is expected to be a file descriptor number,
3357               or, if parsing the numeric fails, an input file name that un‐
3358               dergoes Filename transformations.  For example (this example
3359               requires a modern shell):
3360
3361                     $ printf 'echon "hey, "\nread a\nyou\necho $a' |\
3362                       s-nail -R#
3363                     hey, you
3364                     $ LC_ALL=C printf 'echon "hey, "\nread a\necho $a' |\
3365                       LC_ALL=C 6<<< 'you' s-nail -R#X'readctl create 6'
3366                     hey, you
3367
3368     remove    [Only new quoting rules] Removes the named files or directo‐
3369               ries.  If a name refers to a mailbox, say a Maildir mailbox,
3370               then a mailbox type specific removal will be performed, delet‐
3371               ing the complete mailbox.  In interactive mode the user is
3372               asked for confirmation.
3373
3374     rename    [Only new quoting rules] Takes the name of an existing folder
3375               and the name for the new folder and renames the first to the
3376               second one.  Filename transformations including shell pathname
3377               wildcard pattern expansions (glob(7)) are performed on both ar‐
3378               guments.  Both folders must be of the same type.
3379
3380     Reply, Respond
3381               (Compose mode)(R) Identical to reply except that it replies to
3382               only the sender of each message of the given list, by using the
3383               first message as the template to quote, for the ‘Subject:’
3384               etc.; setting flipr will exchange this command with reply.
3385
3386     reply, respond
3387               (Compose mode)(r) Take a message (list) and group-respond (to
3388               each in turn) by addressing the sender and all recipients, sub‐
3389               ject to fullnames and alternates processing.  followup-to,
3390               followup-to-honour, reply-to-honour as well as recipients-in-cc
3391               influence response behaviour.  quote as well as
3392               quote-as-attachment configure whether responded-to message
3393               shall be quoted etc., content-description-quote-attachment may
3394               be used.  Setting flipr will exchange this command with Reply.
3395               The command Lreply offers special support for replying to mail‐
3396               ing lists.  For more documentation please refer to On sending
3397               mail, and non-interactive mode.
3398
3399               This may generate the errors ^ERR-DESTADDRREQ if no receiver
3400               has been specified, or was rejected by expandaddr policy,
3401               ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3402               character set conversion fails, and ^ERR-INVAL for other er‐
3403               rors.  It can also fail with errors of Specifying messages.
3404               Any error stops processing of further messages.
3405
3406     Resend    Like resend, but does not add any header lines.  This is not a
3407               way to hide the sender's identity, but useful for sending a
3408               message again to the same recipients.
3409
3410     resend    Takes a list of messages and a name, and sends each message to
3411               the given addressee, which is subject to fullnames.
3412               ‘Resent-From:’ and related header fields are prepended to the
3413               new copy of the message.  Saving in record is only performed if
3414               record-resent is set.  [v15 behaviour may differ](Compose mode)
3415               is not entered, the only supported hooks are on-resend-enter
3416               and on-resend-cleanup.
3417
3418               This may generate the errors ^ERR-DESTADDRREQ if no receiver
3419               has been specified, or was rejected by expandaddr policy,
3420               ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3421               character set conversion fails, and ^ERR-INVAL for other er‐
3422               rors.  It can also fail with errors of Specifying messages.
3423               Any error stops processing of further messages.
3424
3425     retain    (ret) Superseded by the multiplexer headerpick.
3426
3427     return    Only available inside of a defined macro or an account, this
3428               command returns control of execution to the outer scope.  The
3429               two optional parameters are positive decimal numbers and de‐
3430               fault to 0: the first specifies the 32-bit return value (stored
3431               in ? [v15 behaviour may differ] and later extended to 64-bit),
3432               the second the 32-bit error number (stored in !).  As docu‐
3433               mented for ? a non-0 exit status may cause the program to exit.
3434
3435     Save      (S) Similar to save, but saves the messages in a file named af‐
3436               ter the local part of the sender of the first message instead
3437               of taking a filename argument; outfolder is inspected to decide
3438               on the actual storage location.
3439
3440     save      (s) Takes a message list and a filename and appends each mes‐
3441               sage in turn to the end of the file.  Filename transformations
3442               including shell pathname wildcard pattern expansions (glob(7))
3443               is performed on the filename.  If no filename is given, the
3444               secondary mailbox MBOX is used.  The filename in quotes, fol‐
3445               lowed by the generated character count is echoed on the user's
3446               terminal.  If editing a primary system mailbox the messages are
3447               marked for deletion.  To filter the saved header fields to the
3448               desired subset use the ‘save’ slot of the white- and blacklist‐
3449               ing command headerpick.  Also see Copy.
3450
3451     savediscard
3452               [Obsolete] Superseded by the multiplexer headerpick.
3453
3454     saveignore
3455               [Obsolete] Superseded by the multiplexer headerpick.
3456
3457     saveretain
3458               [Obsolete] Superseded by the multiplexer headerpick.
3459
3460     search    Takes a message specification (list) and displays a header sum‐
3461               mary of all matching messages, as via headers.  This command is
3462               an alias of from.  Also see Specifying messages.
3463
3464     seen      Takes a message list and marks all messages as having been
3465               read.
3466
3467     set, unset
3468               (se, [Only new quoting rules] uns) The latter command will
3469               delete all given global variables, or only block-scope local
3470               ones if the local command modifier has been used.  The former,
3471               when used without arguments, will show all currently known
3472               variables, being more verbose if either of debug or verbose is
3473               set.  Remarks: this list mode will not automatically link-in
3474               (known) ENVIRONMENT variables, this only happens for explicit
3475               addressing, examples are varshow, using a variable in an if
3476               condition or a string passed to echo, explicit setting, as well
3477               as some program-internal use cases (look-ups).
3478
3479               Otherwise the given variables (and arguments) are set or ad‐
3480               justed.  Arguments are of the form ‘name=value’ (no space be‐
3481               fore or after ‘=’), or plain ‘name’ if there is no value, i.e.,
3482               a boolean variable.  If a name begins with ‘no’, as in ‘set
3483               nosave’, the effect is the same as invoking the unset command
3484               with the remaining part of the variable (‘unset save’).  [v15
3485               behaviour may differ] In conjunction with the wysh (or local)
3486               command prefix(es) Shell-style argument quoting can be used to
3487               quote arguments as necessary.  [v15 behaviour may differ] Oth‐
3488               erwise quotation marks may be placed around any part of the as‐
3489               signment statement to quote blanks or tabs.
3490
3491               When operating in global scope any ‘name’ that is known to map
3492               to an environment variable will automatically cause updates in
3493               the program environment (unsetting a variable in the environ‐
3494               ment requires corresponding system support) — use the command
3495               environ for further environmental control.  If the command mod‐
3496               ifier local has been used to enforce local scoping then the
3497               given user variables will be garbage collected when the local
3498               scope is left; for INTERNAL VARIABLES, however, local behaves
3499               the same as if localopts would have been set (temporarily),
3500               which means that changes are inherited by deeper scopes.  Also
3501               see varshow and the sections INTERNAL VARIABLES and
3502               ENVIRONMENT.
3503
3504                     ? wysh set indentprefix=' -> '
3505                     ? wysh set atab=$'' aspace=' ' zero=0
3506
3507     shcodec   Apply shell quoting rules to the given raw-data arguments.
3508               Supports vput (see Command modifiers).  The first argument
3509               specifies the operation: [+]e[ncode] or d[ecode] cause shell
3510               quoting to be applied to the remains of the line, and expanded
3511               away thereof, respectively.  If the former is prefixed with a
3512               plus-sign, the quoted result will not be roundtrip enabled, and
3513               thus can be decoded only in the very same environment that was
3514               used to perform the encode; also see mle-quote-rndtrip.  If the
3515               coding operation fails the error number ! is set to
3516               ^ERR-CANCELED, and the unmodified input is used as the result;
3517               the error number may change again due to output or result stor‐
3518               age errors.
3519
3520     shell     [Only new quoting rules] (sh) Invokes an interactive version of
3521               the shell, and returns its exit status.
3522
3523     shortcut, unshortcut
3524               [Only new quoting rules] Manage the file- or pathname shortcuts
3525               as documented for folder.  The latter command deletes all
3526               shortcuts given as arguments, or all at once when given the as‐
3527               terisk ‘*’.  The former shows the list of all currently defined
3528               shortcuts if used without arguments, the target of the given
3529               with a single argument.  Otherwise arguments are treated as
3530               pairs of shortcuts and their desired expansion, creating new or
3531               updating already existing ones.
3532
3533     shift     [Only new quoting rules] Shift the positional parameter stack
3534               (starting at 1) by the given number (which must be a positive
3535               decimal), or 1 if no argument has been given.  It is an error
3536               if the value exceeds the number of positional parameters.  If
3537               the given number is 0, no action is performed, successfully.
3538               The stack as such can be managed via vpospar.  Note this com‐
3539               mand will fail in account and hook macros unless the positional
3540               parameter stack has been explicitly created in the current con‐
3541               text via vpospar.
3542
3543     show      Like type, but performs neither MIME decoding nor decryption,
3544               so that the raw message text is shown.
3545
3546     size      (si) Shows the size in characters of each message of the given
3547               message list.
3548
3549     sleep     [Only new quoting rules] Sleep for the specified number of sec‐
3550               onds (and optionally milliseconds), by default interruptible.
3551               If a third argument is given the sleep will be uninterruptible,
3552               otherwise the error number ! will be set to ^ERR-INTR if the
3553               sleep has been interrupted.  The command will fail and the er‐
3554               ror number will be ^ERR-OVERFLOW if the given duration(s) over‐
3555               flow the time datatype, and ^ERR-INVAL if the given durations
3556               are no valid integers.
3557
3558     sort, unsort
3559               The latter command disables sorted or threaded mode, returns to
3560               normal message order and, if the header variable is set, dis‐
3561               plays a header summary.  The former command shows the current
3562               sorting criterion when used without an argument, but creates a
3563               sorted representation of the current folder otherwise, and
3564               changes the next command and the addressing modes such that
3565               they refer to messages in the sorted order.  Message numbers
3566               are the same as in regular mode.  If the header variable is
3567               set, a header summary in the new order is also displayed.  Au‐
3568               tomatic folder sorting can be enabled by setting the autosort
3569               variable, as in ‘set autosort=thread’.  Possible sorting crite‐
3570               rions are:
3571
3572               date     Sort the messages by their ‘Date:’ field, that is by
3573                        the time they were sent.
3574               from     Sort messages by the value of their ‘From:’ field,
3575                        that is by the address of the sender.  If the showname
3576                        variable is set, the sender's real name (if any) is
3577                        used.
3578               size     Sort the messages by their size.
3579               spam     [Option] Sort the message by their spam score, as has
3580                        been classified by spamrate.
3581               status   Sort the messages by their message status.
3582               subject  Sort the messages by their subject.
3583               thread   Create a threaded display.
3584               to       Sort messages by the value of their ‘To:’ field, that
3585                        is by the address of the recipient.  If the showname
3586                        variable is set, the recipient's real name (if any) is
3587                        used.
3588
3589     source    [Only new quoting rules] (so) The source command reads commands
3590               from the given file.  Filename transformations will be applied.
3591               If the given expanded argument ends with a vertical bar ‘|’
3592               then the argument will instead be interpreted as a shell com‐
3593               mand and S-nail will read the output generated by it.  Depen‐
3594               dent on the settings of posix and errexit, and also dependent
3595               on whether the command modifier ignerr had been used, encoun‐
3596               tering errors will stop sourcing of the given input.  [v15 be‐
3597               haviour may differ] Note that source cannot be used from within
3598               macros that execute as folder-hooks or accounts, i.e., it can
3599               only be called from macros that were called.
3600
3601     source_if
3602               [Only new quoting rules] The difference to source (beside not
3603               supporting pipe syntax aka shell command input) is that this
3604               command will not generate an error nor warn if the given file
3605               argument cannot be opened successfully.
3606
3607     spamclear
3608               [Option] Takes a list of messages and clears their ‘is-spam’
3609               flag.
3610
3611     spamforget
3612               [Option] Takes a list of messages and causes the spam-interface
3613               to forget it has ever used them to train its Bayesian filter.
3614               Unless otherwise noted the ‘is-spam’ flag of the message is in‐
3615               spected to chose whether a message shall be forgotten to be
3616               “ham” or “spam”.
3617
3618     spamham   [Option] Takes a list of messages and informs the Bayesian fil‐
3619               ter of the spam-interface that they are “ham”.  This also
3620               clears the ‘is-spam’ flag of the messages in question.
3621
3622     spamrate  [Option] Takes a list of messages and rates them using the con‐
3623               figured spam-interface, without modifying the messages, but
3624               setting their ‘is-spam’ flag as appropriate; because the spam
3625               rating headers are lost the rate will be forgotten once the
3626               mailbox is left.  Refer to the manual section Handling spam for
3627               the complete picture of spam handling in S-nail.
3628
3629     spamset   [Option] Takes a list of messages and sets their ‘is-spam’
3630               flag.
3631
3632     spamspam  [Option] Takes a list of messages and informs the Bayesian fil‐
3633               ter of the spam-interface that they are “spam”.  This also sets
3634               the ‘is-spam’ flag of the messages in question.
3635
3636     thread    [Obsolete] The same as ‘sort thread’ (consider using a
3637               ‘commandalias’ as necessary).
3638
3639     tls       [Only new quoting rules] TLS information and management command
3640               multiplexer to aid in Encrypted network communication, mostly
3641               available only if the term ‘,+sockets,’ is included in
3642               features.  Commands support vput if so documented (see Command
3643               modifiers).  The result that is shown in case of errors is al‐
3644               ways the empty string, errors can be identified via the error
3645               number !.  For example, string length overflows are caught and
3646               set ! to ^ERR-OVERFLOW.  The TLS configuration is honoured, es‐
3647               pecially tls-verify.
3648
3649                     ? vput tls result fingerprint pop3s://ex.am.ple
3650                     ? echo $?/$!/$^ERRNAME: $result
3651
3652               certchain Show the complete verified peer certificate chain.
3653                         Includes informational fields in conjunction with
3654                         verbose.
3655
3656               certificate Show only the peer certificate, without any sign‐
3657                         ers.  Includes informational fields in conjunction
3658                         with verbose.
3659
3660               fingerprint Show the tls-fingerprint-digested fingerprint of
3661                         the certificate of the given HOST (‘server:port’,
3662                         where the port defaults to the HTTPS port, 443).
3663                         tls-fingerprint is actively ignored for the runtime
3664                         of this command.
3665
3666     Top       Like top but always uses the headerpick ‘type’ slot for white-
3667               and blacklisting header fields.
3668
3669     top       (to) Takes a message list and types out the first toplines
3670               lines of each message on the user's terminal.  Unless a special
3671               selection has been established for the ‘top’ slot of the
3672               headerpick command, the only header fields that are displayed
3673               are ‘From:’, ‘To:’, ‘Cc:’, and ‘Subject:’.  Top will always use
3674               the ‘type’ headerpick selection instead.  It is possible to ap‐
3675               ply compression to what is displayed by setting topsqueeze.
3676               Messages are decrypted and converted to the terminal character
3677               set if necessary.
3678
3679     touch     (tou) Takes a message list and marks the messages for saving in
3680               the secondary mailbox MBOX.  S-nail deviates from the POSIX
3681               standard with this command, as a following next command will
3682               display the following message instead of the current one.
3683
3684     Type      (T) Like type but also displays header fields which would not
3685               pass the headerpick selection, and all visualizable parts of
3686               MIME ‘multipart/alternative’ messages.
3687
3688     type      (t) Takes a message list and types out each message on the
3689               user's terminal.  The display of message headers is selectable
3690               via headerpick.  For MIME multipart messages, all parts with a
3691               content type of ‘text’, all parts which have a registered MIME
3692               type handler (see HTML mail and MIME attachments) which pro‐
3693               duces plain text output, and all ‘message’ parts are shown,
3694               others are hidden except for their headers.  Messages are de‐
3695               crypted and converted to the terminal character set if neces‐
3696               sary.  The command mimeview can be used to display parts which
3697               are not displayable as plain text.
3698
3699     unaccount
3700               See account.
3701
3702     unalias   (una) See alias.
3703
3704     unanswered
3705               See answered.
3706
3707     unbind    See bind.
3708
3709     uncollapse
3710               See collapse.
3711
3712     uncolour  See colour.
3713
3714     undefine  See define.
3715
3716     undelete  See delete.
3717
3718     undraft   See draft.
3719
3720     unflag    See flag.
3721
3722     unfwdignore
3723               [Obsolete] Superseded by the multiplexer headerpick.
3724
3725     unfwdretain
3726               [Obsolete] Superseded by the multiplexer headerpick.
3727
3728     unignore  Superseded by the multiplexer headerpick.
3729
3730     unmimetype
3731               See mimetype.
3732
3733     unmlist   See mlist.
3734
3735     unmlsubscribe
3736               See mlsubscribe.
3737
3738     Unread    Same as unread.
3739
3740     unread    Takes a message list and marks each message as not having been
3741               read.
3742
3743     unretain  Superseded by the multiplexer headerpick.
3744
3745     unsaveignore
3746               [Obsolete] Superseded by the multiplexer headerpick.
3747
3748     unsaveretain
3749               [Obsolete] Superseded by the multiplexer headerpick.
3750
3751     unset     [Only new quoting rules] (uns) See set.
3752
3753     unshortcut
3754               See shortcut.
3755
3756     unsort    See short.
3757
3758     unthread  [Obsolete] Same as unsort.
3759
3760     urlcodec  Perform URL percent codec operations on the raw-data argument,
3761               rather according to RFC 3986.  The first argument specifies the
3762               operation: e[ncode] or d[ecode] perform plain URL percent en-
3763               and decoding, respectively.  p[ath]enc[ode] and p[ath]dec[ode]
3764               perform a slightly modified operation which should be better
3765               for pathnames: it does not allow a tilde ‘~’, and will neither
3766               accept hyphen-minus ‘-’ nor dot ‘’.  as an initial character.
3767               The remains of the line form the URL data which is to be con‐
3768               verted.  This is a character set agnostic operation, and it may
3769               thus decode bytes which are invalid in the current ttycharset.
3770
3771               Supports vput (see Command modifiers), and manages the error
3772               number !.  If the coding operation fails the error number ! is
3773               set to ^ERR-CANCELED, and the unmodified input is used as the
3774               result; the error number may change again due to output or re‐
3775               sult storage errors.  [v15 behaviour may differ] This command
3776               does not know about URLs beside what is documented.  (vexpr of‐
3777               fers a makeprint subcommand, shall the URL be displayed.)
3778
3779     varshow   [Only new quoting rules] This command produces the same output
3780               as the listing mode of set, including verboseity adjustments,
3781               but only for the given variables.
3782
3783     verify    [Option] Takes a message list and verifies each message.  If a
3784               message is not a S/MIME signed message, verification will fail
3785               for it.  The verification process checks if the message was
3786               signed using a valid certificate, if the message sender's email
3787               address matches one of those contained within the certificate,
3788               and if the message content has been altered.
3789
3790     version   Shows the version and features of S-nail, optionally in a more
3791               verbose form which also includes the build and running system
3792               environment.  This command supports vput (see Command
3793               modifiers).
3794
3795     vexpr     [Only new quoting rules] A multiplexer command which offers
3796               signed 64-bit numeric calculations, as well as other, mostly
3797               string-based operations.  C-style byte string operations are
3798               available via csop.  The first argument defines the number,
3799               type, and meaning of the remaining arguments.  An empty number
3800               argument is treated as 0.  Supports vput (see Command
3801               modifiers).  The result shown in case of errors is ‘-1’ for us‐
3802               age errors and numeric operations, the empty string otherwise;
3803               “soft” errors, like when a search operation failed, will also
3804               set the ! error number to ^ERR-NODATA.  Except when otherwise
3805               noted numeric arguments are parsed as signed 64-bit numbers,
3806               and errors will be reported in the error number ! as the nu‐
3807               meric error ^ERR-RANGE.
3808
3809               Numeric operations work on one or two signed 64-bit integers.
3810               Numbers prefixed with ‘0x’ or ‘0X’ are interpreted as hexadeci‐
3811               mal (base 16) numbers, whereas ‘0’ indicates octal (base 8),
3812               and ‘0b’ as well as ‘0B’ denote binary (base 2) numbers.  It is
3813               possible to use any base in between 2 and 36, inclusive, with
3814               the ‘BASE#number’ notation, where the base is given as an un‐
3815               signed decimal number, so ‘16#AFFE’ is a different way of spec‐
3816               ifying a hexadecimal number.  Unsigned interpretation of a num‐
3817               ber can be enforced by prefixing an ‘u’ (case-insensitively),
3818               as in ‘u-110’; this is not necessary for power-of-two bases (2,
3819               4, 8, 16 and 32), which will be interpreted as unsigned by de‐
3820               fault, but it still makes a difference regarding overflow de‐
3821               tection and overflow constant.  It is possible to enforce
3822               signed interpretation by (instead) prefixing a ‘s’ (case-insen‐
3823               sitively).  The number sign notation uses a permissive parse
3824               mode and as such supports complicated conditions out of the
3825               box:
3826
3827                     ? wysh set ifs=:;read i;unset ifs;echo $i;vexpr pb 2 10#$i
3828                        -009
3829                     <   -009>
3830                     0b1001
3831
3832               One integer is expected by assignment (equals sign ‘=’), which
3833               does nothing but parsing the argument, thus detecting validity
3834               and possible overflow conditions, unary not (tilde ‘~’), which
3835               creates the bitwise complement, and unary plus and minus.  Two
3836               integers are used by addition (plus sign ‘+’), subtraction (hy‐
3837               phen-minus ‘-’), multiplication (asterisk ‘*’), division
3838               (solidus ‘/’) and modulo (percent sign ‘%’), as well as for the
3839               bitwise operators logical or (vertical bar ‘|’, to be quoted) ,
3840               bitwise and (ampersand ‘&’, to be quoted) , bitwise xor (cir‐
3841               cumflex ‘^’), the bitwise signed left- and right shifts (‘<<’,
3842               ‘>>’), as well as for the unsigned right shift ‘>>>’.
3843
3844               Another numeric operation is pbase, which takes a number base
3845               in between 2 and 36, inclusive, and will act on the second num‐
3846               ber given just the same as what equals sign ‘=’ does, but the
3847               number result will be formatted in the base given, as a signed
3848               64-bit number unless unsigned interpretation of the input num‐
3849               ber had been forced (with an u prefix).
3850
3851               Numeric operations support a saturated mode via the question
3852               mark ‘?’ modifier suffix; the keyword ‘saturated’ is optional,
3853               ‘+?’, ‘+?satu’, and ‘+?saturated’ are therefore identical.  In
3854               saturated mode overflow errors and division and modulo by zero
3855               are no longer reported via the exit status, but the result will
3856               linger at the minimum or maximum possible value, instead of
3857               overflowing (or trapping).  This is true also for the argument
3858               parse step.  For the bitwise shifts, the saturated maximum is
3859               63.  Any caught overflow will be reported via the error number
3860               ! as ^ERR-OVERFLOW.
3861
3862                     ? vput vexpr res -? +1 -9223372036854775808
3863                     ? echo $?/$!/$^ERRNAME:$res
3864                     0/75/OVERFLOW:-9223372036854775808
3865
3866               Character set agnostic string functions have no notion of lo‐
3867               cale settings and character sets.
3868
3869               date-utc  Outputs the current date and time in UTC (Coordinated
3870                         Universal Time) with values named such that ‘vput
3871                         vexpr x date-utc; eval wysh set $x’ creates accessi‐
3872                         ble variables.
3873
3874               date-stamp-utc Outputs a RFC 3339 internet date/time format of
3875                         UTC.
3876
3877               epoch     The seconds and nanoseconds since the Unix epoch
3878                         (1970-01-01T00:00:00) named ‘epoch_sec’ and
3879                         ‘epoch_nsec’ such that ‘vput vexpr x epoch; eval wysh
3880                         set $x’ creates accessible variables.
3881
3882               file-expand Performs the usual Filename transformations on its
3883                         argument.
3884
3885               file-stat, file-lstat Perform the usual Filename
3886                         transformations on the argument, then call stat(2)
3887                         and lstat(2), respectively, and output values such
3888                         that ‘vput vexpr x file-stat FILE; eval wysh set $x’
3889                         creates accessible variables.  The variable ‘st_type’
3890                         uses solidus ‘/’ to denote directories, commercial at
3891                         ‘@’ for links, number sign ‘#’ for block devices,
3892                         percent sign ‘%’ for for character devices, vertical
3893                         bar ‘|’ for FIFOs, equal sign ‘=’ for sockets, and
3894                         the period ‘.’ for the rest.
3895
3896               random    Generates a random string of the given length, or of
3897                         PATH_MAX bytes (a constant from /usr/include) if the
3898                         value 0 is given; the random string will be base64url
3899                         encoded according to RFC 4648, and thus be usable as
3900                         a (portable) filename.
3901
3902               String operations work, sufficient support provided, according
3903               to the active user's locale encoding and character set (see
3904               Character sets).  Where the question mark ‘?’ modifier suffix
3905               is supported, a case-insensitive operation mode is available;
3906               the keyword ‘case’ is optional, ‘regex?’ and ‘regex?case’ are
3907               therefore identical.
3908
3909               makeprint (One-way) Converts the argument to something safely
3910                         printable on the terminal.
3911
3912               regex     [Option] A string operation that will try to match
3913                         the first argument with the regular expression given
3914                         as the second argument.  ‘?’ modifier suffix is sup‐
3915                         ported.  If the optional third argument has been
3916                         given then instead of showing the match offset a re‐
3917                         placement operation is performed: the third argument
3918                         is treated as if specified within dollar-single-quote
3919                         (see Shell-style argument quoting), and any occur‐
3920                         rence of a positional parameter, for example 0, 1
3921                         etc. is replaced with the according match group of
3922                         the regular expression:
3923
3924                               ? vput vexpr res regex bananarama \
3925                                   (.*)NanA(.*) '\${1}au\$2'
3926                               ? echo $?/$!/$^ERRNAME:$res:
3927                               1/61/NODATA::
3928                               ? vput vexpr res regex?case bananarama \
3929                                   (.*)NanA(.*) '\${1}uauf\$2'
3930                               ? echo $?/$!/$^ERRNAME:$res:
3931                               0/0/NONE:bauauframa:
3932
3933     vpospar   [Only new quoting rules] Manage the positional parameter stack
3934               (see 1, #, *, @ as well as shift).  If the first argument is
3935               ‘clear’, then the positional parameter stack of the current
3936               context, or the global one, if there is none, is cleared.  If
3937               it is ‘set’, then the remaining arguments will be used to
3938               (re)create the stack, if the parameter stack size limit is ex‐
3939               cessed an ^ERR-OVERFLOW error will occur.
3940
3941               If the first argument is ‘quote’, a round-trip capable repre‐
3942               sentation of the stack contents is created, with each quoted
3943               parameter separated from each other with the first character of
3944               ifs, and followed by the first character of if-ws, if that is
3945               not empty and not identical to the first.  If that results in
3946               no separation at all a space character is used.  This mode sup‐
3947               ports vput (see Command modifiers).  I.e., the subcommands
3948               ‘set’ and ‘quote’ can be used (in conjunction with eval) to
3949               (re)create an argument stack from and to a single variable
3950               losslessly.
3951
3952                     ? vpospar set hey, "'you    ", world!
3953                     ? echo $#: <${1}><${2}><${3}>
3954                     ? vput vpospar x quote
3955                     ? vpospar clear
3956                     ? echo $#: <${1}><${2}><${3}>
3957                     ? eval vpospar set ${x}
3958                     ? echo $#: <${1}><${2}><${3}>
3959
3960     visual    (v) Takes a message list and invokes the VISUAL display editor
3961               on each message.  Modified contents are discarded unless the
3962               writebackedited variable is set, and are not used unless the
3963               mailbox can be written to and the editor returns a successful
3964               exit status.  edit can be used instead for a less display ori‐
3965               ented editor.
3966
3967     write     (w) For conventional messages the body without all headers is
3968               written.  The original message is never marked for deletion in
3969               the originating mail folder.  The output is decrypted and con‐
3970               verted to its native format as necessary.  If the output file
3971               exists, the text is appended.  If a message is in MIME multi‐
3972               part format its first part is written to the specified file as
3973               for conventional messages, handling of the remains depends on
3974               the execution mode.  No special handling of compressed files is
3975               performed.
3976
3977               In interactive mode the user is consecutively asked for the
3978               filenames of the processed parts.  For convenience saving of
3979               each part may be skipped by giving an empty value, the same re‐
3980               sult as writing it to /dev/null.  Shell piping the part content
3981               by specifying a leading vertical bar ‘|’ character for the
3982               filename is supported.  Other user input undergoes the usual
3983               Filename transformations, including shell pathname wildcard
3984               pattern expansions (glob(7)) and shell variable expansion for
3985               the message as such, not the individual parts, and contents of
3986               the destination file are overwritten if the file previously ex‐
3987               isted.  Character set conversion to ttycharset is performed
3988               when saving text data.
3989
3990               [v15 behaviour may differ] In non-interactive mode any part
3991               which does not specify a filename is ignored, and suspicious
3992               parts of filenames of the remaining parts are URL percent en‐
3993               coded (as via urlcodec) to prevent injection of malicious char‐
3994               acter sequences, resulting in a filename that will be written
3995               into the current directory.  Existing files will not be over‐
3996               written, instead the part number or a dot are appended after a
3997               number sign ‘#’ to the name until file creation succeeds (or
3998               fails due to other reasons).
3999
4000     xcall     [Only new quoting rules] The sole difference to call is that
4001               the new macro is executed in place of the current one, which
4002               will not regain control: all resources of the current macro
4003               will be released first.  This implies that any setting covered
4004               by localopts will be forgotten and covered variables will be‐
4005               come cleaned up.  If this command is not used from within a
4006               called macro it will silently be (a more expensive variant of)
4007               call.
4008
4009     xit       (x) A synonym for exit.
4010
4011     z         [Only new quoting rules] S-nail presents message headers in
4012               screenfuls as described under the headers command.  Without ar‐
4013               guments this command scrolls to the next window of messages,
4014               likewise if the argument is ‘+’.  An argument of ‘-’ scrolls to
4015               the last, ‘^’ scrolls to the first, and ‘$’ to the last screen
4016               of messages.  A number argument prefixed by ‘+’ or ‘-’ indi‐
4017               cates that the window is calculated in relation to the current
4018               position, and a number without a prefix specifies an absolute
4019               position.
4020
4021     Z         [Only new quoting rules] Similar to z, but scrolls to the next
4022               or previous window that contains at least one ‘new’ or flagged
4023               message.
4024

COMMAND ESCAPES

4026     Command escapes are available in Compose mode during interactive usage,
4027     when explicitly requested via -~, and in batch mode (-#).  They perform
4028     special functions, like editing headers of the message being composed,
4029     calling normal COMMANDS, yielding a shell, etc.  Command escapes are only
4030     recognized at the beginning of lines, and consist of an escape followed
4031     by a command character.  The default escape character is the tilde ‘~’.
4032
4033     Unless otherwise documented command escapes ensure proper updates of the
4034     error number ! and the exit status ?.  The variable errexit controls
4035     whether a failed operation errors out message compose mode and causes
4036     program exit.  Escapes may be prefixed by none to multiple single charac‐
4037     ter command modifiers, interspersed whitespace is ignored:
4038
4039     An effect equivalent to the command modifier ignerr can be achieved
4040         with hyphen-minus ‘-’, overriding errexit.
4041
4042     The modifier dollar ‘$’ evaluates the remains of the line; also see
4043         Shell-style argument quoting.  [v15 behaviour may differ] For now the
4044         entire input line is evaluated as a whole; to avoid that control op‐
4045         erators like semicolon ; are interpreted unintentionally, they must
4046         be quoted.
4047
4048     Addition of the command line to the [Option]al history can be prevented
4049     by placing whitespace directly after escape.  The [Option]al key bindings
4050     support a compose mode specific context.  The following command escapes
4051     are supported:
4052
4053     ~~ string
4054               Insert the string of text in the message prefaced by a single
4055               ‘~’.  (If the escape character has been changed, that character
4056               must be doubled instead.)
4057
4058     ~! command
4059               Execute the indicated shell command which follows, replacing
4060               unescaped exclamation marks with the previously executed com‐
4061               mand if the internal variable bang is set, then return to the
4062               message.
4063
4064     ~.        End compose mode and send the message.  The hooks
4065               on-compose-splice-shell and on-compose-splice, in order, will
4066               be called when set, after which, in interactive mode askatend
4067               (leading to askcc, askbcc) and askattach will be checked as
4068               well as asksend, after which a set on-compose-leave hook will
4069               be called, autocc and autobcc will be joined in if set, finally
4070               a given message-inject-tail will be incorporated, after which
4071               the compose mode is left.
4072
4073     ~: S-nail-command or ~_ S-nail-command
4074               Can be used to execute COMMANDS (which are allowed in compose
4075               mode).
4076
4077     ~< filename
4078               Identical to ~r.
4079
4080     ~<! command
4081               command is executed using the shell.  Its standard output is
4082               inserted into the message.
4083
4084     ~?        [Option] Write a summary of command escapes.
4085
4086     ~@ [filename...]
4087               Append or edit the list of attachments.  Does not manage the
4088               error number ! and the exit status ? (please use ~^ if error
4089               handling is necessary).  The append mode expects a list of
4090               filename arguments as shell tokens (see Shell-style argument
4091               quoting; token-separating commas are ignored, too), to be in‐
4092               terpreted as documented for the command line option -a, with
4093               the message number exception as below.
4094
4095               Without filename arguments the attachment list is edited, entry
4096               by entry; if a filename is left empty, that attachment is
4097               deleted from the list; once the end of the list is reached ei‐
4098               ther new attachments may be entered or the session can be quit
4099               by committing an empty “new” attachment.  In non-interactive
4100               mode or in batch mode (-#) the list of attachments is effec‐
4101               tively not edited but instead recreated; again, an empty input
4102               ends list creation.
4103
4104               For all modes, if a given filename solely consists of the num‐
4105               ber sign ‘#’ followed by either a valid message number of the
4106               currently active mailbox, or by a period ‘.’, referring to the
4107               current message of the active mailbox, the so-called “dot”,
4108               then the given message is attached as a ‘message/rfc822’ MIME
4109               message part.  The number sign must be quoted to avoid misin‐
4110               terpretation as a shell comment character.
4111
4112     ~| command
4113               Pipe the message text through the specified filter command.  If
4114               the command gives no output or terminates abnormally, retain
4115               the original text of the message.  The command fmt(1) is often
4116               used as a rejustifying filter.
4117
4118               If the first character of the command is a vertical bar, then
4119               the entire message including header fields is subject to the
4120               filter command, so ‘~|| echo Fcc: /tmp/test; cat’ will prepend
4121               a file-carbon-copy message header.  Also see ~e, ~v.
4122
4123     ~^ cmd [subcmd [arg3 [arg4]]]
4124               Inspect and modify the message using the semantics of digmsg,
4125               therefore arguments are evaluated according to Shell-style
4126               argument quoting.  Error number ! and exit status ? are not
4127               managed: errors are handled via the protocol, and hard errors
4128               like I/O failures cannot be handled.
4129
4130               The protocol consists of command lines followed by (a) response
4131               line(s).  The first field of the response line represents a
4132               status code which specifies whether a command was successful or
4133               not, whether result data is to be expected, and if, the format
4134               of the result data.  Response data will be shell quoted as nec‐
4135               essary for consumption by readsh, or eval and vpospar, to name
4136               a few.  Error status code lines may optionally contain addi‐
4137               tional context:
4138
4139               ‘210’     Status ok; the remains of the line are the result.
4140               ‘211’     Status ok; the rest of the line is optionally used
4141                         for more status.  What follows are lines of result
4142                         addresses, terminated by an empty line.  All the in‐
4143                         put, including the empty line, must be consumed be‐
4144                         fore further commands can be issued.  Address lines
4145                         consist of two token, first the plain network ad‐
4146                         dress, e.g., ‘bob@exam.ple’, followed by the (quoted)
4147                         full address as known: ‘'(Lovely) Bob
4148                         <bob@exam.ple>'’.  Non-network addresses use the
4149                         first field to indicate the type (hyphen-minus ‘-’
4150                         for files, vertical bar ‘|’ for pipes, and number
4151                         sign ‘#’ for names which will undergo alias process‐
4152                         ing) instead, the actual value will be in the second
4153                         field.
4154               ‘212’     Status ok; the rest of the line is optionally used
4155                         for more status.  What follows are lines of furtherly
4156                         unspecified (quoted) string content, terminated by an
4157                         empty line.  All the input, including the empty line,
4158                         must be consumed before further commands can be is‐
4159                         sued.
4160               ‘500’     Syntax error; invalid command.
4161               ‘501’     Syntax error or otherwise invalid parameters or argu‐
4162                         ments.
4163               ‘505’     Error: an argument fails verification.  For example
4164                         an invalid address has been specified (also see
4165                         expandaddr), or an attempt was made to modify any‐
4166                         thing in S-nail's own namespace, or a modifying sub‐
4167                         command has been used on a read-only message.
4168               ‘506’     Error: an otherwise valid argument is rendered in‐
4169                         valid due to context.  For example, a second address
4170                         is added to a header which may consist of a single
4171                         address only.
4172
4173               If a command indicates failure then the message will have re‐
4174               mained unmodified.  Most commands can fail with ‘500’ if re‐
4175               quired arguments are missing, or excessive arguments have been
4176               given (false command usage).  ([v15 behaviour may differ] The
4177               latter does not yet occur regularly, because as stated in
4178               Shell-style argument quoting our argument parser is not yet
4179               smart enough to work on subcommand base; for example one might
4180               get excess argument error for a three argument subcommand that
4181               receives four arguments, but not for a four argument subcommand
4182               which receives six arguments: here excess will be joined.)  The
4183               following (case-insensitive) commands are supported:
4184
4185               attachment This command allows listing, removal and addition of
4186                        message attachments.  The second argument specifies
4187                        the subcommand to apply, one of:
4188
4189                        attribute This uses the same search mechanism as de‐
4190                                  scribed for remove and prints any known at‐
4191                                  tributes of the first found attachment via
4192                                  ‘212’ upon success or ‘501’ if no such at‐
4193                                  tachment can be found.  The attributes are
4194                                  written as lines with a keyword and a value
4195                                  token.
4196
4197                        attribute-at This uses the same search mechanism as
4198                                  described for remove-at and is otherwise
4199                                  identical to attribute.
4200
4201                        attribute-set This uses the same search mechanism as
4202                                  described for remove, and will set the at‐
4203                                  tribute given as the fourth to the value
4204                                  given as the fifth token argument.  If the
4205                                  value is an empty token, then the given at‐
4206                                  tribute is removed, or reset to a default
4207                                  value if existence of the attribute is cru‐
4208                                  cial.
4209
4210                                  It returns via ‘210’ upon success, with the
4211                                  index of the found attachment following,
4212                                  ‘505’ for message attachments or if the
4213                                  given keyword is invalid, and ‘501’ if no
4214                                  such attachment can be found.  The following
4215                                  keywords may be used (case-insensitively):
4216
4217                                  ‘filename’  Sets the filename of the MIME
4218                                              part, i.e., the name that is
4219                                              used for display and when (sug‐
4220                                              gesting a name for) saving (pur‐
4221                                              poses).
4222                                  ‘content-description’ Associate some de‐
4223                                              scriptive information to the at‐
4224                                              tachment's content, used in
4225                                              favour of the plain filename by
4226                                              some MUAs.
4227                                  ‘content-id’ May be used for uniquely iden‐
4228                                              tifying MIME entities in several
4229                                              contexts; this expects a special
4230                                              reference address format as de‐
4231                                              fined in RFC 2045 and generates
4232                                              a ‘505’ upon address content
4233                                              verification failure.
4234                                  ‘content-type’ Defines the media type/sub‐
4235                                              type of the part, which is man‐
4236                                              aged automatically, but can be
4237                                              overwritten.
4238                                  ‘content-disposition’ Automatically set to
4239                                              the string ‘attachment’.
4240
4241                        attribute-set-at This uses the same search mechanism
4242                                  as described for remove-at and is otherwise
4243                                  identical to attribute-set.
4244
4245                        insert    Adds the attachment given as the third argu‐
4246                                  ment, specified exactly as documented for
4247                                  the command line option -a, and supporting
4248                                  the message number extension as documented
4249                                  for ~@.  This reports ‘210’ upon success,
4250                                  with the index of the new attachment follow‐
4251                                  ing, ‘505’ if the given file cannot be
4252                                  opened, ‘506’ if an on-the-fly performed
4253                                  character set conversion fails, otherwise
4254                                  ‘501’ is reported; this is also reported if
4255                                  character set conversion is requested but
4256                                  not available.
4257
4258                        list      List all attachments via ‘212’, or report
4259                                  ‘501’ if no attachments exist.  This command
4260                                  is the default command of attachment if no
4261                                  second argument has been given.
4262
4263                        remove    This will remove the attachment given as the
4264                                  third argument, and report ‘210’ upon suc‐
4265                                  cess or ‘501’ if no such attachment can be
4266                                  found.  If there exists any path component
4267                                  in the given argument, then an exact match
4268                                  of the path which has been used to create
4269                                  the attachment is used directly, but if only
4270                                  the basename of that path matches then all
4271                                  attachments are traversed to find an exact
4272                                  match first, and the removal occurs after‐
4273                                  wards; if multiple basenames match, a ‘506’
4274                                  error occurs.  Message attachments are
4275                                  treated as absolute pathnames.
4276
4277                                  If no path component exists in the given ar‐
4278                                  gument, then all attachments will be
4279                                  searched for ‘filename=’ parameter matches
4280                                  as well as for matches of the basename of
4281                                  the path which has been used when the at‐
4282                                  tachment has been created; multiple matches
4283                                  result in a ‘506’.
4284
4285                        remove-at This will interpret the third argument as a
4286                                  number and remove the attachment at that
4287                                  list position (counting from one!), report‐
4288                                  ing ‘210’ upon success or ‘505’ if the argu‐
4289                                  ment is not a number or ‘501’ if no such at‐
4290                                  tachment exists.
4291
4292               header   This command allows listing, inspection, and editing
4293                        of message headers.  Header name case is not normal‐
4294                        ized, so that case-insensitive comparison should be
4295                        used when matching names.  The second argument speci‐
4296                        fies the subcommand to apply, one of:
4297
4298                        insert    Create a new or an additional instance of
4299                                  the header given in the third argument, with
4300                                  the header body content as given in the
4301                                  fourth token.  It may return ‘501’ if the
4302                                  third argument specifies a free-form header
4303                                  field name that is invalid, or if body con‐
4304                                  tent extraction fails to succeed, ‘505’ if
4305                                  any extracted address does not pass syntax
4306                                  and/or security checks or on S-nail name‐
4307                                  space violations, and ‘506’ to indicate pre‐
4308                                  vention of excessing a single-instance
4309                                  header — note that ‘Subject:’ can be ap‐
4310                                  pended to (a space separator will be added
4311                                  automatically first).  ‘To:’, ‘Cc:’ and
4312                                  ‘Bcc:’ support the ‘?single’ modifier to en‐
4313                                  force treatment as a single addressee, for
4314                                  example ‘header insert To?single: 'exa,
4315                                  <m@ple>'’; the word ‘single’ is optional.
4316
4317                                  ‘210’ is returned upon success, followed by
4318                                  the name of the header and the list position
4319                                  of the newly inserted instance.  The list
4320                                  position is always 1 for single-instance
4321                                  header fields.  All free-form header fields
4322                                  are managed in a single list; also see
4323                                  customhdr.
4324
4325                        list      Without a third argument a list of all yet
4326                                  existing headers is given via ‘210’; this
4327                                  command is the default command of header if
4328                                  no second argument has been given.  A third
4329                                  argument restricts output to the given
4330                                  header only, which may fail with ‘501’ if no
4331                                  such field is defined.
4332
4333                        remove    This will remove all instances of the header
4334                                  given as the third argument, reporting ‘210’
4335                                  upon success, ‘501’ if no such header can be
4336                                  found, and ‘505’ on S-nail namespace viola‐
4337                                  tions.
4338
4339                        remove-at This will remove from the header given as
4340                                  the third argument the instance at the list
4341                                  position (counting from one!) given with the
4342                                  fourth argument, reporting ‘210’ upon suc‐
4343                                  cess or ‘505’ if the list position argument
4344                                  is not a number or on S-nail namespace vio‐
4345                                  lations, and ‘501’ if no such header in‐
4346                                  stance exists.
4347
4348                        show      Shows the content of the header given as the
4349                                  third argument.  Dependent on the header
4350                                  type this may respond with ‘211’ or ‘212’;
4351                                  any failure results in ‘501’.
4352
4353                        In compose-mode read-only access to optional pseudo
4354                        headers in the S-nail private namespace is available:
4355
4356                        ‘Mailx-Command:’
4357                                  The name of the command that generates the
4358                                  message, one of ‘forward’, ‘Lreply’, ‘mail’,
4359                                  ‘Reply’, ‘reply’, ‘resend’.  This pseudo
4360                                  header always exists (in compose-mode).
4361                        ‘Mailx-Raw-To:’
4362                        ‘Mailx-Raw-Cc:’
4363                        ‘Mailx-Raw-Bcc:’
4364                                  Represent the frozen initial state of these
4365                                  headers before any transformation (alias,
4366                                  alternates, recipients-in-cc etc.) took
4367                                  place.
4368                        ‘Mailx-Orig-Sender:’
4369                        ‘Mailx-Orig-From:’
4370                        ‘Mailx-Orig-To:’
4371                        ‘Mailx-Orig-Cc:’
4372                        ‘Mailx-Orig-Bcc:’
4373                                  The values of said headers of the original
4374                                  message which has been addressed by any of
4375                                  reply, forward, resend.  The sender field is
4376                                  special as it is filled in with the sole
4377                                  sender according to RFC 5322 rules, it may
4378                                  thus be equal to the from field.
4379
4380               help, ?  Show an abstract of the above commands via ‘211’.
4381
4382               version  This command will print the protocol version via
4383                        ‘210’.
4384
4385     ~A        The same as ‘~i Sign’.
4386
4387     ~a        The same as ‘~i sign’.
4388
4389     ~b name ...
4390               Add the given names to the list of blind carbon copy recipi‐
4391               ents.
4392
4393     ~c name ...
4394               Add the given names to the list of carbon copy recipients.
4395
4396     ~d        Read the file specified by the DEAD variable into the message.
4397
4398     ~e        Invoke the text EDITOR on the message collected so far, then
4399               return to compose mode.  ~v can be used for a more display ori‐
4400               ented editor, and ~|| offers a pipe-based editing approach.
4401
4402     ~F messages
4403               Read the named messages into the message being sent, including
4404               all message headers and MIME parts, and honouring
4405               forward-add-cc as well as forward-inject-head and
4406               forward-inject-tail.  If no messages are specified, read in the
4407               current message, the “dot”.
4408
4409     ~f messages
4410               Read the named messages into the message being sent.  If no
4411               messages are specified, read in the current message, the “dot”.
4412               Strips down the list of header fields according to the
4413               ‘forward’ (with posix: ‘type’) white- and blacklist selection
4414               of headerpick, and honours forward-add-cc as well as
4415               forward-inject-head and forward-inject-tail.  For MIME multi‐
4416               part messages, only the first displayable part is included.
4417
4418     ~H        In interactive mode, edit the message header fields ‘From:’,
4419               ‘Reply-To:’ and ‘Sender:’ by typing each one in turn and allow‐
4420               ing the user to edit the field.  The default values for these
4421               fields originate from the from, reply-to and sender variables.
4422               In non-interactive mode this sets ^ERR-NOTTY.
4423
4424     ~h        In interactive mode, edit the message header fields ‘To:’,
4425               ‘Cc:’, ‘Bcc:’ and ‘Subject:’ by typing each one in turn and al‐
4426               lowing the user to edit the field.  In non-interactive mode
4427               this sets ^ERR-NOTTY.
4428
4429     ~I variable
4430               Insert the value of the specified variable into the message.
4431               The message remains unaltered if the variable is unset or
4432               empty.  Any embedded character sequences ‘\t’ horizontal tabu‐
4433               lator and ‘\n’ line feed are expanded in posix mode; otherwise
4434               the expansion should occur at set time ([v15 behaviour may dif‐
4435               fer] by using the command modifier wysh).
4436
4437     ~i variable
4438               Like ~I, but appends a newline character.
4439
4440     ~M messages
4441               Read the named messages into the message being sent, indented
4442               by indentprefix.  If no messages are specified, read the cur‐
4443               rent message, the “dot”.  Honours forward-add-cc as well as
4444               forward-inject-head and forward-inject-tail.
4445
4446     ~m messages
4447               Read the named messages into the message being sent, indented
4448               by indentprefix.  If no messages are specified, read the cur‐
4449               rent message, the “dot”.  Strips down the list of header fields
4450               according to the ‘type’ white- and blacklist selection of
4451               headerpick.  Honours forward-add-cc as well as
4452               forward-inject-head and forward-inject-tail.  For MIME multi‐
4453               part messages, only the first displayable part is included.
4454
4455     ~p        Display the message collected so far, prefaced by the message
4456               header fields and followed by the attachment list, if any.
4457
4458     ~Q        Read in the given / current message(s) using the algorithm of
4459               quote (except that is implicitly assumed, even if not set),
4460               honouring quote-add-cc.
4461
4462     ~q        Abort the message being sent, copying it to the file specified
4463               by the DEAD variable if save is set.
4464
4465     ~R filename
4466               Identical to ~r, but indent each line that has been read by
4467               indentprefix.
4468
4469     ~r filename [HERE-delimiter]
4470               Read the named file, object to Filename transformations exclud‐
4471               ing shell globs and variable expansions, into the message; if
4472               filename is the hyphen-minus ‘-’ then standard input is used
4473               (for pasting, for example).  Only in this latter mode
4474               HERE-delimiter may be given: if it is data will be read in un‐
4475               til the given HERE-delimiter is seen on a line by itself, and
4476               encountering EOF is an error; the HERE-delimiter is a required
4477               argument in non-interactive mode; if it is single-quote quoted
4478               then the pasted content will not be expanded, [v15 behaviour
4479               may differ] otherwise a future version of S-nail may perform
4480               shell-style expansion on the content.
4481
4482     ~s string
4483               Cause the named string to become the current subject field.
4484               Newline (NL) and carriage-return (CR) bytes are invalid and
4485               will be normalized to space (SP) characters.
4486
4487     ~t name ...
4488               Add the given name(s) to the direct recipient list.
4489
4490     ~U messages
4491               Read in the given / current message(s) excluding all headers,
4492               indented by indentprefix.  Honours forward-add-cc as well as
4493               forward-inject-head and forward-inject-tail.
4494
4495     ~u messages
4496               Read in the given / current message(s), excluding all headers.
4497               Honours forward-add-cc as well as forward-inject-head and
4498               forward-inject-tail.
4499
4500     ~v        Invoke the VISUAL editor on the message collected so far, then
4501               return to compose mode.  ~e can be used for a less display ori‐
4502               ented editor, and ~|| offers a pipe-based editing approach.
4503
4504     ~w filename
4505               Write the message onto the named file, which is object to the
4506               usual Filename transformations.  If the file exists, the mes‐
4507               sage is appended to it.
4508
4509     ~x        Same as ~q, except that the message is not saved at all.
4510

INTERNAL VARIABLES

4512     Internal S-nail variables are controlled via the set and unset commands;
4513     prefixing a variable name with the string ‘no’ and calling set has the
4514     same effect as using unset: ‘unset crt’ and ‘set nocrt’ do the same
4515     thing.  varshow will give more insight on the given variable(s), and set,
4516     when called without arguments, will show a listing of all variables.
4517     Both commands support a more verbose listing mode.  Some well-known vari‐
4518     ables will also become inherited from the program ENVIRONMENT implicitly,
4519     others can be imported explicitly with the command environ and henceforth
4520     share said properties.
4521
4522     Two different kinds of internal variables exist, and both of which can
4523     also form chains.  There are boolean variables, which can only be in one
4524     of the two states “set” and “unset”, and value variables with a(n op‐
4525     tional) string value.  For the latter proper quoting is necessary upon
4526     assignment time, the introduction of the section COMMANDS documents the
4527     supported quoting rules.
4528
4529           ? wysh set one=val\ 1 two="val 2" \
4530               three='val "3"' four=$'val \'4\''; \
4531               varshow one two three four; \
4532               unset one two three four
4533
4534     Dependent upon the actual option string values may become interpreted as
4535     colour names, command specifications, normal text, etc.  They may be
4536     treated as numbers, in which case decimal values are expected if so docu‐
4537     mented, but otherwise any numeric format and base that is valid and un‐
4538     derstood by the vexpr command may be used, too.
4539
4540     There also exists a special kind of string value, the “boolean string”,
4541     which must either be a decimal integer (in which case ‘0’ is false and
4542     ‘1’ and any other value is true) or any of the (case-insensitive) strings
4543     ‘off’, ‘no’, ‘n’ and ‘false’ for a false boolean and ‘on’, ‘yes’, ‘y’ and
4544     ‘true’ for a true boolean; a special kind of boolean string is the
4545     “quadoption”: it can optionally be prefixed with the (case-insensitive)
4546     term ‘ask-’, as in ‘ask-yes’; in interactive mode the user will be
4547     prompted, otherwise the actual boolean is used.
4548
4549     Variable chains extend a plain ‘variable’ with ‘variable-HOST’ and
4550     ‘variable-USER@HOST’ variants.  Here ‘HOST’ will be converted to all low‐
4551     ercase when looked up (but not when the variable is set or unset!), [Op‐
4552     tion]ally IDNA converted, and indeed means ‘server:port’ if a ‘port’ had
4553     been specified in the contextual Uniform Resource Locator URL, see On URL
4554     syntax and credential lookup.  Even though this mechanism is based on
4555     URLs no URL percent encoding may be applied to neither of ‘USER’ nor
4556     ‘HOST’, variable chains need to be specified using raw data; the men‐
4557     tioned section contains examples.  Variables which support chains are ex‐
4558     plicitly documented as such, and S-nail treats the base name of any such
4559     variable special, meaning that users should not create custom names like
4560     ‘variable-xyz’ in order to avoid false classifications and treatment of
4561     such variables.
4562
4563   Initial settings
4564     The standard POSIX 2008/Cor 2-2016 mandates the following initial vari‐
4565     able settings: noallnet, noappend, asksub, noaskbcc, noautoprint, nobang,
4566     nocmd, nocrt, nodebug, nodot, escape set to ‘~’, noflipr, nofolder,
4567     header, nohold, noignore, noignoreeof, nokeep, nokeepsave, nometoo,
4568     nooutfolder, nopage, prompt set to ‘? ’, noquiet, norecord, save,
4569     nosendwait, noshowto, noSign, nosign, toplines set to ‘5’.
4570
4571     However, S-nail has built-in some initial (and some default) settings
4572     which (may) diverge, others may become adjusted by one of the Resource
4573     files.  Displaying the former is accomplished via set: ‘$ s-nail -:/ -v
4574     -Xset -Xx’.  In general this implementation sets (and has extended the
4575     meaning of) sendwait, and does not support the noonehop variable – use
4576     command line options or mta-arguments to pass options through to a mta.
4577     The default global resource file sets, among others, the variables hold,
4578     keep and keepsave, establishes a default headerpick selection etc., and
4579     should thus be taken into account.
4580
4581   Variables
4582     ?         (Read-only) The exit status of the last command, or the return
4583               value of the macro called last.  This status has a meaning in
4584               the state machine: in conjunction with errexit any non-0 exit
4585               status will cause a program exit, and in posix mode any error
4586               while loading (any of the) resource files will have the same
4587               effect.  ignerr, one of the Command modifiers, can be used to
4588               instruct the state machine to ignore errors.
4589
4590     !         (Read-only) The current error number (errno(3)), which is set
4591               after an error occurred; it is also available via ^ERR, and the
4592               error name and documentation string can be queried via ^ERRNAME
4593               and ^ERRDOC.  [v15 behaviour may differ] This machinery is new
4594               and the error number is only really usable if a command explic‐
4595               itly states that it manages the variable !, for others errno
4596               will be used in case of errors, or ^ERR-INVAL if that is 0: it
4597               thus may or may not reflect the real error.  The error number
4598               may be set with the command return.
4599
4600     ^         (Read-only) This is a multiplexer variable which performs dy‐
4601               namic expansion of the requested state or condition, of which
4602               there are:
4603
4604               ^ERR, ^ERRDOC, ^ERRNAME
4605                         The number, documentation, and name of the current
4606                         errno(3), respectively, which is usually set after an
4607                         error occurred.  The documentation is an [Option],
4608                         the name is used if not available.  [v15 behaviour
4609                         may differ] This machinery is new and is usually re‐
4610                         liable only if a command explicitly states that it
4611                         manages the variable !, which is effectively identi‐
4612                         cal to ^ERR.  Each of those variables can be suffixed
4613                         with a hyphen minus followed by a name or number, in
4614                         which case the expansion refers to the given error.
4615                         Note this is a direct mapping of (a subset of) the
4616                         system error values:
4617
4618                               define work {
4619                                 eval echo \$1: \$^ERR-$1:\
4620                                   \$^ERRNAME-$1: \$^ERRDOC-$1
4621                                 vput vexpr i + "$1" 1
4622                                 if [ $i -lt 16 ]
4623                                   \xcall work $i
4624                                 end
4625                               }
4626                               call work 0
4627
4628               ^ERRQUEUE-COUNT, ^ERRQUEUE-EXISTS
4629                         The number of messages in the [Option]al queue of
4630                         errors, and a string indicating queue state: empty or
4631                         (translated) “ERROR”.  Always 0 and the empty string,
4632                         respectively, unless features includes ‘,+errors,’.
4633
4634     *         (Read-only) Expands all positional parameters (see 1), sepa‐
4635               rated by the first character of the value of ifs.  [v15 behav‐
4636               iour may differ] The special semantics of the equally named
4637               special parameter of the sh(1) are not yet supported.
4638
4639     @         (Read-only) Expands all positional parameters (see 1), sepa‐
4640               rated by a space character.  If placed in double quotation
4641               marks, each positional parameter is properly quoted to expand
4642               to a single parameter again.
4643
4644     #         (Read-only) Expands to the number of positional parameters,
4645               i.e., the size of the positional parameter stack in decimal.
4646
4647     0         (Read-only) Inside the scope of a defined and called macro this
4648               expands to the name of the calling macro, or to the empty
4649               string if the macro is running from top-level.  For the [Op‐
4650               tion]al regular expression search and replace operator of vexpr
4651               this expands to the entire matching expression.  It represents
4652               the program name in global context.
4653
4654     1         (Read-only) Access of the positional parameter stack.  All fur‐
4655               ther parameters can be accessed with this syntax, too, ‘2’, ‘3’
4656               etc.; positional parameters can be shifted off the stack by
4657               calling shift.  The parameter stack contains, for example, the
4658               arguments of a called defined macro, the matching groups of the
4659               [Option]al regular expression search and replace expression of
4660               vexpr, and can be explicitly created or overwritten with the
4661               command vpospar.
4662
4663     account   (Read-only) Is set to the active account.
4664
4665     add-file-recipients
4666               (Boolean) When file or pipe recipients have been specified,
4667               mention them in the corresponding address fields of the message
4668               instead of silently stripping them from their recipient list.
4669               By default such addressees are not mentioned.
4670
4671     allnet    (Boolean) Causes only the local part to be evaluated when com‐
4672               paring addresses.
4673
4674     append    (Boolean) Causes messages saved in the secondary mailbox MBOX
4675               to be appended to the end rather than prepended.  This should
4676               always be set.
4677
4678     askatend  (Boolean) Causes the prompts for ‘Cc:’ and ‘Bcc:’ lists to ap‐
4679               pear after the message has been edited.
4680
4681     askattach
4682               (Boolean) If set, S-nail asks an interactive user for files to
4683               attach at the end of each message; An empty line finalizes the
4684               list.
4685
4686     askcc     (Boolean) Causes the interactive user to be prompted for carbon
4687               copy recipients (at the end of each message if askatend or
4688               bsdcompat are set).
4689
4690     askbcc    (Boolean) Causes the interactive user to be prompted for blind
4691               carbon copy recipients (at the end of each message if askatend
4692               or bsdcompat are set).
4693
4694     asksend   (Boolean) Causes the interactive user to be prompted for con‐
4695               firmation to send the message or reenter compose mode after
4696               having been shown a preliminary envelope summary.
4697
4698     asksign   (Boolean)[Option] Causes the interactive user to be prompted if
4699               the message is to be signed at the end of each message.  The
4700               smime-sign variable is ignored when this variable is set.
4701
4702     asksub    (Boolean) Causes S-nail to prompt the interactive user for the
4703               subject upon entering compose mode unless a subject already ex‐
4704               ists.
4705
4706     attrlist  A sequence of characters to display in the ‘attribute’ column
4707               of the headline as shown in the display of headers; each for
4708               one type of messages (see Message states), with the default be‐
4709               ing ‘NUROSPMFAT+-$~’ or ‘NU  *HMFAT+-$~’ if the bsdflags vari‐
4710               able is set, in the following order:
4711
4712               ‘N’       new.
4713               ‘U’       unread but old.
4714               ‘R’       new but read.
4715               ‘O’       read and old.
4716               ‘S’       saved.
4717               ‘P’       preserved.
4718               ‘M’       mboxed.
4719               ‘F’       flagged.
4720               ‘A’       answered.
4721               ‘T’       draft.
4722               ‘+’       [v15 behaviour may differ] start of a (collapsed)
4723                         thread in threaded mode (see autosort, thread);
4724               ‘-’       [v15 behaviour may differ] an uncollapsed thread in
4725                         threaded mode; only used in conjunction with -L.
4726               ‘$’       classified as spam.
4727               ‘~’       classified as possible spam.
4728
4729     autobcc   Specifies a list of recipients to which a blind carbon copy of
4730               each outgoing message will be sent automatically.
4731
4732     autocc    Specifies a list of recipients to which a carbon copy of each
4733               outgoing message will be sent automatically.
4734
4735     autocollapse
4736               (Boolean) Causes threads to be collapsed automatically when .Ql
4737               thread Ns ed sort mode is entered (see the collapse command).
4738
4739     autoprint
4740               (Boolean) Enable automatic typeing of a(n existing)
4741               “successive” message after delete and undelete commands: the
4742               message that becomes the new “dot” is shown automatically, as
4743               via dp or dt.
4744
4745     autosort  Causes sorted mode (see the sort command) to be entered auto‐
4746               matically with the value of this variable as sorting method
4747               when a folder is opened, for example ‘set autosort=thread’.
4748
4749     bang      (Boolean) Enables the substitution of all not (reverse-solidus)
4750               escaped exclamation mark ‘!’ characters by the contents of the
4751               last executed command for the ! shell escape command and ~!,
4752               one of the compose mode COMMAND ESCAPES.  If this variable is
4753               not set no reverse solidus stripping is performed.
4754
4755     bind-timeout
4756               [Obsolete] Predecessor of bind-inter-byte-timeout.  [v15 behav‐
4757               iour may differ] Setting this automatically sets the successor.
4758
4759     bind-inter-byte-timeout
4760               [Option] Terminals may generate multi-byte sequences for spe‐
4761               cial function keys, for example, but these sequences may not
4762               become read as a unit.  And multi-byte sequences can be defined
4763               freely via bind.  This variable specifies the timeout in mil‐
4764               liseconds that the MLE (see On terminal control and line
4765               editor) waits for more bytes to arrive unless it considers a
4766               sequence “complete”.  The default is 200, the maximum is about
4767               10 seconds.  In the following example the comments state which
4768               sequences are affected by this timeout:
4769
4770                     ? bind base abc echo 0 # abc
4771                     ? bind base ab,c echo 1 # ab
4772                     ? bind base abc,d echo 2 # abc
4773                     ? bind base ac,d echo 3 # ac
4774                     ? bind base a,b,c echo 4
4775                     ? bind base a,b,c,d echo 5
4776                     ? bind base a,b,cc,dd echo 6 # cc and dd
4777
4778     bind-inter-key-timeout
4779               [Option] Multi-key bind sequences do not time out by default.
4780               If this variable is set, then the current key sequence is
4781               forcefully terminated once the timeout (in milliseconds) trig‐
4782               gers.  The value should be (maybe significantly) larger than
4783               bind-inter-byte-timeout, but may not excess the maximum, too.
4784
4785     bsdcompat
4786               (Boolean) Sets some cosmetical features to traditional BSD
4787               style; has the same affect as setting askatend and all other
4788               variables prefixed with ‘bsd’; it also changes the behaviour of
4789               emptystart (which does not exist in BSD).
4790
4791     bsdflags  (Boolean) Changes the letters shown in the first column of a
4792               header summary to traditional BSD style.
4793
4794     bsdheadline
4795               (Boolean) Changes the display of columns in a header summary to
4796               traditional BSD style.
4797
4798     bsdmsgs   (Boolean) Changes some informational messages to traditional
4799               BSD style.
4800
4801     bsdorder  (Boolean) Causes the ‘Subject:’ field to appear immediately af‐
4802               ter the ‘To:’ field in message headers and with the ~h COMMAND
4803               ESCAPES.
4804
4805     build-cc, build-ld, build-os, build-rest
4806               (Read-only) The build environment, including the compiler, the
4807               linker, the operating system S-nail has been build for, usually
4808               taken from uname(1) via ‘uname -s’, and then lowercased, as
4809               well as all the possibly interesting rest of the configuration
4810               and build environment.  This information is also available in
4811               the verbose output of the command version.
4812
4813     charset-7bit
4814               The value that should appear in the ‘charset=’ parameter of
4815               ‘Content-Type:’ MIME header fields when no character set con‐
4816               version of the message data was performed.  This defaults to
4817               US-ASCII, and the chosen character set should be US-ASCII com‐
4818               patible.
4819
4820     charset-8bit
4821               [Option] The default 8-bit character set that is used as an im‐
4822               plicit last member of the variable sendcharsets.  This defaults
4823               to UTF-8 if character set conversion capabilities are avail‐
4824               able, and to ISO-8859-1 otherwise (unless the operating system
4825               environment is known to always and exclusively support UTF-8
4826               locales), in which case the only supported character set is
4827               ttycharset and this variable is effectively ignored.
4828
4829     charset-unknown-8bit
4830               [Option] RFC 1428 specifies conditions when internet mail gate‐
4831               ways shall “upgrade” the content of a mail message by using a
4832               character set with the name ‘unknown-8bit’.  Because of the un‐
4833               classified nature of this character set S-nail will not be ca‐
4834               pable to convert this character set to any other character set.
4835               If this variable is set any message part which uses the charac‐
4836               ter set ‘unknown-8bit’ is assumed to really be in the character
4837               set given in the value, otherwise the (final) value of
4838               charset-8bit is used for this purpose.
4839
4840               This variable will also be taken into account if a MIME type
4841               (see The mime.types files) of a MIME message part that uses the
4842               ‘binary’ character set is forcefully treated as text.
4843
4844     cmd       The default value for the pipe command.
4845
4846     colour-disable
4847               (Boolean)[Option] Forcefully disable usage of colours.  Also
4848               see the section Coloured display.
4849
4850     colour-pager
4851               (Boolean)[Option] Whether colour shall be used for output that
4852               is paged through PAGER.  Note that pagers may need special com‐
4853               mand line options, for example less(1) requires the option -R
4854               and lv(1) the option -c in order to support colours.  Often do‐
4855               ing manual adjustments is unnecessary since S-nail may perform
4856               adjustments dependent on the value of the environment variable
4857               PAGER (see there for more).
4858
4859     contact-mail, contact-web
4860               (Read-only) Addresses for contact per email and web, respec‐
4861               tively, for bug reports, suggestions, or anything else regard‐
4862               ing S-nail.  The former can be used directly: ‘? eval mail
4863               $contact-mail’.
4864
4865     content-description-forwarded-message,
4866               content-description-quote-attachment,
4867               content-description-smime-message,
4868               content-description-smime-signature
4869               [Option](partially) Strings which will be placed in according
4870               ‘Content-Description:’ headers if non-empty.  They all have de‐
4871               fault values, for example ‘Forwarded message’.
4872
4873     crt       In a(n interactive) terminal session, then if this valued vari‐
4874               able is set it will be used as a threshold to determine how
4875               many lines the given output has to span before it will be dis‐
4876               played via the configured PAGER; Usage of the PAGER can be
4877               forced by setting this to the value ‘0’, setting it without a
4878               value will deduce the current height of the terminal screen to
4879               compute the threshold (see LINES, screen and stty(1)).  [v15
4880               behaviour may differ] At the moment this uses the count of
4881               lines of the message in wire format, which, dependent on the
4882               mime-encoding of the message, is unrelated to the number of
4883               display lines.  (The software is old and historically the rela‐
4884               tion was a given thing.)
4885
4886     customhdr
4887               Define a set of custom headers to be injected into newly com‐
4888               posed or forwarded messages.  A custom header consists of the
4889               field name followed by a colon ‘:’ and the field content body.
4890               Standard header field names cannot be overwritten by a custom
4891               header, with the exception of ‘Comments:’ and ‘Keywords:’.
4892               Different to the command line option -C the variable value is
4893               interpreted as a comma-separated list of custom headers: to in‐
4894               clude commas in header bodies they need to become escaped with
4895               reverse solidus ‘\’.  Headers can be managed more freely in
4896               Compose mode via ~^.
4897
4898                     ? set customhdr='Hdr1: Body1-1\, Body1-2, Hdr2: Body2'
4899
4900     datefield
4901               Controls the appearance of the ‘%d’ date and time format speci‐
4902               fication of the headline variable, that is used, for example,
4903               when viewing the summary of headers.  If unset, then the local
4904               receiving date is used and displayed unformatted, otherwise the
4905               message sending ‘Date:’.  It is possible to assign a
4906               strftime(3) format string and control formatting, but embedding
4907               newlines via the ‘%n’ format is not supported, and will result
4908               in display errors.  The default is ‘%Y-%m-%d %H:%M’, and also
4909               see datefield-markout-older.
4910
4911     datefield-markout-older
4912               Only used in conjunction with datefield.  Can be used to create
4913               a visible distinction of messages dated more than a day in the
4914               future, or older than six months, a concept comparable to the
4915               -l option of the POSIX utility ls(1).  If set to the empty
4916               string, then the plain month, day and year of the ‘Date:’ will
4917               be displayed, but a strftime(3) format string to control for‐
4918               matting can be assigned.  The default is ‘%Y-%m-%d’.
4919
4920     debug     (Boolean) (Almost) Enter a debug-only sandbox mode which gener‐
4921               ates many log messages, disables the actual delivery of mes‐
4922               sages, and also implies norecord as well as nosave.  Also see
4923               verbose.
4924
4925     disposition-notification-send
4926               (Boolean)[Option] Emit a ‘Disposition-Notification-To:’ header
4927               (RFC 3798) with the message.  This requires the from variable
4928               to be set.
4929
4930     dot       (Boolean) When dot is set, a period ‘.’ on a line by itself
4931               during message input in (interactive or batch -#) Compose mode
4932               will be treated as end-of-message (in addition to the normal
4933               end-of-file condition).  This behaviour is implied in posix
4934               mode with a set ignoreeof.
4935
4936     dotlock-disable
4937               (Boolean)[Option] Disable creation of dotlock files for MBOX
4938               databases.
4939
4940     dotlock-ignore-error
4941               [Obsolete](Boolean)[Option] Ignore failures when creating
4942               dotlock files.  Please use dotlock-disable instead.
4943
4944     editalong
4945               If this variable is set then the editor is started automati‐
4946               cally when a message is composed in interactive mode.  If the
4947               value starts with the letter ‘v’ then this acts as if ~v, oth‐
4948               erwise as if ~e (see COMMAND ESCAPES) had been specified.  The
4949               editheaders variable is implied for this automatically spawned
4950               editor session.
4951
4952     editheaders
4953               (Boolean) When a message is edited while being composed, its
4954               header is included in the editable text.
4955
4956     emptystart
4957               (Boolean) When entering interactive mode S-nail normally writes
4958               “No mail for user” and exits immediately if a mailbox is empty
4959               or does not exist.  If this variable is set S-nail starts even
4960               with an empty or non-existent mailbox (the latter behaviour
4961               furtherly depends upon bsdcompat, though).
4962
4963     errexit   (Boolean) Let each command with a non-0 exit status, including
4964               every called macro which returns a non-0 status, cause a pro‐
4965               gram exit unless prefixed by ignerr (see Command modifiers).
4966               This also affects COMMAND ESCAPES, but which use a different
4967               modifier for ignoring the error.  Please refer to the variable
4968               ? for more on this topic.
4969
4970     errors-limit
4971               [Option] Maximum number of entries in the errors queue.
4972
4973     escape    The first character of this value defines the escape character
4974               for COMMAND ESCAPES in Compose mode.  The default value is the
4975               character tilde ‘~’.  If set to the empty string, command es‐
4976               capes are disabled.
4977
4978     expandaddr
4979               If unset only user name and email address recipients are al‐
4980               lowed On sending mail, and non-interactive mode.  If set with‐
4981               out value all possible recipient types will be accepted.  A
4982               value is parsed as a comma-separated list of case-insensitive
4983               strings, and if that contains ‘restrict’ behaviour equals the
4984               former except when in interactive mode or if COMMAND ESCAPES
4985               were enabled via -~ or -#, in which case it equals the latter,
4986               allowing all address types.  ‘restrict’ really acts like
4987               ‘restrict,-all,+name,+addr’, so care for ordering issues must
4988               be taken.
4989
4990               Recipient types can be added and removed with a plus sign ‘+’
4991               or hyphen-minus ‘-’ prefix, respectively.  By default invalid
4992               or disallowed types are filtered out and cause a warning, hard
4993               send errors need to be enforced by including ‘fail’.  The value
4994               ‘all’ covers all types, ‘fcc’ whitelists ‘Fcc:’ header targets
4995               regardless of other settings, ‘file’ file targets (it includes
4996               ‘fcc’), ‘pipe’ command pipeline targets, ‘name’ user names
4997               still unexpanded after alias and mta-aliases processing and
4998               thus left for expansion by the mta (invalid for the built-in
4999               SMTP one), and ‘addr’ network addresses.  Targets are inter‐
5000               preted in the given order, so that ‘restrict,fail,+file,-all,
5001               +addr’ will cause hard errors for any non-network address re‐
5002               cipient address unless running interactively or having been
5003               started with the option -~ or -#; in the latter case(s) any
5004               type may be used.
5005
5006               User name receivers addressing valid local users can be ex‐
5007               panded to fully qualified network addresses (also see hostname)
5008               by including ‘nametoaddr’ in the list.  Historically invalid
5009               recipients were stripped off without causing errors, this can
5010               be changed by making ‘failinvaddr’ an entry of the list (it re‐
5011               ally acts like ‘failinvaddr,+addr’).  Likewise, ‘domaincheck’
5012               (really ‘domaincheck,+addr’) compares address domain names
5013               against a whitelist and strips off (‘fail’ for hard errors) ad‐
5014               dressees which fail this test; the domain name ‘localhost’ and
5015               the non-empty value of hostname (the real hostname otherwise)
5016               are always whitelisted, expandaddr-domaincheck can be set to
5017               extend this list.  Finally some address providers (for example
5018               -b, -c and all other command line recipients) will be evaluated
5019               as if specified within dollar-single-quotes (see Shell-style
5020               argument quoting) if the value list contains the string
5021               ‘shquote’.
5022
5023     expandaddr-domaincheck
5024               Can be set to a comma-separated list of domain names which
5025               should be whitelisted for the evaluation of the ‘domaincheck’
5026               mode of expandaddr.  IDNA encoding is not automatically per‐
5027               formed, addrcodec can be used to prepare the domain (of an ad‐
5028               dress).
5029
5030     expandargv
5031               Unless this variable is set additional mta (Mail-Transfer-
5032               Agent) arguments from the command line, as can be given after a
5033               -- separator, results in a program termination with failure
5034               status.  The same can be accomplished by using the special
5035               (case-insensitive) value ‘fail’.  A lesser strict variant is
5036               the otherwise identical ‘restrict’, which does accept such ar‐
5037               guments in interactive mode, or if tilde commands were enabled
5038               explicitly by using one of the command line options -~ or -#.
5039               The empty value will allow unconditional usage.
5040
5041     features  (Read-only) String giving a list of optional features.  Fea‐
5042               tures are preceded with a plus sign ‘+’ if they are available,
5043               with a hyphen-minus ‘-’ otherwise.  To ease substring matching
5044               the string starts and ends with a comma.  The output of the
5045               command version includes this information in a more pleasant
5046               output.
5047
5048     flipr     (Boolean) This setting reverses the meanings of a set of reply
5049               commands, turning the lowercase variants, which by default ad‐
5050               dress all recipients included in the header of a message
5051               (reply, respond, followup) into the uppercase variants, which
5052               by default address the sender only (Reply, Respond, Followup)
5053               and vice versa.
5054
5055     folder    The default path under which mailboxes are to be saved: file‐
5056               names that begin with the plus sign ‘+’ will have the plus sign
5057               replaced with the value of this variable if set, otherwise the
5058               plus sign will remain unchanged when doing Filename
5059               transformations; also see folder for more on this topic, and
5060               know about standard imposed implications of outfolder.  The
5061               value supports a subset of transformations itself, and if the
5062               non-empty value does not start with a solidus ‘/’, then the
5063               value of HOME will be prefixed automatically.  Once the actual
5064               value is evaluated first, the internal variable folder-resolved
5065               will be updated for caching purposes.
5066
5067     folder-hook-FOLDER, folder-hook
5068               Names a defined macro which will be called whenever a folder is
5069               opened.  The macro will also be invoked when new mail arrives,
5070               but message lists for commands executed from the macro only in‐
5071               clude newly arrived messages then.  localopts are activated by
5072               default in a folder hook, causing the covered settings to be
5073               reverted once the folder is left again.
5074
5075               The specialized form will override the generic one if ‘FOLDER’
5076               matches the file that is opened.  Unlike other folder specifi‐
5077               cations, the fully expanded name of a folder, without metachar‐
5078               acters, is used to avoid ambiguities.  However, if the mailbox
5079               resides under folder then the usual ‘+’ specification is tried
5080               in addition, so that if folder is “mail” (and thus relative to
5081               the user's home directory) then /home/usr1/mail/sent will be
5082               tried as ‘folder-hook-/home/usr1/mail/sent’ first, but then
5083               followed by ‘folder-hook-+sent’.
5084
5085     folder-resolved
5086               (Read-only) Set to the fully resolved path of folder once that
5087               evaluation has occurred; rather internal.
5088
5089     followup-to
5090               (Boolean) Controls whether a ‘Mail-Followup-To:’ header is gen‐
5091               erated when sending messages to known mailing lists.  The user
5092               as determined via from (or, if that contains multiple ad‐
5093               dresses, sender) will be placed in there if any list addressee
5094               is not a subscribed list.  Also see followup-to-honour and the
5095               commands mlist, mlsubscribe, reply and Lreply.
5096
5097     followup-to-add-cc
5098               (Boolean) Controls whether the user will be added to the mes‐
5099               sages' ‘Cc:’ list in addition to placing an entry in
5100               ‘Mail-Followup-To:’ (see followup-to).
5101
5102     followup-to-honour
5103               Controls whether a ‘Mail-Followup-To:’ header is honoured when
5104               group-replying to a message via reply or Lreply.  This is a
5105               quadoption; if set without a value it defaults to “yes”, and
5106               see followup-to.
5107
5108     forward-add-cc
5109               (Boolean) Whether senders of messages forwarded via ~F, ~f, ~m,
5110               ~U or ~u shall be made members of the carbon copies ‘Cc:’ list.
5111
5112     forward-as-attachment
5113               (Boolean) Original messages are normally sent as inline text
5114               with the forward command, and only the first part of a multi‐
5115               part message is included.  With this setting enabled messages
5116               are sent as unmodified MIME ‘message/rfc822’ attachments with
5117               all of their parts included.
5118
5119     forward-inject-head, forward-inject-tail
5120               The strings to put before and after the text of a message with
5121               the forward command, respectively.  The former defaults to
5122               ‘-------- Original Message --------\n’.  Special format direc‐
5123               tives in these strings will be expanded if possible, and if so
5124               configured the output will be folded according to quote-fold;
5125               for more please refer to quote-inject-head.  Injections will
5126               not be performed by forward if the variable
5127               forward-as-attachment is set — the COMMAND ESCAPES ~F, ~f, ~M,
5128               ~m, ~U, ~u always inject.
5129
5130     from      The address (or a list of addresses) to put into the ‘From:’
5131               field of the message header, quoting RFC 5322: the author(s) of
5132               the message, that is, the mailbox(es) of the person(s) or sys‐
5133               tem(s) responsible for the writing of the message.  According
5134               to that RFC setting the sender variable is required if from
5135               contains more than one address.  [v15 behaviour may differ]
5136               Please expect automatic management of the from and sender rela‐
5137               tionship.  Dependent on the context these addresses are handled
5138               as if they were in the list of alternates.
5139
5140               If a file-based MTA is used, then from (or, if that contains
5141               multiple addresses, sender) can nonetheless be used as the en‐
5142               velope sender address at the MTA protocol level (the RFC 5321
5143               reverse-path), either via the -r command line option (without
5144               argument; see there for more), or by setting r-option-implicit.
5145
5146               If the machine's hostname is not valid at the Internet (for ex‐
5147               ample at a dialup machine), then either this variable or
5148               hostname ([v15-compat] a SMTP-based mta adds even more fine-
5149               tuning capabilities with smtp-hostname) have to be set: if so
5150               the message and MIME part related unique ID fields
5151               ‘Message-ID:’ and ‘Content-ID:’ will be created (except when
5152               disallowed by message-id-disable or stealthmua).
5153
5154     fullnames
5155               (Boolean) Due to historical reasons comments and name parts of
5156               email addresses are removed by default when sending mail, re‐
5157               plying to or forwarding a message.  If this variable is set
5158               such stripping is not performed.
5159
5160     fwdheading
5161               [Obsolete] Predecessor of forward-inject-head.
5162
5163     header    (Boolean) Causes the header summary to be written at startup
5164               and after commands that affect the number of messages or the
5165               order of messages in the current folder.  Unless in posix mode
5166               a header summary will also be displayed on folder changes.  The
5167               command line option -N can be used to set noheader.
5168
5169     headline  A format string to use for the summary of headers.  Format
5170               specifiers in the given string start with a percent sign ‘%’
5171               and may be followed by an optional decimal number indicating
5172               the field width — if that is negative, the field is to be left-
5173               aligned.  Names and addresses are subject to modifications ac‐
5174               cording to showname and showto.  Valid format specifiers are:
5175
5176               ‘%%’      A plain percent sign.
5177               ‘%>’      “Dotmark”: a space character but for the current mes‐
5178                         sage (“dot”), for which it expands to ‘>’ (dependent
5179                         on headline-plain).
5180               ‘%<’      “Dotmark”: a space character but for the current mes‐
5181                         sage (“dot”), for which it expands to ‘<’ (dependent
5182                         on headline-plain).
5183               ‘%$’      [Option] The spam score of the message, as has been
5184                         classified via the command spamrate.  Shows only a
5185                         replacement character if there is no spam support.
5186               ‘%a’      Message attribute character (status flag); the actual
5187                         content can be adjusted by setting attrlist.
5188               ‘%d’      The date found in the ‘Date:’ header of the message
5189                         when datefield is set (the default), otherwise the
5190                         date when the message was received.  Formatting can
5191                         be controlled by assigning a strftime(3) format
5192                         string to datefield (and datefield-markout-older).
5193               ‘%e’      The indenting level in ‘thread’ed sort mode.
5194               ‘%f’      The address of the message sender.
5195               ‘%i’      The message thread tree structure.  (Note that this
5196                         format does not support a field width, and honours
5197                         headline-plain.)
5198               ‘%L’      Mailing list status: is the addressee of the message
5199                         a known ‘l’ (mlist) or ‘L’ mlsubscribed mailing list?
5200                         The letter ‘P’ announces the presence of a RFC 2369
5201                         ‘List-Post:’ header, which makes a message a valuable
5202                         target of Lreply.
5203               ‘%l’      The number of lines of the message, if available.
5204               ‘%m’      Message number.
5205               ‘%o’      The number of octets (bytes) in the message, if
5206                         available.
5207               ‘%S’      Message subject (if any) in double quotes.
5208               ‘%s’      Message subject (if any).
5209               ‘%t’      The position in threaded/sorted order.
5210               ‘%U’      The value 0 except in an IMAP mailbox, where it ex‐
5211                         pands to the UID of the message.
5212
5213               The default is ‘%>%a%m %-18f %16d %4l/%-5o %i%-s’, or
5214               ‘%>%a%m %20-f  %16d %3l/%-5o %i%-S’ if bsdcompat is set.  Also
5215               see attrlist, headline-plain and headline-bidi.
5216
5217     headline-bidi
5218               Bidirectional text requires special treatment when displaying
5219               headers, because numbers (in dates or for file sizes etc.) will
5220               not affect the current text direction, in effect resulting in
5221               ugly line layouts when arabic or other right-to-left text is to
5222               be displayed.  On the other hand only a minority of terminals
5223               is capable to correctly handle direction changes, so that user
5224               interaction is necessary for acceptable results.  Note that ex‐
5225               tended host system support is required nonetheless, e.g., de‐
5226               tection of the terminal character set is one precondition; and
5227               this feature only works in an Unicode (i.e., UTF-8) locale.
5228
5229               In general setting this variable will cause S-nail to encapsu‐
5230               late text fields that may occur when displaying headline (and
5231               some other fields, like dynamic expansions in prompt) with spe‐
5232               cial Unicode control sequences; it is possible to fine-tune the
5233               terminal support level by assigning a value: no value (or any
5234               value other than ‘1’, ‘2’ and ‘3’) will make S-nail assume that
5235               the terminal is capable to properly deal with Unicode version
5236               6.3, in which case text is embedded in a pair of U+2068 (FIRST
5237               STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) charac‐
5238               ters.  In addition no space on the line is reserved for these
5239               characters.
5240
5241               Weaker support is chosen by using the value ‘1’ (Unicode 6.3,
5242               but reserve the room of two spaces for writing the control se‐
5243               quences onto the line).  The values ‘2’ and ‘3’ select Unicode
5244               1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter again re‐
5245               serves room for two spaces in addition.
5246
5247     headline-plain
5248               (Boolean) On Unicode (UTF-8) aware terminals enhanced graphical
5249               symbols are used by default for certain entries of headline.
5250               If this variable is set only basic US-ASCII symbols will be
5251               used.
5252
5253     history-file
5254               [Option] The (expandable) location of a permanent history file
5255               for the MLE line editor (On terminal control and line editor).
5256               Also see history-size.
5257
5258     history-gabby
5259               [Option] Add more entries to the MLE history as is normally
5260               done.  A comma-separated list of case-insensitive strings can
5261               be used to fine-tune which gabby entries shall be allowed.  If
5262               it contains ‘errors’, erroneous commands will also be added.
5263               ‘all’ adds all optional entries, and is the fallback chattiness
5264               identifier of on-history-addition.
5265
5266     history-gabby-persist
5267               (Boolean)[Option] The history-gabby entries will not be saved
5268               in persistent storage unless this variable is set.  The knowl‐
5269               edge of whether a persistent entry was gabby is not lost.  Also
5270               see history-file.
5271
5272     history-size
5273               [Option] Setting this variable imposes a limit on the number of
5274               concurrent history entries.  If set to the value 0 then no fur‐
5275               ther history entries will be added, and loading and incorpora‐
5276               tion of the history-file upon program startup can also be sup‐
5277               pressed by doing this.  Runtime changes will not be reflected
5278               before the history is saved or loaded (again).
5279
5280     hold      (Boolean) This setting controls whether messages are held in
5281               the system inbox, and it is set by default.
5282
5283     hostname  Used instead of the value obtained from uname(3) and
5284               getaddrinfo(3) as the hostname when expanding local addresses,
5285               for example in ‘From:’ (also see On sending mail, and non-
5286               interactive mode, for expansion of addresses that have a valid
5287               user-, but no domain name in angle brackets).  If either of
5288               from or this variable is set the message and MIME part related
5289               unique ID fields ‘Message-ID:’ and ‘Content-ID:’ will be cre‐
5290               ated (except when disallowed by message-id-disable or
5291               stealthmua).  If the [Option]al IDNA support is available (see
5292               idna-disable) variable assignment is aborted when a necessary
5293               conversion fails.
5294
5295               Setting it to the empty string will cause the normal hostname
5296               to be used, but nonetheless enables creation of said ID fields.
5297               [v15-compat] in conjunction with the built-in SMTP mta
5298               smtp-hostname also influences the results: one should produce
5299               some test messages with the desired combination of hostname,
5300               and/or from, sender etc. first.
5301
5302     idna-disable
5303               (Boolean)[Option] Can be used to turn off the automatic conver‐
5304               sion of domain names according to the rules of IDNA (interna‐
5305               tionalized domain names for applications).  Since the IDNA code
5306               assumes that domain names are specified with the ttycharset
5307               character set, an UTF-8 locale charset is required to represent
5308               all possible international domain names (before conversion,
5309               that is).
5310
5311     ifs       The input field separator that is used ([v15 behaviour may dif‐
5312               fer] by some functions) to determine where to split input data.
5313
5314               1.        Unsetting is treated as assigning the default value,
5315                         ‘ \t\n’.
5316               2.        If set to the empty value, no field splitting will be
5317                         performed.
5318               3.        If set to a non-empty value, all whitespace charac‐
5319                         ters are extracted and assigned to the variable
5320                         ifs-ws.
5321
5322               a.        ifs-ws will be ignored at the beginning and end of
5323                         input.  Diverging from POSIX shells default white‐
5324                         space is removed in addition, which is owed to the
5325                         entirely different line content extraction rules.
5326               b.        Each occurrence of a character of ifs will cause
5327                         field-splitting, any adjacent ifs-ws characters will
5328                         be skipped.
5329
5330     ifs-ws    (Read-only) Automatically deduced from the whitespace charac‐
5331               ters in ifs.
5332
5333     ignore    (Boolean) Ignore interrupt signals from the terminal while en‐
5334               tering messages; instead echo them as ‘@’ characters and dis‐
5335               card the current line.
5336
5337     ignoreeof
5338               (Boolean) Ignore end-of-file conditions (‘control-D’) in
5339               Compose mode on message input and in interactive command input.
5340               If set an interactive command input session can only be left by
5341               explicitly using one of the commands exit and quit, and message
5342               input in compose mode can only be terminated by entering a pe‐
5343               riod ‘.’ on a line by itself or by using the ~. COMMAND
5344               ESCAPES; Setting this implies the behaviour that dot describes
5345               in posix mode.
5346
5347     inbox     If this is set to a non-empty string it will specify the user's
5348               primary system mailbox, overriding MAIL and the system-depen‐
5349               dent default, and (thus) be used to replace ‘%’ when doing
5350               Filename transformations; also see folder for more on this
5351               topic.  The value supports a subset of transformations itself.
5352
5353     indentprefix
5354               String used by the ~m, ~M and ~R COMMAND ESCAPES and by the
5355               quote option for indenting messages, in place of the POSIX man‐
5356               dated default tabulator character ‘\t’.  Also see quote-chars.
5357
5358     keep      (Boolean) If set, an empty primary system mailbox file is not
5359               removed.  Note that, in conjunction with posix mode any empty
5360               file will be removed unless this variable is set.  This may im‐
5361               prove the interoperability with other mail user agents when us‐
5362               ing a common folder directory, and prevents malicious users
5363               from creating fake mailboxes in a world-writable spool direc‐
5364               tory.  [v15 behaviour may differ] Only local regular (MBOX)
5365               files are covered, Maildir and other mailbox types will never
5366               be removed, even if empty.
5367
5368     keep-content-length
5369               (Boolean) When (editing messages and) writing MBOX mailbox
5370               files S-nail can be told to keep the ‘Content-Length:’ and
5371               ‘Lines:’ header fields that some MUAs generate by setting this
5372               variable.  Since S-nail does neither use nor update these non-
5373               standardized header fields (which in itself shows one of their
5374               conceptual problems), stripping them should increase interoper‐
5375               ability in between MUAs that work with with same mailbox files.
5376               Note that, if this is not set but writebackedited, as below,
5377               is, a possibly performed automatic stripping of these header
5378               fields already marks the message as being modified.  [v15 be‐
5379               haviour may differ] At some future time S-nail will be capable
5380               to rewrite and apply an mime-encoding to modified messages, and
5381               then those fields will be stripped silently.
5382
5383     keepsave  (Boolean) When a message is saved it is usually discarded from
5384               the originating folder when S-nail is quit.  This setting
5385               causes all saved message to be retained.
5386
5387     line-editor-cpl-word-breaks
5388               [Option] List of bytes which are used by the mle-complete tabu‐
5389               lator completion to decide where word boundaries exist, by de‐
5390               fault ‘"'@=;|:’ [v15 behaviour may differ] This mechanism is
5391               yet restricted.
5392
5393     line-editor-disable
5394               (Boolean) Turn off any line editing capabilities (from S-nails
5395               POW, see On terminal control and line editor for more).
5396
5397     line-editor-no-defaults
5398               (Boolean)[Option] Do not establish any default key binding.
5399
5400     log-prefix
5401               Error log message prefix string (‘s-nail: ’).
5402
5403     mailbox-display
5404               (Read-only) The name of the current mailbox (folder), possibly
5405               abbreviated for display purposes.
5406
5407     mailbox-resolved
5408               (Read-only) The fully resolved path of the current mailbox.
5409
5410     mailcap-disable
5411               (Boolean)[Option] Turn off consideration of MIME type handlers
5412               from, and implicit loading of The Mailcap files.
5413
5414     mailx-extra-rc
5415               An additional startup file that is loaded as the last of the
5416               Resource files.  Use this file for commands that are not under‐
5417               stood by other POSIX mailx(1) implementations, i.e., mostly
5418               anything which is not covered by Initial settings.
5419
5420     markanswered
5421               (Boolean) When a message is replied to and this variable is
5422               set, it is marked as having been answered.  See the section
5423               Message states.
5424
5425     mbox-fcc-and-pcc
5426               (Boolean) By default all file and pipe message receivers (see
5427               expandaddr) will be fed valid MBOX database entry message data
5428               (see folder, mbox-rfc4155), and existing file targets will be‐
5429               come extended in compliance to RFC 4155.  If this variable is
5430               unset then a plain standalone RFC 5322 message will be written,
5431               and existing file targets will be overwritten.
5432
5433     mbox-rfc4155
5434               (Boolean) When opening MBOX mailbox databases, and in order to
5435               achieve compatibility with old software, the very tolerant
5436               POSIX standard rules for detecting message boundaries (so-
5437               called ‘From_’ lines) are used instead of the stricter rules
5438               from the standard RFC 4155.  This behaviour can be switched by
5439               setting this variable.
5440
5441               This may temporarily be handy when S-nail complains about in‐
5442               valid ‘From_’ lines when opening a MBOX: in this case setting
5443               this variable and re-opening the mailbox in question may cor‐
5444               rect the result.  If so, copying the entire mailbox to some
5445               other file, as in ‘copy * SOME-FILE’, will perform proper, all-
5446               compatible ‘From_’ quoting for all detected messages, resulting
5447               in a valid MBOX mailbox.  ([v15 behaviour may differ] The bet‐
5448               ter and non-destructive approach is to re-encode invalid mes‐
5449               sages, as if it would be created anew, instead of mangling the
5450               ‘From_’ lines; this requires the structural code changes of the
5451               v15 rewrite.)  Finally the variable can be unset again:
5452
5453                     define mboxfix {
5454                       localopts yes; wysh set mbox-rfc4155;\
5455                         wysh File "${1}"; copy * "${2}"
5456                     }
5457                     call mboxfix /tmp/bad.mbox /tmp/good.mbox
5458
5459     memdebug  (Boolean) Internal development variable.  (Keeps memory debug
5460               enabled even if debug is not set.)
5461
5462     message-id-disable
5463               (Boolean) By setting this variable the generation of
5464               ‘Message-ID:’ and ‘Content-ID:’ message and MIME part headers
5465               can be completely suppressed, effectively leaving this task up
5466               to the mta (Mail-Transfer-Agent) or the SMTP server.  Note that
5467               according to RFC 5321 a SMTP server is not required to add this
5468               field by itself, so it should be ensured that it accepts mes‐
5469               sages without ‘Message-ID’.
5470
5471     message-inject-head
5472               A string to put at the beginning of each new message, followed
5473               by a newline.  [Obsolete] The escape sequences tabulator ‘\t’
5474               and newline ‘\n’ are understood (use the wysh prefix when
5475               setting the variable(s) instead).
5476
5477     message-inject-tail
5478               A string to put at the end of each new message, followed by a
5479               newline.  [Obsolete] The escape sequences tabulator ‘\t’ and
5480               newline ‘\n’ are understood (use the wysh prefix when setting
5481               the variable(s) instead).  Also see on-compose-leave.
5482
5483     metoo     (Boolean) Usually, when an alias expansion contains the sender,
5484               the sender is removed from the expansion.  Setting this option
5485               suppresses these removals.  Note that a set metoo also causes a
5486               ‘-m’ option to be passed through to the mta (Mail-Transfer-
5487               Agent); though most of the modern MTAs no longer document this
5488               flag, no MTA is known which does not support it (for historical
5489               compatibility).
5490
5491     mime-allow-text-controls
5492               (Boolean) When sending messages, each part of the message is
5493               MIME-inspected in order to classify the ‘Content-Type:’ and
5494               ‘Content-Transfer-Encoding:’ (see mime-encoding) that is re‐
5495               quired to send this part over mail transport, i.e., a computa‐
5496               tion rather similar to what the file(1) command produces when
5497               used with the ‘--mime’ option.
5498
5499               This classification however treats text files which are encoded
5500               in UTF-16 (seen for HTML files) and similar character sets as
5501               binary octet-streams, forcefully changing any ‘text/plain’ or
5502               ‘text/html’ specification to ‘application/octet-stream’: If
5503               that actually happens a yet unset charset MIME parameter is set
5504               to ‘binary’, effectively making it impossible for the receiving
5505               MUA to automatically interpret the contents of the part.
5506
5507               If this variable is set, and the data was unambiguously identi‐
5508               fied as text data at first glance (by a ‘.txt’ or ‘.html’ file
5509               extension), then the original ‘Content-Type:’ will not be over‐
5510               written.
5511
5512     mime-alternative-favour-rich
5513               (Boolean) If this variable is set then rich MIME alternative
5514               parts (e.g., HTML) will be preferred in favour of included
5515               plain text versions when displaying messages, provided that a
5516               handler exists which produces output that can be (re)integrated
5517               into S-nail's normal visual display.
5518
5519     mime-counter-evidence
5520               Normally the ‘Content-Type:’ field is used to decide how to
5521               handle MIME parts.  Some MUAs, however, do not use The
5522               mime.types files (also see HTML mail and MIME attachments) or a
5523               similar mechanism to correctly classify content, but specify an
5524               unspecific MIME type (‘application/octet-stream’) even for
5525               plain text attachments.  If this variable is set then S-nail
5526               will try to re-classify such MIME message parts, if possible,
5527               for example via a possibly existing attachment filename.  A
5528               non-empty value may also be given, in which case a number is
5529               expected, actually a carrier of bits, best specified as a bi‐
5530               nary value, like ‘0b1111’.
5531
5532               If bit two is set (counting from 1, decimal 2) then the de‐
5533                   tected mimetype will be carried along with the message and
5534                   be used for deciding which MIME handler is to be used, for
5535                   example; when displaying such a MIME part the part-info
5536                   will indicate the overridden content-type by showing a plus
5537                   sign ‘+’.
5538               If bit three is set (decimal 4) then the counter-evidence
5539                   is always produced and a positive result will be used as
5540                   the MIME type, even forcefully overriding the parts given
5541                   MIME type.
5542               If bit four is set (decimal 8) as a last resort the actual
5543                   content of ‘application/octet-stream’ parts will be in‐
5544                   spected, so that data which looks like plain text can be
5545                   treated as such.  This mode is even more relaxed when data
5546                   is to be displayed to the user or used as a message quote
5547                   (data consumers which mangle data for display purposes,
5548                   which includes masking of control characters, for example).
5549
5550     mime-encoding
5551               The MIME ‘Content-Transfer-Encoding’ to use in outgoing text
5552               messages and message parts, where applicable (7-bit clean text
5553               messages are without an encoding if possible):
5554
5555               ‘8bit’    (Or ‘8b’.)  8-bit transport effectively causes the
5556                         raw data be passed through unchanged, but may cause
5557                         problems when transferring mail messages over chan‐
5558                         nels that are not ESMTP (RFC 1869) compliant.  Also,
5559                         several input data constructs are not allowed by the
5560                         specifications and may cause a different transfer-en‐
5561                         coding to be used.  By established rules and popular
5562                         demand occurrences of ‘^From_’ (see mbox-rfc4155)
5563                         will be MBOXO quoted (prefixed with greater-than sign
5564                         ‘>’) instead of causing a non-destructive encoding
5565                         like ‘quoted-printable’ to be chosen, unless context
5566                         (like message signing) requires otherwise.
5567               ‘quoted-printable’
5568                         (Or ‘qp’.)  Quoted-printable encoding is 7-bit clean
5569                         and has the property that ASCII characters are passed
5570                         through unchanged, so that an english message can be
5571                         read as-is; it is also acceptable for other single-
5572                         byte locales that share many characters with ASCII,
5573                         for example ISO-8859-1.  The encoding will cause a
5574                         large overhead for messages in other character sets:
5575                         for example it will require up to twelve (12) bytes
5576                         to encode a single UTF-8 character of four (4) bytes.
5577                         It is the default encoding.
5578               ‘base64’  (Or ‘b64’.)  This encoding is 7-bit clean and will
5579                         always be used for binary data.  This encoding has a
5580                         constant input:output ratio of 3:4, regardless of the
5581                         character set of the input data it will encode three
5582                         bytes of input to four bytes of output.  This trans‐
5583                         fer-encoding is not human readable without performing
5584                         a decoding step.
5585
5586     mime-force-sendout
5587               (Boolean)[Option] Whenever it is not acceptable to fail sending
5588               out messages because of non-convertible character content this
5589               variable may be set.  It will, as a last resort, classify the
5590               part content as ‘application/octet-stream’.  Please refer to
5591               the section Character sets for the complete picture of charac‐
5592               ter set conversion, and HTML mail and MIME attachments for how
5593               to internally or externally handle part content.
5594
5595     mimetypes-load-control
5596               Can be used to control which of The mime.types files are
5597               loaded: if the letter ‘u’ is part of the option value, then the
5598               user's personal ~/.mime.types file will be loaded (if it ex‐
5599               ists); likewise the letter ‘s’ controls loading of the system
5600               wide /etc/mime.types; directives found in the user file take
5601               precedence, letter matching is case-insensitive.  If this vari‐
5602               able is not set S-nail will try to load both files.  Incorpora‐
5603               tion of the S-nail-built-in MIME types cannot be suppressed,
5604               but they will be matched last (the order can be listed via
5605               mimetype).
5606
5607               More sources can be specified by using a different syntax: if
5608               the value string contains an equals sign ‘=’ then it is instead
5609               parsed as a comma-separated list of the described letters plus
5610               ‘f=FILENAME’ pairs; the given filenames will be expanded and
5611               loaded, and their content may use the extended syntax that is
5612               described in the section The mime.types files.  Directives
5613               found in such files always take precedence (are prepended to
5614               the MIME type cache).
5615
5616     mta       Select an alternate Mail-Transfer-Agent by either specifying
5617               the full pathname of an executable (a ‘file://’ prefix may be
5618               given), or [Option]ally a SMTP aka SUBMISSION protocol URL
5619               [v15-compat]:
5620
5621                     submissions://[user[:password]@]server[:port]
5622
5623               ([no v15-compat]: ‘[smtp://]server[:port]’.)  The default has
5624               been chosen at compile time.  MTA data transfers are always
5625               performed in asynchronous child processes, and without supervi‐
5626               sion unless either the sendwait or the verbose variable is set.
5627               Also see mta-bcc-ok.  [Option]ally expansion of aliases(5) can
5628               be performed by setting mta-aliases.
5629
5630               For testing purposes there is the ‘test’ pseudo-MTA, which
5631               dumps to standard output or optionally to a file, and honours
5632               mbox-fcc-and-pcc:
5633
5634                     $ echo text | s-nail -:/ -Smta=test -s ubject ex@am.ple
5635                     $ </dev/null s-nail -:/ -Smta=test://./xy ex@am.ple
5636
5637               For a file-based MTA it may be necessary to set mta-argv0 in in
5638               order to choose the right target of a modern mailwrapper(8) en‐
5639               vironment.  It will be passed command line arguments from sev‐
5640               eral possible sources: from the variable mta-arguments if set,
5641               from the command line if given and the variable expandargv al‐
5642               lows their use.  Argument processing of the MTA will be termi‐
5643               nated with a -- separator.
5644
5645               The otherwise occurring implicit usage of the following MTA
5646               command line arguments can be disabled by setting the boolean
5647               variable mta-no-default-arguments (which will also disable
5648               passing -- to the MTA): -i (for not treating a line with only a
5649               dot ‘.’ character as the end of input), -m (shall the variable
5650               metoo be set) and -v (if the verbose variable is set); in con‐
5651               junction with the -r command line option or r-option-implicit
5652               -f as well as possibly -F will (not) be passed.
5653
5654               [Option]ally S-nail can send mail over SMTP aka SUBMISSION net‐
5655               work connections to a single defined smart host by setting this
5656               variable to a SMTP or SUBMISSION URL (see On URL syntax and
5657               credential lookup).  An authentication scheme can be specified
5658               via the variable chain smtp-auth.  Encrypted network connec‐
5659               tions are [Option]ally available, the section Encrypted network
5660               communication should give an overview and provide links to more
5661               information on this.  Note that with some mail providers it may
5662               be necessary to set the smtp-hostname variable in order to use
5663               a specific combination of from, hostname and mta.  Network com‐
5664               munication socket timeouts are configurable via
5665               socket-connect-timeout.  All generated network traffic may be
5666               proxied over a SOCKS socks-proxy, it can be logged by setting
5667               verbose twice.  The following SMTP variants may be used:
5668
5669               The plain SMTP protocol (RFC 5321) that normally lives on
5670                   the server port 25 and requires setting the
5671                   smtp-use-starttls variable to enter a TLS encrypted session
5672                   state.  Assign a value like [v15-compat]
5673                   ‘smtp://[user[:password]@]server[:port]’ ([no v15-compat]
5674                   ‘smtp://server[:port]’) to choose this protocol.
5675
5676               The so-called SMTPS which is supposed to live on server
5677                   port 465 and is automatically TLS secured.  Unfortunately
5678                   it never became a standardized protocol and may thus not be
5679                   supported by your hosts network service database – in fact
5680                   the port number has already been reassigned to other proto‐
5681                   cols!
5682
5683                   SMTPS is nonetheless a commonly offered protocol and thus
5684                   can be chosen by assigning a value like [v15-compat]
5685                   ‘smtps://[user[:password]@]server[:port]’ ([no v15-compat]
5686                   ‘smtps://server[:port]’); due to the mentioned problems it
5687                   is usually necessary to explicitly specify the port as
5688                   ‘:465’, however.
5689
5690               The SUBMISSION protocol (RFC 6409) lives on server port 587
5691                   and is identically to the SMTP protocol from S-nail's point
5692                   of view; it requires setting smtp-use-starttls to enter a
5693                   TLS secured session state; e.g., [v15-compat]
5694                   ‘submission://[user[:password]@]server[:port]’.
5695
5696               The SUBMISSIONS protocol (RFC 8314) that lives on server
5697                   port 465 and is TLS secured by default.  It can be chosen
5698                   by assigning a value like [v15-compat]
5699                   ‘submissions://[user[:password]@]server[:port]’.  Due to
5700                   the problems mentioned for SMTPS above and the fact that
5701                   SUBMISSIONS is new and a successor that lives on the same
5702                   port as the historical engineering mismanagement named
5703                   SMTPS, it is usually necessary to explicitly specify the
5704                   port as ‘:465’.
5705
5706     mta-aliases
5707               [Option] If set to a path pointing to a text file in valid MTA
5708               (Postfix) aliases(5) format, the file is loaded and cached
5709               (manageable with mtaaliases), and henceforth plain ‘name’ (see
5710               expandaddr) message receiver names are recursively expanded as
5711               a last expansion step, after the distribution lists which can
5712               be created with alias.  Constraints on aliases(5) content sup‐
5713               port: only local addresses (names) which are valid usernames
5714               (‘[a-z_][a-z0-9_-]*[$]?’) are treated as expandable aliases,
5715               and [v15 behaviour may differ] ‘:include:/file/name’ directives
5716               are not supported.  By including ‘-name’ in expandaddr it can
5717               be asserted that only expanded names (mail addresses) are
5718               passed through to the MTA.
5719
5720     mta-arguments
5721               Arguments to pass through to a file-based mta (Mail-Transfer-
5722               Agent), parsed according to Shell-style argument quoting into
5723               an array of arguments which will be joined onto MTA options
5724               from other sources, for example ‘? wysh set mta-arguments='-t
5725               -X "/tmp/my log"'’.
5726
5727     mta-no-default-arguments
5728               (Boolean) Avoids passing standard command line options to a
5729               file-based mta (please see there).
5730
5731     mta-no-receiver-arguments
5732               (Boolean) By default all receiver addresses will be passed as
5733               command line options to a file-based mta.  Setting this vari‐
5734               able disables this behaviour to aid those MTAs which employ
5735               special treatment of such arguments.  Doing so can make it nec‐
5736               essary to pass a -t via mta-arguments, to testify the MTA that
5737               it should use the passed message as a template.
5738
5739     mta-argv0
5740               Many systems use a so-called mailwrapper(8) environment to en‐
5741               sure compatibility with sendmail(1).  This works by inspecting
5742               the name that was used to invoke the mail delivery system.  If
5743               this variable is set then the mailwrapper (the program that is
5744               actually executed when calling the file-based mta) will treat
5745               its contents as that name.
5746
5747     mta-bcc-ok
5748               (Boolean) In violation of RFC 5322 some MTAs do not remove
5749               ‘Bcc:’ header lines from transported messages after having
5750               noted the respective receivers for addressing purposes.  (The
5751               MTAs Exim and Courier for example require the command line op‐
5752               tion -t to enforce removal.)  Unless this is set corresponding
5753               receivers are addressed by protocol-specific means or MTA com‐
5754               mand line options only, the header itself is stripped before
5755               being sent over the wire.
5756
5757     netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup
5758               (Boolean)[v15-compat][Option] Used to control usage of the
5759               user's ~/.netrc file for lookup of account credentials, as doc‐
5760               umented in the section On URL syntax and credential lookup and
5761               for the command netrc; the section The .netrc file documents
5762               the file format.  Also see netrc-pipe.
5763
5764     netrc-pipe
5765               [v15-compat][Option] When ~/.netrc is loaded (see netrc and
5766               netrc-lookup) then S-nail will read the output of a shell pipe
5767               instead of the user's ~/.netrc file if this variable is set (to
5768               the desired shell command).  This can be used to, for example,
5769               store ~/.netrc in encrypted form: ‘? set netrc-pipe='gpg -qd
5770               ~/.netrc.pgp'’.
5771
5772     newfolders
5773               [Option] If this variable has the value ‘maildir’, newly cre‐
5774               ated local folders will be in Maildir instead of MBOX format.
5775
5776     newmail   Checks for new mail in the current folder each time the prompt
5777               is shown.  A Maildir folder must be re-scanned to determine if
5778               new mail has arrived.  If this variable is set to the special
5779               value ‘nopoll’ then a Maildir folder will not be rescanned com‐
5780               pletely, but only timestamp changes are detected.  Maildir
5781               folders are [Option]al.
5782
5783     outfolder
5784               (Boolean) Causes a non-absolute filename specified in record,
5785               as well as the sender-based filenames of the Copy, Save,
5786               Followup and followup commands to be interpreted relative to
5787               the folder directory rather than relative to the current direc‐
5788               tory.
5789
5790     on-account-cleanup-ACCOUNT, on-account-cleanup
5791               Macro hook which will be called once an account is left, as the
5792               very last step before unrolling per-account localopts.  This
5793               hook is run even in case of fatal errors, including those gen‐
5794               erated by switching to the account as such, and it is advisable
5795               to perform only absolutely necessary actions, like cleaning up
5796               alternates, for example.  The specialized form is used in
5797               favour of the generic one if found.
5798
5799     on-compose-cleanup
5800               Macro hook which will be called after the message has been sent
5801               (or not, in case of failures), as the very last step before un‐
5802               rolling compose mode localopts.  This hook is run even in case
5803               of fatal errors, and it is advisable to perform only absolutely
5804               necessary actions, like cleaning up alternates, for example.
5805
5806               For compose mode hooks that may affect the message content
5807               please see on-compose-enter, on-compose-leave,
5808               on-compose-splice.  [v15 behaviour may differ] This hook exists
5809               because alias, alternates, commandalias, shortcut, to name a
5810               few, are neither covered by localopts nor by local: changes ap‐
5811               plied in compose mode will continue to be in effect thereafter.
5812
5813     on-compose-enter, on-compose-leave
5814               Macro hooks which will be called once compose mode is entered,
5815               and after composing has been finished, respectively; the exact
5816               order of the steps taken is documented for ~., one of the
5817               COMMAND ESCAPES.  Context about the message being worked on can
5818               be queried via digmsg.  localopts are enabled for these hooks,
5819               and changes on variables will be forgotten after the message
5820               has been sent.  on-compose-cleanup can be used to perform other
5821               necessary cleanup steps.
5822
5823               Here is an example that injects a signature via
5824               message-inject-tail; instead using on-compose-splice to simply
5825               inject the file of desire via ~< or ~<! may be a better ap‐
5826               proach.
5827
5828                     define t_ocl {
5829                       vput ! i cat ~/.mysig
5830                       if $? -eq 0
5831                          vput csop message-inject-tail trim-end $i
5832                       end
5833
5834                       # Alternatively
5835                       readctl create ~/.mysig
5836                       if $? -eq 0
5837                         readall i
5838                         if $? -eq 0
5839                           vput csop message-inject-tail trim-end $i
5840                         end
5841                         readctl remove ~/.mysig
5842                       end
5843                     }
5844                     set on-compose-leave=t_ocl
5845
5846     on-compose-splice, on-compose-splice-shell
5847               These hooks run once the normal compose mode is finished, but
5848               before the on-compose-leave macro hook is called etc.  Both
5849               hooks will be executed in a subprocess, with their input and
5850               output connected to S-nail such that they can act as if they
5851               would be an interactive user.  The difference in between them
5852               is that the latter is a SHELL command, whereas the former is a
5853               normal defined macro, but which is restricted to a small set of
5854               commands (the verbose output of for example list will indicate
5855               said capability).  localopts are enabled for these hooks (in
5856               the parent process), causing any setting to be forgotten after
5857               the message has been sent; on-compose-cleanup can be used to
5858               perform other cleanup as necessary.
5859
5860               During execution of these hooks S-nail will temporarily forget
5861               whether it has been started in interactive mode, (a restricted
5862               set of) COMMAND ESCAPES will always be available, and for guar‐
5863               anteed reproducibilities sake escape and ifs will be set to
5864               their defaults.  The compose mode command ~^ has been espe‐
5865               cially designed for scriptability (via these hooks).  The first
5866               line the hook will read on its standard input is the protocol
5867               version of said command escape, currently “0 0 2”: backward in‐
5868               compatible protocol changes have to be expected.
5869
5870               Care must be taken to avoid deadlocks and other false control
5871               flow: if both involved processes wait for more input to happen
5872               at the same time, or one does not expect more input but the
5873               other is stuck waiting for consumption of its output, etc.
5874               There is no automatic synchronization of the hook: it will not
5875               be stopped automatically just because it, e.g., emits ‘~x’.
5876               The hooks will however receive a termination signal if the par‐
5877               ent enters an error condition.  [v15 behaviour may differ] Pro‐
5878               tection against and interaction with signals is not yet given;
5879               it is likely that in the future these scripts will be placed in
5880               an isolated session, which is signalled in its entirety as nec‐
5881               essary.
5882
5883                     define ocs_signature {
5884                       read version
5885                       echo '~< ~/.mysig' # '~<! fortune pathtofortunefile'
5886                     }
5887                     set on-compose-splice=ocs_signature
5888
5889                     wysh set on-compose-splice-shell=$'\
5890                       read version;\
5891                       printf "hello $version!  Headers: ";\
5892                       echo \'~^header list\';\
5893                       read status result;\
5894                       echo "status=$status result=$result";\
5895                       '
5896
5897                     define ocsm {
5898                       read version
5899                       echo Splice protocol version is $version
5900                       echo '~^h l'; read hl; vput csop es subs "${hl}" 0 1
5901                       if "$es" != 2
5902                         echoerr 'Cannot read header list'; echo '~x'; xit
5903                       endif
5904                       if "$hl" !%?case ' cc'
5905                         echo '~^h i cc "Diet is your <mirr.or>"'; read es;\
5906                           vput csop es substring "${es}" 0 1
5907                         if "$es" != 2
5908                           echoerr 'Cannot insert Cc: header'; echo '~x'
5909                           # (no xit, macro finishes anyway)
5910                         endif
5911                       endif
5912                     }
5913                     set on-compose-splice=ocsm
5914
5915     on-history-addition
5916               This hook will be called if an entry is about to be added to
5917               the history of the MLE, as documented in On terminal control
5918               and line editor.  It will be called with three arguments: the
5919               first is the name of the input context (see bind), the second
5920               is either an empty string or the matching history-gabby type,
5921               and the third being the complete command line to be added.  The
5922               entry will not be added to history if the hook uses a non-0
5923               return.  [v15 behaviour may differ] A future version will give
5924               the expanded command name as the third argument, followed by
5925               the tokenized command line as parsed in the remaining argu‐
5926               ments, the first of which is the original unexpanded command
5927               name; i.e., one may do ‘shift 4’ and will then be able to ac‐
5928               cess the positional parameters as usual via *, #, 1 etc.
5929
5930     on-main-loop-tick
5931               This hook will be called whenever the program's main event loop
5932               is about to read the next input line.  Note variable and other
5933               changes it performs are not scoped as via localopts!
5934
5935     on-program-exit
5936               This hook will be called when the program exits, whether via
5937               exit or quit, or because the send mode is done.  Note: this
5938               runs late and so terminal settings etc. are already teared
5939               down.
5940
5941     on-resend-cleanup
5942               [v15 behaviour may differ] Identical to on-compose-cleanup, but
5943               is only triggered by resend.
5944
5945     on-resend-enter
5946               [v15 behaviour may differ] Identical to on-compose-enter, but
5947               is only triggered by resend; currently there is no digmsg sup‐
5948               port, for example.
5949
5950     page      (Boolean) If set, each message feed through the command given
5951               for pipe is followed by a formfeed character ‘\f’.
5952
5953     password-USER@HOST, password-HOST, password
5954               [v15-compat] Variable chain that sets a password, which is used
5955               in case none has been given in the protocol and account-spe‐
5956               cific URL; as a last resort S-nail will ask for a password on
5957               the user's terminal if the authentication method requires a
5958               password.  Specifying passwords in a startup file is generally
5959               a security risk; the file should be readable by the invoking
5960               user only.
5961
5962     password-USER@HOST
5963               [no v15-compat] (see the chain above for [v15-compat]) Set the
5964               password for ‘USER’ when connecting to ‘HOST’.  If no such
5965               variable is defined for a host, the user will be asked for a
5966               password on standard input.  Specifying passwords in a startup
5967               file is generally a security risk; the file should be readable
5968               by the invoking user only.
5969
5970     piperaw   (Boolean) Send messages to the pipe command without performing
5971               MIME and character set conversions.
5972
5973     pipe-EXTENSION
5974               Identical to pipe-TYPE/SUBTYPE except that ‘EXTENSION’ (normal‐
5975               ized to lowercase using character mappings of the ASCII
5976               charset) denotes a file extension, for example ‘xhtml’.  Han‐
5977               dlers registered using this method take precedence.
5978
5979     pipe-TYPE/SUBTYPE
5980               A MIME message part identified as ‘TYPE/SUBTYPE’ (case-insensi‐
5981               tive, normalized to lowercase using character mappings of the
5982               ASCII charset) is displayed or quoted, its text is filtered
5983               through the value of this variable interpreted as a shell com‐
5984               mand.  Unless noted only parts displayable as inline plain text
5985               (see copiousoutput) are covered, other MIME parts will only be
5986               considered by and for mimeview.
5987
5988               The special value question mark ‘?’ forces interpretation of
5989               the message part as plain text, for example ‘set
5990               pipe-application/xml=?’.  (This can also be achieved by adding
5991               a MIME type-marker via mimetype.)  [Option]ally MIME type han‐
5992               dlers may be defined via The Mailcap files to which should be
5993               referred to for documentation of flags like copiousoutput.
5994               Question mark is indeed a trigger character to indicate flags
5995               that adjust behaviour and usage of the rest of the value, the
5996               shell command, for example:
5997
5998                     ? set pipe-X/Y='?!++=? vim ${MAILX_FILENAME_TEMPORARY}'
5999
6000               ‘*’       The command output can be reintegrated into this
6001                         MUA's normal processing: copiousoutput.  Implied when
6002                         using a plain ‘’.
6003               ‘#’       Only use this handler for display, not for quoting a
6004                         message: x-mailx-noquote.
6005               ‘&’       Run the command asynchronously, do not wait for the
6006                         handler to exit: x-mailx-async.  The standard output
6007                         of the command will go to /dev/null.
6008               ‘!’       The command must be run on an interactive terminal,
6009                         the terminal will temporarily be released for it to
6010                         run: needsterminal.
6011               ‘+’       Request creation of a zero-sized temporary file, the
6012                         absolute pathname of which will be made accessible
6013                         via the environment variable
6014                         MAILX_FILENAME_TEMPORARY: x-mailx-tmpfile.  If given
6015                         twice then the file will be unlinked automatically by
6016                         S-nail when the command loop is entered again at lat‐
6017                         est: x-mailx-tmpfile-unlink; it is an error to use
6018                         automatic deletion in conjunction with x-mailx-async.
6019               ‘=’       Normally the MIME part content is passed to the han‐
6020                         dler via standard input; with this the data will in‐
6021                         stead be written into MAILX_FILENAME_TEMPORARY
6022                         (x-mailx-tmpfile-fill), the creation of which is im‐
6023                         plied; in order to cause automatic deletion of the
6024                         temporary file two plus signs ‘++’ still have to be
6025                         used.
6026               ‘t’       Text type-marker: display this as normal plain text
6027                         (for type-markers: The mime.types files).  Identical
6028                         to only giving plain ‘?’, implies copiousoutput.
6029               ‘h’       [Option] HTML type-marker: display via built-in HTML-
6030                         to-text filter.  Implies copiousoutput.
6031               ‘?’       To avoid ambiguities with normal shell command con‐
6032                         tent another question mark can be used to forcefully
6033                         terminate interpretation of remaining characters.
6034                         (Any character not in this list will have the same
6035                         effect.)
6036
6037               Some information about the MIME part to be displayed is embed‐
6038               ded into the environment of the shell command:
6039
6040               MAILX_CONTENT            The MIME content-type of the part, if
6041                                        known, the empty string otherwise.
6042               MAILX_CONTENT_EVIDENCE   If mime-counter-evidence includes the
6043                                        carry-around-bit (2), then this will
6044                                        be set to the detected MIME content-
6045                                        type; not only then identical to
6046                                        MAILX_CONTENT otherwise.
6047               MAILX_EXTERNAL_BODY_URL  MIME parts of type
6048                                        ‘message/external-body
6049                                        access-type=url’ will store the access
6050                                        URL in this variable, it is empty oth‐
6051                                        erwise.  URL targets should not be ac‐
6052                                        tivated automatically, without super‐
6053                                        vision.
6054               MAILX_FILENAME           The filename, if any is set, the empty
6055                                        string otherwise.
6056               MAILX_FILENAME_GENERATED
6057                                        A random string.
6058               MAILX_FILENAME_TEMPORARY
6059                                        If temporary file creation has been
6060                                        requested through the command prefix
6061                                        this variable will be set and contain
6062                                        the absolute pathname of the temporary
6063                                        file.
6064
6065     pop3-auth-USER@HOST, pop3-auth-HOST, pop3-auth
6066               [Option][v15-compat] Variable chain that sets the POP3 authen‐
6067               tication method.  Supported are the default ‘plain’, [v15-com‐
6068               pat] ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6069               OAUTHBEARER?), as well as [v15-compat] ‘external’ and
6070               ‘externanon’ for TLS secured connections which pass a client
6071               certificate via tls-config-pairs.  There may be the [Option]al
6072               method [v15-compat] ‘gssapi’.  ‘externanon’ does not need any
6073               user credentials, ‘external’ and ‘gssapi’ need a user, the re‐
6074               mains also require a password.  ‘externanon’ solely builds upon
6075               the credentials passed via a client certificate, and is usually
6076               the way to go since tested servers do not actually follow RFC
6077               4422, and fail if additional credentials are actually passed.
6078               Unless pop3-no-apop is set the ‘plain’ method will [Option]ally
6079               be replaced with APOP if possible (see there).
6080
6081     pop3-bulk-load-USER@HOST, pop3-bulk-load-HOST, pop3-bulk-load
6082               (Boolean)[Option] When accessing a POP3 server S-nail loads the
6083               headers of the messages, and only requests the message bodies
6084               on user request.  For the POP3 protocol this means that the
6085               message headers will be downloaded twice.  If this variable is
6086               set then S-nail will download only complete messages from the
6087               given POP3 server(s) instead.
6088
6089     pop3-keepalive-USER@HOST, pop3-keepalive-HOST, pop3-keepalive
6090               [Option] POP3 servers close the connection after a period of
6091               inactivity; the standard requires this to be at least 10 min‐
6092               utes, but practical experience may vary.  Setting this variable
6093               to a numeric value greater than ‘0’ causes a ‘NOOP’ command to
6094               be sent each value seconds if no other operation is performed.
6095
6096     pop3-no-apop-USER@HOST, pop3-no-apop-HOST, pop3-no-apop
6097               (Boolean)[Option] Unless this variable is set the MD5 based
6098               ‘APOP’ authentication method will be used instead of a chosen
6099               ‘plain’ pop3-auth when connecting to a POP3 server that adver‐
6100               tises support.  The advantage of ‘APOP’ is that only a single
6101               packet is sent for the user/password tuple.  (Originally also
6102               that the password is not sent in clear text over the wire, but
6103               for one MD5 does not any longer offer sufficient security, and
6104               then today transport is almost ever TLS secured.)  Note that
6105               pop3-no-apop-HOST requires [v15-compat].
6106
6107     pop3-use-starttls-USER@HOST, pop3-use-starttls-HOST, pop3-use-starttls
6108               (Boolean)[Option] Causes S-nail to issue a ‘STLS’ command to
6109               make an unencrypted POP3 session TLS encrypted.  This function‐
6110               ality is not supported by all servers, and is not used if the
6111               session is already encrypted by the POP3S method.  Note that
6112               pop3-use-starttls-HOST requires [v15-compat].
6113
6114     posix     (Boolean) This flag enables POSIX mode, which changes behaviour
6115               of S-nail where that deviates from standardized behaviour.  It
6116               is automatically squared with the environment variable
6117               POSIXLY_CORRECT, changing the one will adjust the other.  The
6118               following behaviour is covered and enforced by this mechanism:
6119
6120               In non-interactive mode, any error encountered while load‐
6121                   ing resource files during program startup will cause a pro‐
6122                   gram exit, whereas in interactive mode such errors will
6123                   stop loading of the currently loaded (stack of) file(s,
6124                   i.e., recursively).  These exits can be circumvented on a
6125                   per-command base by using ignerr, one of the Command
6126                   modifiers, for each command which shall be allowed to fail.
6127               •   alternates will replace the list of alternate addresses in‐
6128                   stead of appending to it.  In addition alternates will only
6129                   be honoured for any sort of message reply, and for aliases.
6130               The variable inserting COMMAND ESCAPES ~A, ~a, ~I and ~i
6131                   will expand embedded character sequences ‘\t’ horizontal
6132                   tabulator and ‘\n’ line feed.  [v15 behaviour may differ]
6133                   For compatibility reasons this step will always be per‐
6134                   formed.
6135               Reading in messages via ~f (COMMAND ESCAPES) will use the
6136                   ‘type’ not the ‘forward’ headerpick selection.
6137               Upon changing the active folder no summary of headers will
6138                   be displayed even if header is set.
6139               Setting ignoreeof implies the behaviour described by dot.
6140               The variable keep is extended to cover any empty mailbox,
6141                   not only empty primary system mailboxes: they will be re‐
6142                   moved when they are left in empty state otherwise.
6143               Each command has an exit ? and error ! status that over‐
6144                   writes that of the last command.  In POSIX mode the program
6145                   exit status will signal failure regardless unless all mes‐
6146                   sages were successfully sent out to the mta; also see
6147                   sendwait.
6148
6149     print-alternatives
6150               (Boolean) When a MIME message part of type
6151               ‘multipart/alternative’ is displayed and it contains a subpart
6152               of type ‘text/plain’, other parts are normally discarded.  Set‐
6153               ting this variable causes all subparts to be displayed, just as
6154               if the surrounding part was of type ‘multipart/mixed’.
6155
6156     prompt    The string used as a prompt in interactive mode.  Whenever the
6157               variable is evaluated the value is treated as if specified
6158               within dollar-single-quotes (see Shell-style argument quoting).
6159               This (post-assignment, i.e., second) expansion can be used to
6160               embed status information, for example ?, !, account or
6161               mailbox-display.
6162
6163               In order to embed characters which should not be counted when
6164               calculating the visual width of the resulting string, enclose
6165               the characters of interest in a pair of reverse solidus escaped
6166               brackets: ‘\[\E[0m\]’; a slot for coloured prompts is also
6167               available with the [Option]al command colour.  Prompting may be
6168               prevented by setting this to the null string (aka ‘set
6169               noprompt’).
6170
6171     prompt2   This string is used for secondary prompts, but is otherwise
6172               identical to prompt.  The default is ‘.. ’.
6173
6174     quiet     (Boolean) Suppresses the printing of the version when first in‐
6175               voked.
6176
6177     quote     If set messages processed by variants of followup and reply
6178               will start with the original message, lines of which prefixed
6179               by indentprefix, taking into account quote-chars and
6180               quote-fold.  No headers will be quoted when set without value
6181               or for ‘noheading’, for ‘headers’ the ‘type’ headerpick selec‐
6182               tion will be included in the quote, ‘allbodies’ embeds the
6183               (body) contents of all MIME parts, and ‘allheaders’ also in‐
6184               cludes all headers.  The quoted message will be enclosed by the
6185               expansions of quote-inject-head and quote-inject-tail.  Also
6186               see quote-add-cc, quote-as-attachment and ~Q, one of the
6187               COMMAND ESCAPES.
6188
6189     quote-add-cc
6190               (Boolean) Whether senders of messages quoted via ~Q shall be
6191               made members of the carbon copies ‘Cc:’ list.
6192
6193     quote-as-attachment
6194               (Boolean) Add the original message in its entirety as a
6195               ‘message/rfc822’ MIME attachment when replying to a message.
6196               Note this works regardless of the setting of quote.
6197
6198     quote-chars
6199               Can be set to a string consisting of non-whitespace ASCII char‐
6200               acters which shall be treated as quotation leaders, the default
6201               being ‘>|}:’.
6202
6203     quote-fold
6204               [Option] Can be set in addition to indentprefix, and creates a
6205               more fancy quotation in that leading quotation characters
6206               (quote-chars) are compressed and overlong lines are folded.
6207               quote-fold can be set to either one, two or three (space sepa‐
6208               rated) numeric values, which are interpreted as the maximum
6209               (goal) and the minimum line length, respectively, in a spirit
6210               rather equal to the fmt(1) program, but line- instead of para‐
6211               graph-based.  The third value is used as the maximum line
6212               length instead of the first if no better break point can be
6213               found; it is ignored unless it is larger than the minimum and
6214               smaller than the maximum.  If not set explicitly the minimum
6215               will reflect the goal algorithmically.  The goal cannot be
6216               smaller than the length of indentprefix plus some additional
6217               pad; necessary adjustments take place silently.
6218
6219     quote-inject-head, quote-inject-tail
6220               The strings to put before and after the text of a quoted mes‐
6221               sage, if non-empty, and respectively.  The former defaults to
6222               ‘%f wrote:\n\n’.  Special format directives will be expanded if
6223               possible, and if so configured the output will be folded ac‐
6224               cording to quote-fold.  Format specifiers in the given strings
6225               start with a percent sign ‘%’ and expand values of the original
6226               message, unless noted otherwise.  Note that names and addresses
6227               are not subject to the setting of showto.  Valid format speci‐
6228               fiers are:
6229
6230               ‘%%’      A plain percent sign.
6231               ‘%a’      The address(es) of the sender(s).
6232               ‘%d’      The date found in the ‘Date:’ header of the message
6233                         when datefield is set (the default), otherwise the
6234                         date when the message was received.  Formatting can
6235                         be controlled by assigning a strftime(3) format
6236                         string to datefield (and datefield-markout-older).
6237               ‘%f’      The full name(s) (name and address, as given) of the
6238                         sender(s).
6239               ‘%i’      The ‘Message-ID:’.
6240               ‘%n’      The real name(s) of the sender(s) if there is one and
6241                         showname allows usage, the address(es) otherwise.
6242               ‘%r’      The senders real name(s) if there is one, the ad‐
6243                         dress(es) otherwise.
6244
6245     r-option-implicit
6246               (Boolean) Setting this option evaluates the contents of from
6247               (or, if that contains multiple addresses, sender) and passes
6248               the results onto the used (file-based) MTA as described for the
6249               -r option (empty argument case).
6250
6251     recipients-in-cc
6252               (Boolean) When doing a reply, the original ‘From:’ and ‘To:’ as
6253               well as addressees which possibly came in via ‘Reply-To:’ and
6254               ‘Mail-Followup-To:’ are by default merged into the new ‘To:’.
6255               If this variable is set a sensitive algorithm tries to place in
6256               ‘To:’ only the sender of the message being replied to, others
6257               are placed in ‘Cc:’.
6258
6259     record    Unless this variable is defined, no copies of outgoing mail
6260               will be saved.  If defined it gives the pathname, subject to
6261               the usual Filename transformations, of a folder where all new,
6262               replied-to or forwarded messages are saved: when saving to this
6263               folder fails the message is not sent, but instead saved to
6264               DEAD.  The standard defines that relative (fully expanded)
6265               paths are to be interpreted relative to the current directory
6266               (cwd), to force interpretation relative to folder outfolder
6267               needs to be set in addition.
6268
6269     record-files
6270               (Boolean) If this variable is set the meaning of record will be
6271               extended to cover messages which target only file and pipe re‐
6272               cipients (see expandaddr).  These address types will not appear
6273               in recipient lists unless add-file-recipients is also set.
6274
6275     record-resent
6276               (Boolean) If this variable is set the meaning of record will be
6277               extended to also cover the resend and Resend commands.
6278
6279     reply-in-same-charset
6280               (Boolean) If this variable is set S-nail first tries to use the
6281               same character set of the original message for replies.  If
6282               this fails, the mechanism described in Character sets is evalu‐
6283               ated as usual.
6284
6285     reply-strings
6286               Can be set to a comma-separated list of (case-insensitive ac‐
6287               cording to ASCII rules) strings which shall be recognized in
6288               addition to the built-in strings as ‘Subject:’ reply message
6289               indicators – built-in are ‘Re:’, which is mandated by RFC 5322,
6290               as well as the german ‘Aw:’, ‘Antw:’, and the ‘Wg:’ which often
6291               has been seen in the wild; I.e., the separating colon has to be
6292               specified explicitly.
6293
6294     reply-to  A list of addresses to put into the ‘Reply-To:’ field of the
6295               message header.  Members of this list are handled as if they
6296               were in the alternates list.
6297
6298     replyto   [Obsolete] Variant of reply-to.
6299
6300     reply-to-honour
6301               Controls whether a ‘Reply-To:’ header is honoured when replying
6302               to a message via reply or Lreply.  This is a quadoption; if set
6303               without a value it defaults to “yes”.
6304
6305     reply-to-swap-in
6306               Standards like DKIM and (in conjunction with) DMARC caused many
6307               Mailing lists to use sender address rewriting in the style of
6308               ‘Name via List <list@address>’, where the original sender ad‐
6309               dress often being placed in ‘Reply-To:’.  If this is set and a
6310               ‘Reply-To:’ exists, and consists of only one addressee (!),
6311               then that is used in place of the pretended sender.  This works
6312               independently from reply-to-honour.  The optional value, a
6313               comma-separated list of strings, offers more fine-grained con‐
6314               trol on when swapping shall be used; for now supported is
6315               mlist, here swapping occurs if the sender is a mailing-list as
6316               defined by mlist.
6317
6318     rfc822-body-from_
6319               (Boolean) This variable can be used to force displaying a so-
6320               called ‘From_’ line for messages that are embedded into an en‐
6321               velope mail via the ‘message/rfc822’ MIME mechanism, for more
6322               visual convenience, also see mbox-rfc4155.
6323
6324     save      (Boolean) Enable saving of (partial) messages in DEAD upon in‐
6325               terrupt or delivery error.
6326
6327     screen    The number of lines that represents a “screenful” of lines,
6328               used in headers summary display, from searching, message
6329               topline display and scrolling via z.  If this variable is not
6330               set S-nail falls back to a calculation based upon the detected
6331               terminal window size and the baud rate: the faster the termi‐
6332               nal, the more will be shown.  Overall screen dimensions and
6333               pager usage is influenced by the environment variables COLUMNS
6334               and LINES and the variable crt.
6335
6336     searchheaders
6337               (Boolean) Expand message list specifiers in the form ‘/x:y’ to
6338               all messages containing the substring “y” in the header field
6339               ‘x’.  The string search is case insensitive.
6340
6341     sendcharsets
6342               [Option] A comma-separated list of character set names that can
6343               be used in outgoing internet mail.  The value of the variable
6344               charset-8bit is automatically appended to this list of charac‐
6345               ter sets.  If no character set conversion capabilities are com‐
6346               piled into S-nail then the only supported charset is
6347               ttycharset.  Also see sendcharsets-else-ttycharset and refer to
6348               the section Character sets for the complete picture of charac‐
6349               ter set conversion in S-nail.
6350
6351     sendcharsets-else-ttycharset
6352               (Boolean)[Option] If this variable is set, but sendcharsets is
6353               not, then S-nail acts as if sendcharsets had been set to the
6354               value of the variable ttycharset.  In effect this combination
6355               passes through the message data in the character set of the
6356               current locale encoding: therefore mail message text will be
6357               (assumed to be) in ISO-8859-1 encoding when send from within a
6358               ISO-8859-1 locale, and in UTF-8 encoding when send from within
6359               an UTF-8 locale.
6360
6361               The 8-bit fallback charset-8bit never comes into play as
6362               ttycharset is implicitly assumed to be 8-bit and capable to
6363               represent all files the user may specify (as is the case when
6364               no character set conversion support is available in S-nail and
6365               the only supported character set is ttycharset, see Character
6366               sets).  This might be a problem for scripts which use the sug‐
6367               gested ‘LC_ALL=C’ setting, since in this case the character set
6368               is US-ASCII by definition, so that it is better to also over‐
6369               ride ttycharset, then; and/or do something like the following
6370               in the resource file:
6371
6372                     # Avoid ASCII "propagates to 8-bit" when scripting
6373                     \if ! t && "$LC_ALL" != C && "$LC_CTYPE" != C
6374                       \set sendcharsets-else-ttycharset
6375                     \end
6376
6377     sender    An address that is put into the ‘Sender:’ field of outgoing
6378               messages, quoting RFC 5322: the mailbox of the agent responsi‐
6379               ble for the actual transmission of the message.  This field
6380               should normally not be used unless the from field contains more
6381               than one address, on which case it is required.  [v15 behaviour
6382               may differ] Please expect automatic management of the from and
6383               sender relationship.  Dependent on the context this address is
6384               handled as if it were in the list of alternates.  Also see -r,
6385               r-option-implicit.
6386
6387     sendmail  [Obsolete] Predecessor of mta.
6388
6389     sendmail-arguments
6390               [Obsolete] Predecessor of mta-arguments.
6391
6392     sendmail-no-default-arguments
6393               [Obsolete](Boolean) Predecessor of mta-no-default-arguments.
6394
6395     sendmail-progname
6396               [Obsolete] Predecessor of mta-argv0.
6397
6398     sendwait  Sending messages to the chosen mta or to command-pipe receivers
6399               (see On sending mail, and non-interactive mode) will be per‐
6400               formed asynchronously.  This means that only startup errors of
6401               the respective program will be recognizable, but no delivery
6402               errors.  Also, no guarantees can be made as to when the respec‐
6403               tive program will actually run, as well as to when they will
6404               have produced output.
6405
6406               If this variable is set then child program exit is waited for,
6407               and its exit status code is used to decide about success.  Re‐
6408               marks: in conflict with the POSIX standard this variable is
6409               built-in to be initially set.  Another difference is that it
6410               can have a value, which is interpreted as a comma-separated
6411               list of case-insensitive strings naming specific subsystems for
6412               which synchronousness shall be ensured (only).  Possible values
6413               are ‘mta’ for mta delivery, and ‘pcc’ for command-pipe re‐
6414               ceivers.
6415
6416     showlast  (Boolean) This setting causes S-nail to start at the last mes‐
6417               sage instead of the first one when opening a mail folder, as
6418               well as with from and headers.
6419
6420     showname  (Boolean) Causes S-nail to use the sender's real name instead
6421               of the plain address in the header field summary and in message
6422               specifications.
6423
6424     showto    (Boolean) Causes the recipient of the message to be shown in
6425               the header summary if the message was sent by the user.
6426
6427     Sign      The value backing ~A, one of the COMMAND ESCAPES.  Also see
6428               message-inject-tail, on-compose-leave and on-compose-splice.
6429
6430     sign      The value backing ~a, one of the COMMAND ESCAPES.  Also see
6431               message-inject-tail, on-compose-leave and on-compose-splice.
6432
6433     signature
6434               [Obsolete] Please use on-compose-splice or
6435               on-compose-splice-shell or on-compose-leave and (if necessary)
6436               message-inject-tail instead!
6437
6438     skipemptybody
6439               (Boolean) If an outgoing message has an empty first or only
6440               message part, do not send, but discard it, successfully (also
6441               see the command line option -E).
6442
6443     smime-ca-dir, smime-ca-file
6444               [Option] Specify the location of trusted CA certificates in PEM
6445               (Privacy Enhanced Mail) for the purpose of verification of
6446               S/MIME signed messages.  tls-ca-dir documents the necessary
6447               preparation steps to use the former.  The set of CA certifi‐
6448               cates which are built into the TLS library can be explicitly
6449               turned off by setting smime-ca-no-defaults, and further fine-
6450               tuning is possible via smime-ca-flags.
6451
6452     smime-ca-flags
6453               [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6454               tificate storage, and the certificate verification that is
6455               used.  The actual values and their meanings are documented for
6456               tls-ca-flags.
6457
6458     smime-ca-no-defaults
6459               (Boolean)[Option] Do not load the default CA locations that are
6460               built into the used to TLS library to verify S/MIME signed mes‐
6461               sages.
6462
6463     smime-cipher-USER@HOST, smime-cipher
6464               [Option] Specifies the cipher to use when generating S/MIME en‐
6465               crypted messages (for the specified account).  RFC 5751 man‐
6466               dates a default of ‘aes128’ (AES-128 CBC).  Possible values are
6467               (case-insensitive and) in decreasing cipher strength: ‘aes256’
6468               (AES-256 CBC), ‘aes192’ (AES-192 CBC), ‘aes128’ (AES-128 CBC),
6469               ‘des3’ (DES EDE3 CBC, 168 bits; default if ‘aes128’ is not
6470               available) and ‘des’ (DES CBC, 56 bits).
6471
6472               The actually available cipher algorithms depend on the crypto‐
6473               graphic library that S-nail uses.  [Option] Support for more
6474               cipher algorithms may be available through dynamic loading via
6475               EVP_get_cipherbyname(3) (OpenSSL) if S-nail has been compiled
6476               to support this.
6477
6478     smime-crl-dir
6479               [Option] Specifies a directory that contains files with CRLs in
6480               PEM format to use when verifying S/MIME messages.
6481
6482     smime-crl-file
6483               [Option] Specifies a file that contains a CRL in PEM format to
6484               use when verifying S/MIME messages.
6485
6486     smime-encrypt-USER@HOST
6487               [Option] If this variable is set, messages send to the given
6488               receiver are encrypted before sending.  The value of the vari‐
6489               able must be set to the name of a file that contains a certifi‐
6490               cate in PEM format.
6491
6492               If a message is sent to multiple recipients, each of them for
6493               whom a corresponding variable is set will receive an individu‐
6494               ally encrypted message; other recipients will continue to re‐
6495               ceive the message in plain text unless the
6496               smime-force-encryption variable is set.  It is recommended to
6497               sign encrypted messages, i.e., to also set the smime-sign vari‐
6498               able.  content-description-smime-message will be inspected for
6499               messages which become encrypted.
6500
6501     smime-force-encryption
6502               (Boolean)[Option] Causes S-nail to refuse sending unencrypted
6503               messages.
6504
6505     smime-sign
6506               (Boolean)[Option] S/MIME sign outgoing messages with the user's
6507               (from) private key and include the users certificate as a MIME
6508               attachment.  Signing a message enables a recipient to verify
6509               that the sender used a valid certificate, that the email ad‐
6510               dresses in the certificate match those in the message header
6511               and that the message content has not been altered.  It does not
6512               change the message text, and people will be able to read the
6513               message as usual.  content-description-smime-signature will be
6514               inspected.  Also see smime-sign-cert, smime-sign-include-certs
6515               and smime-sign-digest.
6516
6517     smime-sign-cert-USER@HOST, smime-sign-cert
6518               [Option] Points to a file in PEM format.  For the purpose of
6519               signing and decryption this file needs to contain the user's
6520               private key, followed by his certificate.
6521
6522               For message signing ‘USER@HOST’ is always derived from the
6523               value of from (or, if that contains multiple addresses,
6524               sender).  For the purpose of encryption the recipients public
6525               encryption key (certificate) is expected; the command certsave
6526               can be used to save certificates of signed messages (the sec‐
6527               tion Signed and encrypted messages with S/MIME gives some de‐
6528               tails).  This mode of operation is usually driven by the spe‐
6529               cialized form.
6530
6531               When decrypting messages the account is derived from the recip‐
6532               ient fields (‘To:’ and ‘Cc:’) of the message, which are
6533               searched for addresses for which such a variable is set.
6534               S-nail always uses the first address that matches, so if the
6535               same message is sent to more than one of the user addresses us‐
6536               ing different encryption keys, decryption might fail.
6537
6538               Password-encrypted keys may be used for signing and decryption.
6539               Automated password lookup is possible via the “pseudo-hosts”
6540               ‘USER@HOST.smime-cert-key’ for the private key, and
6541               ‘USER@HOST.smime-cert-cert’ for the certificate stored in the
6542               same file.  For example, the hypothetical address
6543               ‘bob@exam.ple’ could be driven with a private key / certificate
6544               pair path defined in smime-sign-cert-bob@exam.ple, and the
6545               needed passwords would then be looked up as
6546               ‘bob@exam.ple.smime-cert-key’ and
6547               ‘bob@exam.ple.smime-cert-cert’.  When decrypting the value of
6548               from will be tried as a fallback to provide the necessary
6549               ‘USER@HOST’.  To include intermediate certificates, use
6550               smime-sign-include-certs.  The possible password sources are
6551               documented in On URL syntax and credential lookup.
6552
6553     smime-sign-digest-USER@HOST, smime-sign-digest
6554               [Option] Specifies the message digest to use when signing
6555               S/MIME messages.  Please remember that for this use case
6556               ‘USER@HOST’ refers to the variable from (or, if that contains
6557               multiple addresses, sender).  The available algorithms depend
6558               on the used cryptographic library, but at least one usable
6559               built-in algorithm is ensured as a default.  If possible the
6560               standard RFC 5751 will be violated by using ‘SHA512’ instead of
6561               the mandated ‘SHA1’ due to security concerns.  This variable is
6562               ignored for very old (released before 2010) cryptographic li‐
6563               braries which do not offer the necessary interface: it will be
6564               logged if that happened.
6565
6566               S-nail will try to add built-in support for the following mes‐
6567               sage digests, names are case-insensitive: ‘BLAKE2b512’,
6568               ‘BLAKE2s256’, ‘SHA3-512’, ‘SHA3-384’, ‘SHA3-256’, ‘SHA3-224’,
6569               as well as the widely available ‘SHA512’, ‘SHA384’, ‘SHA256’,
6570               ‘SHA224’, and the proposed insecure ‘SHA1’, finally ‘MD5’.
6571               More digests may [Option]ally be available through dynamic
6572               loading via the OpenSSL function EVP_get_digestbyname(3).
6573
6574     smime-sign-include-certs-USER@HOST, smime-sign-include-certs
6575               [Option] If used, this is supposed to a consist of a comma-sep‐
6576               arated list of files, each of which containing a single cer‐
6577               tificate in PEM format to be included in the S/MIME message in
6578               addition to the smime-sign-cert certificate.  This can be used
6579               to include intermediate certificates of the certificate author‐
6580               ity, in order to allow the receiver's S/MIME implementation to
6581               perform a verification of the entire certificate chain, start‐
6582               ing from a local root certificate, over the intermediate cer‐
6583               tificates, down to the smime-sign-cert.  Even though top level
6584               certificates may also be included in the chain, they will not
6585               be used for the verification on the receiver's side.
6586
6587               For the purpose of the mechanisms involved here, ‘USER@HOST’
6588               refers to the content of the internal variable from (or, if
6589               that contains multiple addresses, sender).  The pseudo-host
6590               ‘USER@HOST.smime-include-certs’ will be used for performing
6591               password lookups for these certificates, shall they have been
6592               given one, therefore the lookup can be automated via the mecha‐
6593               nisms described in On URL syntax and credential lookup.
6594
6595     smime-sign-message-digest-USER@HOST, smime-sign-message-digest
6596               [Obsolete][Option] Predecessor(s) of smime-sign-digest.
6597
6598     smtp      [Obsolete][Option] To use the built-in SMTP transport, specify
6599               a SMTP URL in mta.  [v15 behaviour may differ] For compatibil‐
6600               ity reasons a set smtp is used in preference of mta.
6601
6602     smtp-auth-USER@HOST, smtp-auth-HOST, smtp-auth
6603               [Option] Variable chain that controls the SMTP mta authentica‐
6604               tion method, possible values are ‘none’ ([no v15-compat] de‐
6605               fault), ‘plain’ ([v15-compat] default), ‘login’, [v15-compat]
6606               ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6607               OAUTHBEARER?) as well as [v15-compat] ‘external’ and
6608               ‘externanon’ for TLS secured connections which pass a client
6609               certificate via tls-config-pairs.  There may be the [Option]al
6610               methods ‘cram-md5’ and ‘gssapi’.  ‘none’ and ‘externanon’ do
6611               not need any user credentials, ‘external’ and ‘gssapi’ require
6612               a user name, and all other methods require a user name and a
6613               password.  ‘externanon’ solely builds upon the credentials
6614               passed via a client certificate, and is usually the way to go
6615               since tested servers do not actually follow RFC 4422 aka RFC
6616               4954, and fail if additional credentials are passed.  Also see
6617               mta.  Note that smtp-auth-HOST is [v15-compat].  ([no v15-com‐
6618               pat] Requires smtp-auth-password and smtp-auth-user.  Note for
6619               smtp-auth-USER@HOST: may override dependent on sender address
6620               in the variable from.)
6621
6622     smtp-auth-password
6623               [Option][no v15-compat] Sets the global fallback password for
6624               SMTP authentication.  If the authentication method requires a
6625               password, but neither smtp-auth-password nor a matching
6626               smtp-auth-password-USER@HOST can be found, S-nail will ask for
6627               a password on the user's terminal.
6628
6629     smtp-auth-password-USER@HOST
6630               [no v15-compat] Overrides smtp-auth-password for specific val‐
6631               ues of sender addresses, dependent upon the variable from.
6632
6633     smtp-auth-user
6634               [Option][no v15-compat] Sets the global fallback user name for
6635               SMTP authentication.  If the authentication method requires a
6636               user name, but neither smtp-auth-user nor a matching
6637               smtp-auth-user-USER@HOST can be found, S-nail will ask for a
6638               user name on the user's terminal.
6639
6640     smtp-auth-user-USER@HOST
6641               [no v15-compat] Overrides smtp-auth-user for specific values of
6642               sender addresses, dependent upon the variable from.
6643
6644     smtp-hostname
6645               [Option][v15-compat] Normally S-nail uses the variable from to
6646               derive the necessary ‘USER@HOST’ information in order to issue
6647               a ‘MAIL FROM:<>’ SMTP mta command.  Setting smtp-hostname can
6648               be used to use the ‘USER’ from the SMTP account (mta or the
6649               user variable chain) and the given ‘HOST’ (hostname if the
6650               empty string is given, or the local hostname as a last resort).
6651               This often allows using an address that is itself valid but
6652               hosted by a provider other than from which (in from) the mes‐
6653               sage is sent.  Setting this variable also influences generated
6654               ‘Message-ID:’ and ‘Content-ID:’ header fields.  If the [Op‐
6655               tion]al IDNA support is available (see idna-disable) variable
6656               assignment is aborted when a necessary conversion fails.
6657
6658     smtp-use-starttls-USER@HOST, smtp-use-starttls-HOST, smtp-use-starttls
6659               (Boolean)[Option] Causes S-nail to issue a ‘STARTTLS’ command
6660               to make an SMTP mta session TLS encrypted, i.e., to enable
6661               transport layer security.
6662
6663     socket-connect-timeout
6664               [Option] A positive number that defines the timeout to wait for
6665               establishing a socket connection before forcing ^ERR-TIMEDOUT.
6666
6667     socks-proxy-USER@HOST, socks-proxy-HOST, socks-proxy
6668               [Option] If set to the URL of a SOCKS5 server then all network
6669               activities are proxied through it, except for the single DNS
6670               name lookup necessary to resolve the proxy URL (unnecessary
6671               when given an already resolved IP address).  It is automati‐
6672               cally squared with the environment variable SOCKS5_PROXY,
6673               changing the one will adjust the other.  This example creates a
6674               local SOCKS5 proxy on port 10000 that forwards to the machine
6675               ‘HOST’ (with identity ‘USER’), and from which actual network
6676               traffic happens:
6677
6678                     $ ssh -D 10000 USER@HOST
6679                     $ s-nail -Ssocks-proxy=[socks5://]localhost:10000
6680                     # or =localhost:10000; no local DNS: =127.0.0.1:10000
6681
6682     spam-interface
6683               [Option] In order to use any of the spam-related commands (like
6684               spamrate) the desired spam interface must be defined by setting
6685               this variable.  Please refer to the manual section Handling
6686               spam for the complete picture of spam handling in S-nail.  All
6687               or none of the following interfaces may be available:
6688
6689               ‘spamc’   Interaction with spamc(1) from the spamassassin(1)
6690                         (SpamAssassin: http://spamassassin.apache.org) suite.
6691                         Different to the generic filter interface S-nail will
6692                         automatically add the correct arguments for a given
6693                         command and has the necessary knowledge to parse the
6694                         program's output.  A default value for spamc-command
6695                         will have been compiled into the S-nail binary if
6696                         spamc(1) has been found in PATH during compilation.
6697                         Shall it be necessary to define a specific connection
6698                         type (rather than using a configuration file for
6699                         that), the variable spamc-arguments can be used as in
6700                         for example ‘-d server.example.com -p 783’.  It is
6701                         also possible to specify a per-user configuration via
6702                         spamc-user.  Note that this interface does not in‐
6703                         spect the ‘is-spam’ flag of a message for the command
6704                         spamforget.
6705
6706               ‘filter’  generic spam filter support via freely configurable
6707                         hooks.  This interface is meant for programs like
6708                         bogofilter(1) and requires according behaviour in re‐
6709                         spect to the hooks' exit status for at least the com‐
6710                         mand spamrate (‘0’ meaning a message is spam, ‘1’ for
6711                         non-spam, ‘2’ for unsure and any other return value
6712                         indicating a hard error); since the hooks can include
6713                         shell code snippets diverting behaviour can be inter‐
6714                         cepted as necessary.  The hooks are spamfilter-ham,
6715                         spamfilter-noham, spamfilter-nospam, spamfilter-rate
6716                         and spamfilter-spam; the manual section Handling spam
6717                         contains examples for some programs.  The process en‐
6718                         vironment of the hooks will have the variable
6719                         MAILX_FILENAME_GENERATED set.  Note that spam score
6720                         support for spamrate is not supported unless the [Op‐
6721                         tion]tional regular expression support is available
6722                         and the spamfilter-rate-scanscore variable is set.
6723
6724     spam-maxsize
6725               [Option] Messages that exceed this size will not be passed
6726               through to the configured spam-interface.  If unset or 0, the
6727               default of 420000 bytes is used.
6728
6729     spamc-command
6730               [Option] The path to the spamc(1) program for the ‘spamc’
6731               spam-interface.  Note that the path is not expanded, but used
6732               “as is”.  A fallback path will have been compiled into the
6733               S-nail binary if the executable had been found during compila‐
6734               tion.
6735
6736     spamc-arguments
6737               [Option] Even though S-nail deals with most arguments for the
6738               ‘spamc’ spam-interface automatically, it may at least sometimes
6739               be desirable to specify connection-related ones via this vari‐
6740               able, for example ‘-d server.example.com -p 783’.
6741
6742     spamc-user
6743               [Option] Specify a username for per-user configuration files
6744               for the ‘spamc’ spam-interface.  If this is set to the empty
6745               string then S-nail will use the name of the current user.
6746
6747     spamfilter-ham, spamfilter-noham, spamfilter-nospam, spamfilter-rate,
6748               spamfilter-spam
6749               [Option] Command and argument hooks for the ‘filter’
6750               spam-interface.  The manual section Handling spam contains ex‐
6751               amples for some programs.
6752
6753     spamfilter-rate-scanscore
6754               [Option] Because of the generic nature of the ‘filter’
6755               spam-interface spam scores are not supported for it by default,
6756               but if the [Option]nal regular expression support is available
6757               then setting this variable can be used to overcome this re‐
6758               striction.  It is interpreted as follows: first a number (dig‐
6759               its) is parsed that must be followed by a semicolon ‘;’ and an
6760               extended regular expression.  Then the latter is used to parse
6761               the first output line of the spamfilter-rate hook, and, in case
6762               the evaluation is successful, the group that has been specified
6763               via the number is interpreted as a floating point scan score.
6764
6765     ssl-ca-dir-USER@HOST, ssl-ca-dir-HOST, ssl-ca-dir, ssl-ca-file-USER@HOST,
6766               ssl-ca-file-HOST, ssl-ca-file
6767               [Obsolete][Option] Predecessors of tls-ca-file, tls-ca-dir.
6768
6769     ssl-ca-flags-USER@HOST, ssl-ca-flags-HOST, ssl-ca-flags
6770               [Obsolete][Option] Predecessor of tls-ca-flags.
6771
6772     ssl-ca-no-defaults-USER@HOST, ssl-ca-no-defaults-HOST, ssl-ca-no-defaults
6773               [Obsolete](Boolean)[Option] Predecessor of tls-ca-no-defaults.
6774
6775     ssl-cert-USER@HOST, ssl-cert-HOST, ssl-cert
6776               [Obsolete][Option] Please use the Certificate slot of
6777               tls-config-pairs.
6778
6779     ssl-cipher-list-USER@HOST, ssl-cipher-list-HOST, ssl-cipher-list
6780               [Obsolete][Option] Please use the CipherString slot of
6781               tls-config-pairs.
6782
6783     ssl-config-file
6784               [Obsolete][Option] Predecessor of tls-config-file.
6785
6786     ssl-config-module-USER@HOST, ssl-config-module-HOST, ssl-config-module
6787               [Obsolete][Option] Predecessor of tls-config-module.
6788
6789     ssl-config-pairs-USER@HOST, ssl-config-pairs-HOST, ssl-config-pairs
6790               [Obsolete][Option] Predecessor of tls-config-pairs.
6791
6792     ssl-crl-dir, ssl-crl-file
6793               [Obsolete][Option] Predecessors of tls-crl-dir, tls-crl-file.
6794
6795     ssl-curves-USER@HOST, ssl-curves-HOST, ssl-curves
6796               [Obsolete][Option] Please use the Curves slot of
6797               tls-config-pairs.
6798
6799     ssl-features
6800               [Obsolete][Option](Read-only) Predecessor of tls-features.
6801
6802     ssl-key-USER@HOST, ssl-key-HOST, ssl-key
6803               [Obsolete][Option] Please use the PrivateKey slot of
6804               tls-config-pairs.
6805
6806     ssl-method-USER@HOST, ssl-method-HOST, ssl-method
6807               [Obsolete][Option] Please use the Protocol slot of
6808               tls-config-pairs.
6809
6810     ssl-protocol-USER@HOST, ssl-protocol-HOST, ssl-protocol
6811               [Obsolete][Option] Please use the Protocol slot of
6812               tls-config-pairs.
6813
6814     ssl-rand-file
6815               [Obsolete][Option] Predecessor of tls-rand-file.
6816
6817     ssl-verify-USER@HOST, ssl-verify-HOST, ssl-verify
6818               [Obsolete][Option] Predecessor of tls-verify.
6819
6820     stealthmua
6821               If only set without an assigned value, then this setting in‐
6822               hibits the generation of the ‘Message-ID:’, ‘Content-ID:’ and
6823               ‘User-Agent:’ header fields that include obvious references to
6824               S-nail.  There are two pitfalls associated with this: First,
6825               the message id of outgoing messages is not known anymore.  Sec‐
6826               ond, an expert may still use the remaining information in the
6827               header to track down the originating mail user agent.  If set
6828               to the value ‘noagent’, then the mentioned ‘Message-ID:’ and
6829               ‘Content-ID:’ suppression does not occur.
6830
6831     system-mailrc
6832               (Read-only) The compiled in path of the system wide initializa‐
6833               tion file one of the Resource files: s-nail.rc.
6834
6835     termcap   ([Option]) This specifies a comma-separated list of Terminal
6836               Information Library (libterminfo, -lterminfo) and/or Termcap
6837               Access Library (libtermcap, -ltermcap) capabilities (see On
6838               terminal control and line editor, escape commas with reverse
6839               solidus ‘\’) to be used to overwrite or define entries.  Note
6840               this variable will only be queried once at program startup and
6841               can thus only be specified in resource files or on the command
6842               line.  It will always be inspected, regardless of whether
6843               features denotes termcap/terminfo library support via
6844               ‘,+termcap,’.
6845
6846               String capabilities form ‘cap=value’ pairs and are expected un‐
6847               less noted otherwise.  Numerics have to be notated as
6848               ‘cap#number’ where the number is expected in normal decimal no‐
6849               tation.  Finally, booleans do not have any value but indicate a
6850               true or false state simply by being defined or not; this indeed
6851               means that S-nail does not support undefining an existing bool‐
6852               ean.  String capability values will undergo some expansions be‐
6853               fore use: for one notations like ‘^LETTER’ stand for
6854               ‘control-LETTER’, and for clarification purposes ‘\E’ can be
6855               used to specify ‘escape’ (the control notation ‘^[’ could lead
6856               to misreadings when a left bracket follows, which it does for
6857               the standard CSI sequence); finally three letter octal se‐
6858               quences, as in ‘\061’, are supported.  To specify that a termi‐
6859               nal supports 256-colours, and to define sequences that home the
6860               cursor and produce an audible bell, one might write:
6861
6862                     ? set termcap='Co#256,home=\E[H,bel=^G'
6863
6864               The following terminal capabilities are or may be meaningful
6865               for the operation of the built-in line editor or S-nail in gen‐
6866               eral:
6867
6868               am        auto_right_margin: boolean which indicates if the
6869                         right margin needs special treatment; the xenl capa‐
6870                         bility is related, for more see COLUMNS.  This capa‐
6871                         bility is only used when backed by library support.
6872               clear or cl
6873                         clear_screen: clear the screen and home cursor.
6874                         (Will be simulated via ho plus cd.)
6875               colors or Co
6876                         max_colors: numeric capability specifying the maximum
6877                         number of colours.  Note that S-nail does not actu‐
6878                         ally care about the terminal beside that, but always
6879                         emits ANSI / ISO 6429 escape sequences; also see
6880                         colour.
6881               cr        carriage_return: move to the first column in the cur‐
6882                         rent row.  The default built-in fallback is ‘\r’.
6883               cub1 or le
6884                         cursor_left: move the cursor left one space (non-de‐
6885                         structively).  The default built-in fallback is ‘\b’.
6886               cuf1 or nd
6887                         cursor_right: move the cursor right one space (non-
6888                         destructively).  The default built-in fallback is
6889                         ‘\E[C’, which is used by most terminals.  Less often
6890                         occur ‘\EC’ and ‘\EOC’.
6891               ed or cd  clr_eos: clear the screen.
6892               el or ce  clr_eol: clear to the end of line.  (Will be simu‐
6893                         lated via ch plus repetitions of space characters.)
6894               home or ho
6895                         cursor_home: home cursor.
6896               hpa or ch
6897                         column_address: move the cursor (to the given column
6898                         parameter) in the current row.  (Will be simulated
6899                         via cr plus nd.)
6900               rmcup or te / smcup or ti
6901                         exit_ca_mode and enter_ca_mode, respectively: exit
6902                         and enter the alternative screen ca-mode, effectively
6903                         turning S-nail into a fullscreen application.  This
6904                         must be enabled explicitly by setting
6905                         termcap-ca-mode.
6906               smkx or ks / rmkx or ke
6907                         keypad_xmit and keypad_local, respectively: enable
6908                         and disable the keypad.  This is always enabled if
6909                         available, because it seems even keyboards without
6910                         keypads generate other key codes for, e.g., cursor
6911                         keys in that case, and only if enabled we see the
6912                         codes that we are interested in.
6913               xenl or xn
6914                         eat_newline_glitch: boolean which indicates whether a
6915                         newline written in the last column of an
6916                         auto_right_margin indicating terminal is ignored.
6917                         With it the full terminal width is available even on
6918                         autowrap terminals.  This will be inspected even
6919                         without ‘,+termcap,’ features.
6920
6921               Many more capabilities which describe key-sequences are docu‐
6922               mented for bind.
6923
6924     termcap-ca-mode
6925               [Option] Allow usage of the exit_ca_mode and enter_ca_mode
6926               termcapabilities in order to enter an alternative exclusive
6927               screen, the so-called ca-mode; this usually requires special
6928               configuration of the PAGER, also dependent on the value of crt.
6929               Note this variable will only be queried once at program startup
6930               and can thus only be specified in resource files or on the com‐
6931               mand line.
6932
6933     termcap-disable
6934               [Option] Disable any interaction with a terminal control li‐
6935               brary.  If set only some generic fallback built-ins and possi‐
6936               bly the content of termcap describe the terminal to S-nail.
6937               Note this variable will only be queried once at program startup
6938               and can thus only be specified in resource files or on the com‐
6939               mand line.
6940
6941     tls-ca-dir-USER@HOST, tls-ca-dir-HOST, tls-ca-dir, tls-ca-file-USER@HOST,
6942               tls-ca-file-HOST, tls-ca-file
6943               [Option] Directory and file, respectively, for pools of trusted
6944               CA certificates in PEM (Privacy Enhanced Mail) format, for the
6945               purpose of verification of TLS server certificates.  Concurrent
6946               use is possible, the file is loaded once needed first, the di‐
6947               rectory lookup is performed anew as a last resort whenever nec‐
6948               essary.  The CA certificate pool built into the TLS library can
6949               be disabled via tls-ca-no-defaults, further fine-tuning is pos‐
6950               sible via tls-ca-flags.  The directory search requires special
6951               filename conventions, please see
6952               SSL_CTX_load_verify_locations(3) and verify(1) (or
6953               c_rehash(1)).
6954
6955     tls-ca-flags-USER@HOST, tls-ca-flags-HOST, tls-ca-flags
6956               [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6957               tificate storage, and the certificate verification that is used
6958               (also see tls-verify).  The value is expected to consist of a
6959               comma-separated list of configuration directives, with any in‐
6960               tervening whitespace being ignored.  The directives directly
6961               map to flags that can be passed to X509_STORE_set_flags(3),
6962               which are usually defined in a file openssl/x509_vfy.h, and the
6963               availability of which depends on the used TLS library version:
6964               a directive without mapping is ignored (error log subject to
6965               debug).  Directives currently understood (case-insensitively)
6966               include:
6967
6968               no-alt-chains
6969                         If the initial chain is not trusted, do not attempt
6970                         to build an alternative chain.  Setting this flag
6971                         will make OpenSSL certificate verification match that
6972                         of older OpenSSL versions, before automatic building
6973                         and checking of alternative chains has been imple‐
6974                         mented; also see trusted-first.
6975               no-check-time
6976                         Do not check certificate/CRL validity against current
6977                         time.
6978               partial-chain
6979                         By default partial, incomplete chains which cannot be
6980                         verified up to the chain top, a self-signed root cer‐
6981                         tificate, will not verify.  With this flag set, a
6982                         chain succeeds to verify if at least one signing cer‐
6983                         tificate of the chain is in any of the configured
6984                         trusted stores of CA certificates.  The OpenSSL man‐
6985                         ual page SSL_CTX_load_verify_locations(3) gives some
6986                         advise how to manage your own trusted store of CA
6987                         certificates.
6988               strict    Disable workarounds for broken certificates.
6989               trusted-first
6990                         Try building a chain using issuers in the trusted
6991                         store first to avoid problems with server-sent legacy
6992                         intermediate certificates.  Newer versions of OpenSSL
6993                         support alternative chain checking and enable it by
6994                         default, resulting in the same behaviour; also see
6995                         no-alt-chains.
6996
6997     tls-ca-no-defaults-USER@HOST, tls-ca-no-defaults-HOST, tls-ca-no-defaults
6998               (Boolean)[Option] Do not load the default CA locations that are
6999               built into the used to TLS library to verify TLS server cer‐
7000               tificates.
7001
7002     tls-config-file
7003               [Option] If this variable is set CONF_modules_load_file(3) (if
7004               announced via ‘,+modules-load-file,’ in tls-features) is used
7005               to allow resource file based configuration of the TLS library.
7006               This happens once the library is used first, which may also be
7007               early during startup (logged with verbose)!  If a non-empty
7008               value is given then the given file, after performing Filename
7009               transformations, will be used instead of the TLS libraries
7010               global default, and it is an error if the file cannot be
7011               loaded.  The application name will always be passed as
7012               ‘s-nail’.  Some TLS libraries support application-specific con‐
7013               figuration via resource files loaded like this, please see
7014               tls-config-module.
7015
7016     tls-config-module-USER@HOST, tls-config-module-HOST, tls-config-module
7017               [Option] If file based application-specific configuration via
7018               tls-config-file is available, announced as ‘,+ctx-config,’ by
7019               tls-features, indicating availability of SSL_CTX_config(3),
7020               then, it becomes possible to use a central TLS configuration
7021               file for all programs, including s-nail, for example
7022
7023                     # Register a configuration section for s-nail
7024                     s-nail = mailx_master
7025                     # The top configuration section creates a relation
7026                     # in between dynamic SSL configuration and an actual
7027                     # program specific configuration section
7028                     [mailx_master]
7029                     ssl_conf = mailx_tls_config
7030                     # And that program specific configuration section now
7031                     # can map diverse tls-config-module names to sections,
7032                     # as in: tls-config-module=account_xy
7033                     [mailx_tls_config]
7034                     account_xy = mailx_account_xy
7035                     account_yz = mailx_account_yz
7036                     [mailx_account_xy]
7037                     MinProtocol = TLSv1.2
7038                     Curves=P-521
7039                     [mailx_account_yz]
7040                     CipherString = TLSv1.2:!aNULL:!eNULL:
7041                     MinProtocol = TLSv1.1
7042                     Options = Bugs
7043
7044     tls-config-pairs-USER@HOST, tls-config-pairs-HOST, tls-config-pairs
7045               [Option] The value of this variable chain will be interpreted
7046               as a comma-separated list of directive/value pairs.  Directives
7047               and values need to be separated by equals signs ‘=’, any white‐
7048               space surrounding pair members is removed.  Keys are (usually)
7049               case-insensitive.  Different to when placing these pairs in a
7050               tls-config-module section of a tls-config-file, commas ‘,’ need
7051               to be escaped with a reverse solidus ‘\’ when included in
7052               pairs; also different: if the equals sign ‘=’ is preceded with
7053               an asterisk ‘*’ Filename transformations will be performed on
7054               the value; it is an error if these fail.  Unless proper support
7055               is announced by tls-features (‘,+conf-ctx,’) only the keys be‐
7056               low are supported, otherwise the pairs will be used directly as
7057               arguments to the function SSL_CONF_cmd(3).
7058
7059               Certificate   Filename of a TLS client certificate (chain) re‐
7060                             quired by some servers.  Fallback support via
7061                             SSL_CTX_use_certificate_chain_file(3).  Filename
7062                             transformations are performed.  PrivateKey will
7063                             be set to the same value if not initialized ex‐
7064                             plicitly.  Some services support so-called
7065                             ‘external’ authentication if a TLS client cer‐
7066                             tificate was successfully presented during con‐
7067                             nection establishment (“connecting is
7068                             authenticating”).
7069               CipherString  A list of ciphers for TLS connections, see
7070                             ciphers(1).  By default no list of ciphers is
7071                             set, resulting in a Protocol-specific list of ci‐
7072                             phers (the protocol standards define lists of ac‐
7073                             ceptable ciphers; possibly cramped by the used
7074                             TLS library).  Fallback support via
7075                             SSL_CTX_set_cipher_list(3).
7076               Ciphersuites  A list of ciphers used for TLSv1.3 connections,
7077                             see ciphers(1).  These will be joined onto the
7078                             list of ciphers from CipherString.  Available if
7079                             tls-features announces ‘,+ctx-set-ciphersuites,’,
7080                             as necessary via SSL_CTX_set_ciphersuites(3).
7081               Curves        A list of supported elliptic curves, if applica‐
7082                             ble.  By default no curves are set.  Fallback
7083                             support via SSL_CTX_set1_curves_list(3), if
7084                             available.
7085               MaxProtocol, MinProtocol
7086                             The maximum and minimum supported TLS versions,
7087                             respectively.  Available if tls-features an‐
7088                             nounces ‘,+ctx-set-maxmin-proto,’, as necessary
7089                             via SSL_CTX_set_max_proto_version(3) and
7090                             SSL_CTX_set_min_proto_version(3); these fallbacks
7091                             use an internal parser which understands the
7092                             strings ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7093                             ‘TLSv1.3’, and the special value ‘None’, which
7094                             disables the given limit.
7095               Options       Various flags to set.  Fallback via
7096                             SSL_CTX_set_options(3), in which case any other
7097                             value but (exactly) ‘Bugs’ results in an error.
7098               PrivateKey    Filename of the private key in PEM format of a
7099                             TLS client certificate.  If unset, the value of
7100                             Certificate is used.  Filename transformations
7101                             are performed.  Fallback via
7102                             SSL_CTX_use_PrivateKey_file(3).
7103               Protocol      The used TLS protocol.  If tls-features announces
7104                             ‘,+conf-ctx,’ or ‘ctx-set-maxmin-proto’ then us‐
7105                             ing MaxProtocol and MinProtocol is preferable.
7106                             Fallback is SSL_CTX_set_options(3), driven via an
7107                             internal parser which understands the strings
7108                             ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7109                             ‘TLSv1.3’, and the special value ‘ALL’.  Multiple
7110                             protocols may be given as a comma-separated list,
7111                             any whitespace is ignored, an optional plus sign
7112                             ‘+’ prefix enables, a hyphen-minus ‘-’ prefix
7113                             disables a protocol, so that ‘-ALL, TLSv1.2’ en‐
7114                             ables only the TLSv1.2 protocol.
7115
7116     tls-crl-dir, tls-crl-file
7117               [Option] Specify a directory / a file, respectively, that con‐
7118               tains a CRL in PEM format to use when verifying TLS server cer‐
7119               tificates.
7120
7121     tls-features
7122               [Option](Read-only) This expands to a comma-separated list of
7123               the TLS library identity and optional features.  To ease sub‐
7124               string matching the string starts and ends with a comma.  Cur‐
7125               rently supported identities are ‘libressl’ (LibreSSL) ,
7126               ‘libssl-0x30000’ (OpenSSL v3.0.0 series), ‘libssl-0x10100’
7127               (OpenSSL v1.1.x series) and ‘libssl-0x10000’ (elder OpenSSL se‐
7128               ries, other clones).  Optional features are preceded with a
7129               plus sign ‘+’ when available, and with a hyphen-minus ‘-’ oth‐
7130               erwise.
7131
7132               Currently known features are ‘conf-ctx’ (tls-config-pairs),
7133               ‘ctx-config’ (tls-config-module), ‘ctx-set-ciphersuites’
7134               (Ciphersuites slot of tls-config-pairs), ‘ctx-set-maxmin-proto’
7135               (tls-config-pairs), ‘modules-load-file’ (tls-config-file), and
7136               ‘tls-rand-file’ (tls-rand-file).
7137
7138     tls-fingerprint-USER@HOST, tls-fingerprint-HOST, tls-fingerprint
7139               [Option] It is possible to replace the verification of the con‐
7140               nection peer certificate against the entire local pool of CAs
7141               (for more see Encrypted network communication) with the compar‐
7142               ison against a precalculated certificate message digest, the
7143               so-called fingerprint, to be specified as the used
7144               tls-fingerprint-digest.  This fingerprint can for example be
7145               calculated with ‘tls fingerprint HOST’.
7146
7147     tls-fingerprint-digest-USER@HOST, tls-fingerprint-digest-HOST,
7148               tls-fingerprint-digest
7149               [Option] The message digest to be used when creating TLS cer‐
7150               tificate fingerprints, the defaults, if available, in test or‐
7151               der, being ‘BLAKE2s256’, ‘SHA256’.  For the complete list of
7152               digest algorithms refer to smime-sign-digest.
7153
7154     tls-rand-file
7155               [Option] If tls-features announces ‘,+tls-rand-file,’ then this
7156               will be queried to find a file with random entropy data which
7157               can be used to seed the P(seudo)R(andom)N(umber)G(enerator),
7158               see RAND_load_file(3).  The default filename
7159               (RAND_file_name(3), normally ~/.rnd) will be used if this vari‐
7160               able is not set or empty, or if the Filename transformations
7161               fail.  Shall seeding the PRNG have been successful,
7162               RAND_write_file(3) will be called to update the entropy.  Re‐
7163               marks: libraries which do not announce this feature seed the
7164               PRNG by other means.
7165
7166     tls-verify-USER@HOST, tls-verify-HOST, tls-verify
7167               [Option] Variable chain that sets the action to be performed if
7168               an error occurs during TLS server certificate validation
7169               against the specified or default trust stores tls-ca-dir,
7170               tls-ca-file, or the TLS library built-in defaults (unless usage
7171               disallowed via tls-ca-no-defaults), and as fine-tuned via
7172               tls-ca-flags.  Valid (case-insensitive) values are ‘strict’
7173               (fail and close connection immediately), ‘ask’ (ask whether to
7174               continue on standard input), ‘warn’ (show a warning and con‐
7175               tinue), ‘ignore’ (do not perform validation).  The default is
7176               ‘ask’.
7177
7178     toplines  If defined, gives the number of lines of a message to be dis‐
7179               played with the command top; if unset, the first five lines are
7180               printed, if set to 0 the variable screen is inspected.  If the
7181               value is negative then its absolute value will be used for un‐
7182               signed right shifting (see vexpr) the screen height.
7183
7184     topsqueeze
7185               (Boolean) If set then the top command series will strip adja‐
7186               cent empty lines and quotations.
7187
7188     ttycharset
7189               The character set of the terminal S-nail operates on, and the
7190               one and only supported character set that S-nail can use if no
7191               character set conversion capabilities have been compiled into
7192               it, in which case it defaults to ISO-8859-1.  Otherwise it de‐
7193               faults to UTF-8.  Sufficient locale support provided the de‐
7194               fault will be preferably deduced from the locale environment if
7195               that is set (for example LC_CTYPE, see there for more); runtime
7196               locale changes will be reflected by ttycharset except during
7197               the program startup phase and if -S had been used to freeze the
7198               given value.  Refer to the section Character sets for the com‐
7199               plete picture about character sets.
7200
7201     typescript-mode
7202               (Boolean) A special multiplex variable that disables all vari‐
7203               ables and settings which result in behaviour that interferes
7204               with running S-nail in script(1); it sets colour-disable,
7205               line-editor-disable and (before startup completed only)
7206               termcap-disable.  Unsetting it does not restore the former
7207               state of the covered settings.
7208
7209     umask     For a safe-by-default policy the process file mode creation
7210               mask umask(2) will be set to ‘0077’ on program startup after
7211               the resource files have been loaded, and unless this variable
7212               is set.  By assigning this an empty value the active setting
7213               will not be changed, otherwise the given value will be made the
7214               new file mode creation mask.  Child processes inherit the file
7215               mode creation mask of their parent.
7216
7217     user-HOST, user
7218               [v15-compat] Variable chain that sets a global fallback user
7219               name, used in case none has been given in the protocol and ac‐
7220               count-specific URL.  This variable defaults to the name of the
7221               user who runs S-nail.
7222
7223     v15-compat
7224               Enable upward compatibility with S-nail version 15.0 in respect
7225               to which configuration options are available and how they are
7226               handled.  If set to a non-empty value the command modifier wysh
7227               is implied and thus enforces Shell-style argument quoting over
7228               Old-style argument quoting for all commands which support both.
7229               This manual uses [v15-compat] and [no v15-compat] to refer to
7230               the new and the old way of doing things, respectively.
7231
7232     verbose   Verbose mode enables logging of informational context messages.
7233               Historically a (Boolean) variable, this can either be set mul‐
7234               tiple times (what the command line option -v uses), or be as‐
7235               signed a numeric value in order to increase verbosity.  Assign‐
7236               ing the value 0 disables verbosity and thus (almost) equals
7237               unset.  The maximum number is 3.  Also see debug.
7238
7239     version, version-date, version-hexnum, version-major, version-minor,
7240               version-update
7241               (Read-only) S-nail version information: the first variable is a
7242               string with the complete version identification, the second the
7243               release date in ISO 8601 notation without time.  The third is a
7244               32-bit hexadecimal number with the upper 8 bits storing the ma‐
7245               jor, followed by the minor and update version numbers which oc‐
7246               cupy 12 bits each.  The latter three variables contain only
7247               decimal digits: the major, minor and update version numbers.
7248               The output of the command version will include this informa‐
7249               tion.
7250
7251     writebackedited
7252               If this variable is set messages modified using the edit or
7253               visual commands are written back to the current folder when it
7254               is quit; it is only honoured for writable folders in MBOX for‐
7255               mat, though.  Note that the editor will be pointed to the raw
7256               message content in that case, i.e., neither MIME decoding nor
7257               decryption will have been performed, and proper mbox-rfc4155
7258               ‘From_’ quoting of newly added or edited content is also left
7259               as an exercise to the user.
7260

ENVIRONMENT

7262     The term “environment variable” should be considered an indication that
7263     these variables are either standardized as vivid parts of process envi‐
7264     ronments, or that they are commonly found in there.  The process environ‐
7265     ment is inherited from the sh(1) once S-nail is started, and unless oth‐
7266     erwise explicitly noted handling of the following variables transparently
7267     integrates into that of the INTERNAL VARIABLES from S-nail's point of
7268     view.  This means they can be managed via set and unset, causing auto‐
7269     matic program environment updates (to be inherited by newly created child
7270     processes).
7271
7272     In order to integrate other environment variables equally they need to be
7273     imported (linked) with the command environ.  This command can also be
7274     used to set and unset non-integrated environment variables from scratch,
7275     sufficient system support provided.  The following example, applicable to
7276     a POSIX shell, sets the COLUMNS environment variable for S-nail only, and
7277     beforehand exports the EDITOR in order to affect any further processing
7278     in the running shell:
7279
7280           $ EDITOR="vim -u ${HOME}/.vimrc"
7281           $ export EDITOR
7282           $ COLUMNS=80 s-nail -R
7283
7284     COLUMNS   The user's preferred width in column positions for the terminal
7285               screen.  Queried and used once on program startup in interac‐
7286               tive or batch (-#) mode, actively managed for child processes
7287               and the MLE (see On terminal control and line editor) in inter‐
7288               active mode thereafter.  Non-interactive mode always uses, and
7289               the fallback default is a compile-time constant, by default 80
7290               columns.  If in batch mode COLUMNS and LINES are both set but
7291               not both are usable (empty, not a number, or 0) at program
7292               startup, then the real terminal screen size will be (tried to
7293               be) determined once.  (Normally the sh(1) manages these vari‐
7294               ables, and unsets them for pipe specifications etc.)
7295
7296     DEAD      The name of the (mailbox) folder to use for saving aborted mes‐
7297               sages if save is set; this defaults to ~/dead.letter.  If the
7298               variable debug is set no output will be generated, otherwise
7299               the contents of the file will be replaced.  Except shell globs
7300               Filename transformations (also see folder) will be performed.
7301
7302     EDITOR    Pathname of the text editor to use for the edit command and ~e
7303               (see COMMAND ESCAPES); VISUAL is used for a more display ori‐
7304               ented editor.
7305
7306     HOME      The user's home directory.  This variable is only used when it
7307               resides in the process environment.  The calling user's home
7308               directory will be used instead if this directory does not ex‐
7309               ist, is not accessible or cannot be read; it will always be
7310               used for the root user.  (No test for being writable is per‐
7311               formed to allow usage by non-privileged users within read-only
7312               jails, but dependent on settings this directory is a default
7313               write target for, for example, DEAD, MBOX and more.)
7314
7315     LC_ALL, LC_CTYPE, LANG
7316               [Option] The (names in lookup order of the) locale(7) (and / or
7317               see setlocale(3)) which indicates the used Character sets.
7318               Runtime changes trigger automatic updates of the entire locale
7319               system, which includes updating ttycharset (except during
7320               startup if the variable has been frozen via -S).
7321
7322     LINES     The user's preferred number of lines for the terminal screen.
7323               The behaviour is as described for COLUMNS, yet the compile-time
7324               constant used in non-interactive mode and as a fallback de‐
7325               faults to 24 (lines).
7326
7327     LISTER    Pathname of the directory lister to use in the folders command
7328               when operating on local mailboxes.  Default is ls(1) (path
7329               search through SHELL).
7330
7331     LOGNAME   Upon startup S-nail will actively ensure that this variable
7332               refers to the name of the user who runs S-nail, in order to be
7333               able to pass a verified name to any newly created child
7334               process.
7335
7336     MAIL      Is used as the user's primary system mailbox unless inbox is
7337               set.  If the environmental fallback is also not set, a built-in
7338               compile-time default is used.  This is assumed to be an abso‐
7339               lute pathname.
7340
7341     MAILCAPS  [Option] Override the default path search of The Mailcap files:
7342               any existing file therein will be loaded in sequence, appending
7343               any content to the list of MIME type handler directives.  The
7344               RFC 1524 standard imposed default value is assigned otherwise:
7345               ‘~/.mailcap:/etc/mailcap:/usr/etc/mailcap:
7346               /usr/local/etc/mailcap’.  (The default value is a compile-time
7347               [Option].)
7348
7349     MAILRC    Is used as a startup file instead of ~/.mailrc if set.  In or‐
7350               der to avoid side-effects from configuration files scripts
7351               should either set this variable to /dev/null or the -: command
7352               line option should be used.
7353
7354     MAILX_NO_SYSTEM_RC
7355               If this variable is set then reading of s-nail.rc (aka
7356               system-mailrc) at startup is inhibited, i.e., the same effect
7357               is achieved as if S-nail had been started up with the option -:
7358               (and according argument) or -n.  This variable is only used
7359               when it resides in the process environment.
7360
7361     MBOX      The name of the user's secondary mailbox file.  A logical sub‐
7362               set of the special Filename transformations (also see folder)
7363               are supported.  The default is ~/mbox.  Traditionally this MBOX
7364               is used as the file to save messages from the primary system
7365               mailbox that have been read.  Also see Message states.
7366
7367     NETRC     [v15-compat][Option] This variable overrides the default loca‐
7368               tion of the user's ~/.netrc file.
7369
7370     PAGER     Pathname of the program to use for backing the command more,
7371               and when the crt variable enforces usage of a pager for output.
7372               The default paginator is more(1) (path search through SHELL).
7373
7374               S-nail inspects the contents of this variable: if its contains
7375               the string “less” then a non-existing environment variable LESS
7376               will be set to (the portable) ‘RI’, likewise for “lv” LV will
7377               optionally be set to ‘-c’.  Also see colour-pager.
7378
7379     PATH      A colon-separated list of directories that is searched by the
7380               shell when looking for commands, for example
7381               ‘/bin:/usr/bin:/usr/local/bin’.
7382
7383     POSIXLY_CORRECT
7384               This environment entry is automatically squared with posix.
7385
7386     SHELL     The shell to use for the commands !, shell, the ~! COMMAND
7387               ESCAPES and when starting subprocesses.  A default shell is
7388               used if this environment variable is not defined.
7389
7390     SOCKS5_PROXY
7391               This environment entry is automatically squared with
7392               socks-proxy.
7393
7394     SOURCE_DATE_EPOCH
7395               Specifies a time in seconds since the Unix epoch (1970-01-01)
7396               to be used in place of the current time.  This variable is
7397               looked up upon program startup, and its existence will switch
7398               S-nail to a reproducible mode (https://reproducible-builds.org)
7399               which uses deterministic random numbers, a special fixated
7400               pseudo LOGNAME and more.  This operation mode is used for de‐
7401               velopment and by software packagers.  [v15 behaviour may dif‐
7402               fer] Currently an invalid setting is only ignored, rather than
7403               causing a program abortion.
7404
7405                     $ SOURCE_DATE_EPOCH=`date +%s` s-nail
7406
7407     TERM      [Option] The terminal type for which output is to be prepared.
7408               For extended colour and font control please refer to Coloured
7409               display, and for terminal management in general to On terminal
7410               control and line editor.
7411
7412     TMPDIR    Except for the root user this variable defines the directory
7413               for temporary files to be used instead of /tmp (or the given
7414               compile-time constant) if set, existent, accessible as well as
7415               read- and writable.  This variable is only used when it resides
7416               in the process environment, but S-nail will ensure at startup
7417               that this environment variable is updated to contain a usable
7418               temporary directory.
7419
7420     USER      Identical to LOGNAME (see there), but this variable is not
7421               standardized, should therefore not be used, and is only cor‐
7422               rected if already set.
7423
7424     VISUAL    Pathname of the text editor to use for the visual command and
7425               ~v (see COMMAND ESCAPES); EDITOR is used for a less display
7426               oriented editor.
7427

FILES

7429     ~/.mailcap, /etc/mailcap
7430               [Option] Personal and system-wide MIME type handler definition
7431               files, see The Mailcap files.  (The shown names are part of the
7432               RFC 1524 standard search path MAILCAPS.)
7433
7434     ~/.mailrc, s-nail.rc
7435               User-specific and system-wide files giving initial commands,
7436               the Resource files.  (The used filenames come from MAILRC and
7437               system-mailrc, respectively.)
7438
7439     ~/mbox    The default value for MBOX.
7440
7441     ~/.mime.types, /etc/mime.types
7442               Personal and system-wide MIME types, see The mime.types files.
7443
7444     ~/.netrc  [v15-compat][Option] The default location of the user's .netrc
7445               file – the section The .netrc file documents the file format.
7446               The used path can be set via NETRC.
7447
7448     /dev/null
7449               The data sink null(4).
7450
7451     ~/.rnd    [Option] Possible location for persistent random entropy seed
7452               storage, see tls-rand-file.
7453
7454   Resource files
7455     Upon startup S-nail reads in several resource files, in order:
7456
7457     s-nail.rc
7458               System wide initialization file (system-mailrc).  Reading of
7459               this file can be suppressed, either by using the -: (and ac‐
7460               cording argument) or -n command line options, or by setting the
7461               ENVIRONMENT variable MAILX_NO_SYSTEM_RC.
7462
7463     ~/.mailrc
7464               File giving initial commands.  A different file can be chosen
7465               by setting the ENVIRONMENT variable MAILRC.  Reading of this
7466               file can be suppressed with the -: command line option.
7467
7468     mailx-extra-rc
7469               Defines a startup file to be read after all other resource
7470               files.  It can be used to specify settings that are not under‐
7471               stood by other mailx(1) implementations, for example.
7472
7473     The content of these files is interpreted as follows:
7474
7475     The whitespace characters space, tabulator and newline, as well as
7476         those defined by the variable ifs, are removed from the beginning and
7477         end of input lines.
7478     Empty lines are ignored.
7479     Any other line is interpreted as a command.  It may be spread over
7480         multiple input lines if the newline character is “escaped” by placing
7481         a reverse solidus character ‘\’ as the last character of the line;
7482         whereas any leading whitespace of follow lines is ignored, trailing
7483         whitespace before a escaped newline remains in the input.
7484     If the line (content) starts with the number sign ‘#’ then it is a
7485         comment-command and also ignored.  (The comment-command is a real
7486         command, which does nothing, and therefore the usual follow lines
7487         mechanism applies!)
7488
7489     Errors while loading these files are subject to the settings of errexit
7490     and posix.  More files with syntactically equal content can be sourceed.
7491     The following, saved in a file, would be an examplary content:
7492
7493            # This line is a comment command.  And y\
7494               es, it is really continued here.
7495           set debug \
7496               verbose
7497               set editheaders
7498
7499   The mime.types files
7500     As stated in HTML mail and MIME attachments S-nail needs to learn about
7501     MIME (Multipurpose Internet Mail Extensions) media types in order to
7502     classify message and attachment content.  One source for them are
7503     mime.types files, the loading of which can be controlled by setting the
7504     variable mimetypes-load-control.  Another is the command mimetype, which
7505     also offers access to S-nails MIME type cache.  mime.types files have the
7506     following syntax:
7507
7508           type/subtype extension [extension ...]
7509           # For example text/html html htm
7510
7511     where ‘type/subtype’ define the MIME media type, as standardized in RFC
7512     2046: ‘type’ is used to declare the general type of data, while the
7513     ‘subtype’ specifies a specific format for that type of data.  One or mul‐
7514     tiple filename ‘extension’s, separated by whitespace, can be bound to the
7515     media type format.  Comments may be introduced anywhere on a line with a
7516     number sign ‘#’, causing the remaining line to be discarded.  S-nail also
7517     supports an extended, non-portable syntax in especially crafted files,
7518     which can be loaded via the alternative value syntax of
7519     mimetypes-load-control, and prepends an optional ‘type-marker’:
7520
7521           [type-marker ]type/subtype extension [extension ...]
7522
7523     The following type markers are supported:
7524
7525     ?         Treat message parts with this content as plain text.
7526     ?t        The same as plain ?.
7527     ?h        Treat message parts with this content as HTML tagsoup.  If the
7528               [Option]al HTML-tagsoup-to-text converter is not available
7529               treat the content as plain text instead.
7530     ?H        Likewise ?h, but instead of falling back to plain text require
7531               an explicit content handler to be defined.
7532     ?q        If no handler can be found a text message is displayed which
7533               says so.  This can be annoying, for example signatures serve a
7534               contextual purpose, their content is of no use by itself.  This
7535               marker will avoid displaying the text message.
7536
7537     Further reading: for sending messages: mimetype,
7538     mime-allow-text-controls, mimetypes-load-control.  For reading etc. mes‐
7539     sages: HTML mail and MIME attachments, The Mailcap files, mimetype,
7540     mime-counter-evidence, mimetypes-load-control, pipe-TYPE/SUBTYPE,
7541     pipe-EXTENSION.
7542
7543   The Mailcap files
7544     [Option] RFC 1524 defines a “User Agent Configuration Mechanism” to be
7545     used to inform mail user agent programs about the locally installed fa‐
7546     cilities for handling various data formats, i.e., about commands and how
7547     they can be used to display, edit et cetera MIME part contents, as well
7548     as a default path search that includes multiple possible locations of re‐
7549     source files, and the MAILCAPS environment variable to overwrite that.
7550     Handlers found from doing the path search will be cached, the command
7551     mailcap operates on that cache, and the variable mailcap-disable will
7552     suppress automatic loading, and usage of any mailcap handlers.  HTML mail
7553     and MIME attachments gives a general overview of how MIME types are han‐
7554     dled.
7555
7556     “Mailcap” files consist of a set of newline separated entries.  Comment
7557     lines start with a number sign ‘#’ (in the first column!) and are ig‐
7558     nored.  Empty lines are ignored.  All other lines are interpreted as
7559     mailcap entries.  An entry definition may be split over multiple lines by
7560     placing the reverse solidus character ‘\’ last in all but the final line.
7561     The standard does not specify how leading whitespace of successive lines
7562     is to be treated, therefore they are retained.
7563
7564     “Mailcap” entries consist of a number of semicolon ‘;’ separated fields.
7565     The first two fields are mandatory and must occur in the specified order,
7566     the remaining fields are optional and may appear in any order.  Leading
7567     and trailing whitespace of field content is ignored (removed).  The re‐
7568     verse solidus ‘\’ character can be used to escape any following character
7569     including semicolon and itself in the content of the second field, and in
7570     value parts of any optional key/value field.
7571
7572     The first field defines the MIME ‘TYPE/SUBTYPE’ the entry is about to
7573     handle (case-insensitively).  If the subtype is specified as an asterisk
7574     ‘*’ the entry is meant to match all subtypes of the named type, e.g.,
7575     ‘audio/*’ would match any audio type.  The second field is the view shell
7576     command used to display MIME parts of the given type.
7577
7578     Data consuming shell commands will be fed message (MIME part) data on
7579     standard input unless one or more instances of the (unquoted) string ‘%s’
7580     are used: these formats will be replaced with a temporary file(name) that
7581     has been prefilled with the parts data.  Data producing shell commands
7582     are expected to generata data on their standard output unless that format
7583     is used.  In all cases any given ‘%s’ format is replaced with a properly
7584     shell quoted filename.  When a command requests a temporary file via ‘%s’
7585     then that will be removed again, as if the x-mailx-tmpfile and
7586     x-mailx-tmpfile-fill flags had been set; unless the command requests
7587     x-mailx-async the x-mailx-tmpfile-unlink flag is also implied; see below
7588     for more.
7589
7590     Optional fields define single-word flags (case-insensitive), or key /
7591     value pairs consisting of a case-insensitive keyword, an equals sign ‘=’,
7592     and a shell command; whitespace surrounding the equals sign is removed.
7593     Optional fields include the following:
7594
7595     compose   A program that can be used to compose a new body or body part
7596               in the given format.  (Currently unused.)
7597
7598     composetyped
7599               Similar to the compose field, but is to be used when the com‐
7600               posing program needs to specify the ‘Content-type:’ header
7601               field to be applied to the composed data.  (Currently unused.)
7602
7603     copiousoutput
7604               A flag field which indicates that the output of the view com‐
7605               mand is integrable into S-nails normal visual display.  It is
7606               mutually exclusive with needsterminal.
7607
7608     description
7609               A textual description that describes this type of data.  The
7610               text may optionally be enclosed within double quotation marks
7611               ‘"’.
7612
7613     edit      A program that can be used to edit a body or body part in the
7614               given format.  (Currently unused.)
7615
7616     nametemplate
7617               This field specifies a filename format for the ‘%s’ format used
7618               in the shell command fields, in which ‘%s’ will be replaced by
7619               a random string.  (The filename is also stored in and passed to
7620               subprocesses via MAILX_FILENAME_TEMPORARY.)  The standard says
7621               this is “only expected to be relevant in environments where
7622               filename extensions are meaningful”, and so this field is ig‐
7623               nored unless the ‘%s’ is a prefix, optionally followed by
7624               (ASCII) alphabetic and numeric characters, the underscore and
7625               the period.  For example, to specify that a JPG file is to be
7626               passed to an image viewer with a name ending in ‘.jpg’,
7627               ‘nametemplate=%s.jpg’ can be used.
7628
7629     needsterminal
7630               This flag field indicates that the given shell command must be
7631               run on an interactive terminal.  S-nail will temporarily re‐
7632               lease the terminal to the given command in interactive mode, in
7633               non-interactive mode this entry will be entirely ignored; this
7634               flag implies x-mailx-noquote.
7635
7636     print     A program that can be used to print a message or body part in
7637               the given format.  (Currently unused.)
7638
7639     test      Specifies a program to be run to test some condition, for exam‐
7640               ple, the machine architecture, or the window system in use, to
7641               determine whether or not this mailcap entry applies.  If the
7642               test fails, a subsequent mailcap entry should be sought; also
7643               see x-mailx-test-once.  Standard I/O of the test program is
7644               redirected from and to /dev/null, and the format ‘%s’ is not
7645               supported (the data does not yet exist).
7646
7647     textualnewlines
7648               A flag field which indicates that this type of data is line-
7649               oriented and that, if encoded in ‘base64’, all newlines should
7650               be converted to canonical form (CRLF) before encoding, and will
7651               be in that form after decoding.  (Currently unused.)
7652
7653     x11-bitmap
7654               Names a file, in X11 bitmap (xbm) format, which points to an
7655               appropriate icon to be used to visually denote the presence of
7656               this kind of data.  This field is not used by S-nail.
7657
7658     x-mailx-async
7659               Extension flag field that denotes that the given view command
7660               shall be executed asynchronously, without blocking S-nail.
7661               Cannot be used in conjunction with needsterminal; the standard
7662               output of the command will go to /dev/null.
7663
7664     x-mailx-noquote
7665               An extension flag field that indicates that even a
7666               copiousoutput view command shall not be used when quoteing mes‐
7667               sages, as it would by default.
7668
7669     x-mailx-test-once
7670               Extension flag which denotes whether the given test command
7671               shall be evaluated once only with its exit status being cached.
7672               This is handy if some global unchanging condition is to be
7673               queried, like “running under the X Window System”.
7674
7675     x-mailx-tmpfile
7676               Extension flag field that requests creation of a zero-sized
7677               temporary file, the name of which is to be placed in the envi‐
7678               ronment variable MAILX_FILENAME_TEMPORARY.  It is an error to
7679               use this flag with commands that include a ‘%s’ format (because
7680               that is implemented by means of this temporary file).
7681
7682     x-mailx-tmpfile-fill
7683               Normally the MIME part content is passed to the handler via
7684               standard input; if this flag is set then the data will instead
7685               be written into the implied x-mailx-tmpfile.  In order to cause
7686               deletion of the temporary file you will have to set
7687               x-mailx-tmpfile-unlink explicitly!  It is an error to use this
7688               flag with commands that include a ‘%s’ format.
7689
7690     x-mailx-tmpfile-unlink
7691               Extension flag field that requests that the temporary file
7692               shall be deleted automatically when the command loop is entered
7693               again at latest.  It is an error to use this flag with commands
7694               that include a ‘%s’ format, or in conjunction with
7695               x-mailx-async.  x-mailx-tmpfile is implied.
7696
7697     x-mailx-last-resort
7698               An extension flag that indicates that this handler shall only
7699               be used as a last resort, when no other source (see HTML mail
7700               and MIME attachments) provides a MIME handler.
7701
7702     x-mailx-ignore
7703               An extension that enforces that this handler is not used at
7704               all.
7705
7706     The standard includes the possibility to define any number of additional
7707     fields, prefixed by ‘x-’.  Flag fields apply to the entire “Mailcap” en‐
7708     try — in some unusual cases, this may not be desirable, but differentia‐
7709     tion can be accomplished via separate entries, taking advantage of the
7710     fact that subsequent entries are searched if an earlier one does not pro‐
7711     vide enough information.  For example, if a view command needs to specify
7712     the needsterminal flag, but the compose command shall not, the following
7713     will help out the latter:
7714
7715           application/postscript; ps-to-terminal %s; needsterminal
7716           application/postscript; ps-to-terminal %s; compose=idraw %s
7717
7718     In value parts of command fields any occurrence of the format string ‘%t’
7719     will be replaced by the ‘TYPE/SUBTYPE’ specification.  Any named parame‐
7720     ter from a messages' ‘Content-type:’ field may be embedded into the com‐
7721     mand line using the format ‘%{’ followed by the parameter name and a
7722     closing brace ‘}’ character.  The entire parameter should appear as a
7723     single command line argument, regardless of embedded spaces, shell quot‐
7724     ing will be performed by the RFC 1524 processor, thus:
7725
7726           # Message
7727           Content-type:  multipart/mixed; boundary=42
7728
7729           # Mailcap file
7730           multipart/*; /usr/local/bin/showmulti \
7731             %t %{boundary}  ;  composetyped  = /usr/local/bin/makemulti
7732
7733           # Executed shell command
7734           /usr/local/bin/showmulti multipart/mixed 42
7735
7736     Note that S-nail does not support handlers for multipart MIME parts as
7737     shown in this example (as of today).  It does not support the additional
7738     formats ‘%n’ and ‘%F’.  An example file, also showing how to properly
7739     deal with the expansion of ‘%s’, which includes any quotes that are nec‐
7740     essary to make it a valid shell argument by itself and thus will cause
7741     undesired behaviour when placed in additional user-provided quotes:
7742
7743           # Comment line
7744           text/richtext; richtext %s; copiousoutput
7745
7746           text/x-perl; perl -cWT %s; nametemplate = %s.pl
7747
7748           # Exit EX_TEMPFAIL=75 on signal
7749           application/pdf; \
7750             infile=%s\; \
7751               trap "rm -f ${infile}" EXIT\; \
7752               trap "exit 75" INT QUIT TERM\; \
7753               mupdf "${infile}"; \
7754             test = [ -n "${DISPLAY}" ]; \
7755             nametemplate = %s.pdf; x-mailx-async
7756           application/pdf; pdftotext -layout - -; copiousoutput
7757
7758           application/*; echo "This is \\"%t\\" but \
7759               is 50 \% Greek to me" \; < %s head -c 512 | cat -vet; \
7760             copiousoutput; x-mailx-noquote; x-mailx-last-resort
7761
7762     Further reading: HTML mail and MIME attachments, The mime.types files,
7763     mimetype, MAILCAPS, mime-counter-evidence, pipe-TYPE/SUBTYPE,
7764     pipe-EXTENSION.
7765
7766   The .netrc file
7767     User credentials for machine accounts (see On URL syntax and credential
7768     lookup) can be placed in the .netrc file, which will be loaded and cached
7769     when requested by netrc-lookup.  The default location ~/.netrc may be
7770     overridden by the NETRC environment variable.  As long as syntax con‐
7771     straints are honoured the file source may be replaced with the output of
7772     the shell command set in netrc-pipe, to load an encrypted file, for exam‐
7773     ple.  The cache can be managed with the command netrc.
7774
7775     The file consists of space, tabulator or newline separated tokens.  This
7776     parser implements a superset of the original BSD syntax, but users should
7777     nonetheless be aware of portability glitches, shall their .netrc be us‐
7778     able across multiple programs and platforms:
7779
7780     BSD only supports double quotation marks, for example ‘password "pass
7781         with spaces"’.
7782     BSD (only?) supports escaping of single characters via a reverse
7783         solidus (a space could be escaped via ‘\ ’), in- as well as outside
7784         of a quoted string.  This method is assumed to be present, and will
7785         actively be used to quote double quotation marks ‘"’ and reverse
7786         solidus ‘\’ characters inside the login and password tokens, for ex‐
7787         ample for display purposes.
7788     BSD does not require a final quotation mark of the last user input
7789         token.
7790     The original BSD (Berknet) parser also supported a format which al‐
7791         lowed tokens to be separated with commas – whereas at least Hewlett-
7792         Packard still seems to support this syntax, this parser does not!
7793     As a non-portable extension some widely-used programs support shell-
7794         style comments: if an input line starts, after any amount of white‐
7795         space, with a number sign ‘#’, then the rest of the line is ignored.
7796     Whereas other programs may require that the .netrc file is accessible
7797         by only the user if it contains a password token for any other login
7798         than “anonymous”, this parser will always require these strict per‐
7799         missions.
7800
7801     Of the following list of supported tokens this parser uses (and caches)
7802     machine, login and password.  An existing default entry will not be used.
7803
7804     machine name
7805               The hostname of the entries' machine, lowercase-normalized be‐
7806               fore use.  Any further file content, until either end-of-file
7807               or the occurrence of another machine or a default first-class
7808               token is bound (only related) to the machine name.
7809
7810               As an extension that should not be the cause of any worries
7811               this parser supports a single wildcard prefix for name:
7812
7813                     machine *.example.com login USER password PASS
7814                     machine pop3.example.com login USER password PASS
7815                     machine smtp.example.com login USER password PASS
7816
7817               which would match ‘xy.example.com’ as well as
7818               ‘pop3.example.com’, but neither ‘example.com’ nor
7819               ‘local.smtp.example.com’.  In the example neither
7820               ‘pop3.example.com’ nor ‘smtp.example.com’ will be matched by
7821               the wildcard, since the exact matches take precedence (it is
7822               however faster to specify it the other way around).
7823
7824     default   This is the same as machine except that it is a fallback entry
7825               that is used shall none of the specified machines match; only
7826               one default token may be specified, and it must be the last
7827               first-class token.
7828
7829     login name
7830               The user name on the remote machine.
7831
7832     password string
7833               The user's password on the remote machine.
7834
7835     account string
7836               Supply an additional account password.  This is merely for FTP
7837               purposes.
7838
7839     macdef name
7840               Define a macro.  A macro is defined with the specified name; it
7841               is formed from all lines beginning with the next line and con‐
7842               tinuing until a blank line is (consecutive newline characters
7843               are) encountered.  (Note that macdef entries cannot be utilized
7844               by multiple machines, too, but must be defined following the
7845               machine they are intended to be used with.)  If a macro named
7846               init exists, it is automatically run as the last step of the
7847               login process.  This is merely for FTP purposes.
7848

EXAMPLES

7850   An example configuration
7851           # This example assumes v15.0 compatibility mode
7852           set v15-compat
7853
7854           # Request strict TLL transport layer security checks
7855           set tls-verify=strict
7856
7857           # Where are the up-to-date TLS certificates?
7858           # (Since we manage up-to-date ones explicitly, do not use any,
7859           # possibly outdated, default certificates shipped with OpenSSL)
7860           #set tls-ca-dir=/etc/ssl/certs
7861           set tls-ca-file=/etc/ssl/certs/ca-certificates.crt
7862           set tls-ca-no-defaults
7863           #set tls-ca-flags=partial-chain
7864           wysh set smime-ca-file="${tls-ca-file}" \
7865             smime-ca-no-defaults #smime-ca-flags="${tls-ca-flags}"
7866
7867           # This could be outsourced to a central configuration file via
7868           # tls-config-file plus tls-config-module if the used library allows.
7869           # CipherString: explicitly define the list of ciphers, which may
7870           #   improve security, especially with protocols older than TLS v1.2.
7871           #   See ciphers(1).  Possibly best to only use tls-config-pairs-HOST
7872           #   (or -USER@HOST), as necessary, again..
7873           #   Note that TLSv1.3 uses Ciphersuites= instead, which will join
7874           #   with CipherString (if protocols older than v1.3 are allowed)
7875           # Curves: especially with TLSv1.3 curves selection may be desired.
7876           # MinProtocol,MaxProtocol: do not use protocols older than TLS v1.2.
7877           #   Change this only when the remote server does not support it:
7878           #   maybe use chain support via tls-config-pairs-HOST / -USER@HOST
7879           #   to define such explicit exceptions, then, e.g.,
7880           #     MinProtocol=TLSv1.1
7881           if "$tls-features" =% ,+ctx-set-maxmin-proto,
7882             wysh set tls-config-pairs='\
7883                 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7884                 Curves=P-521:P-384:P-256,\
7885                 MinProtocol=TLSv1.1'
7886           else
7887             wysh set tls-config-pairs='\
7888                 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7889                 Curves=P-521:P-384:P-256,\
7890                 Protocol=-ALL\,+TLSv1.1 \, +TLSv1.2\, +TLSv1.3'
7891           endif
7892
7893           # Essential setting: select allowed character sets
7894           set sendcharsets=utf-8,iso-8859-1
7895
7896           # A very kind option: when replying to a message, first try to
7897           # use the same encoding that the original poster used herself!
7898           set reply-in-same-charset
7899
7900           # When replying, do not merge From: and To: of the original message
7901           # into To:.  Instead old From: -> new To:, old To: -> merge Cc:.
7902           set recipients-in-cc
7903
7904           # When sending messages, wait until the Mail-Transfer-Agent finishs.
7905           # Only like this you will be able to see errors reported through the
7906           # exit status of the MTA (including the built-in SMTP one)!
7907           set sendwait
7908
7909           # Only use built-in MIME types, no mime.types(5) files
7910           set mimetypes-load-control
7911
7912           # Default directory where we act in (relative to $HOME)
7913           set folder=mail
7914           # A leading "+" (often) means: under *folder*
7915           # *record* is used to save copies of sent messages
7916           set MBOX=+mbox.mbox DEAD=+dead.txt \
7917             record=+sent.mbox record-files record-resent
7918
7919           # Make "file mymbox" and "file myrec" go to..
7920           shortcut mymbox %:+mbox.mbox myrec +sent.mbox
7921
7922           # Not really optional, e.g., for S/MIME
7923           set from='Your Name <address@exam.ple>'
7924
7925           # It may be necessary to set hostname and/or smtp-hostname
7926           # if the "SERVER" of mta and "domain" of from do not match.
7927           # The `urlencode' command can be used to encode USER and PASS
7928           set mta=(smtps?|submissions?)://[USER[:PASS]@]SERVER[:PORT] \
7929             smtp-auth=login/plain... \
7930             smtp-use-starttls
7931
7932           # Never refuse to start into interactive mode, and more
7933           set emptystart \
7934             colour-pager crt= \
7935             followup-to followup-to-honour=ask-yes fullnames \
7936             history-file=+.s-nailhist history-size=-1 history-gabby \
7937             mime-counter-evidence=0b1111 \
7938             prompt='?\$?!\$!/\$^ERRNAME[\$account#\$mailbox-display]? ' \
7939             reply-to-honour=ask-yes \
7940             umask=
7941
7942           # Only include the selected header fields when typing messages
7943           headerpick type retain from_ date from to cc subject \
7944             message-id mail-followup-to reply-to
7945           # ...when forwarding messages
7946           headerpick forward retain subject date from to cc
7947           # ...when saving message, etc.
7948           #headerpick save ignore ^Original-.*$ ^X-.*$
7949
7950           # Some mailing lists
7951           mlist '@xyz-editor\.xyz$' '@xyzf\.xyz$'
7952           mlsubscribe '^xfans@xfans\.xyz$'
7953
7954           # Handle a few file extensions (to store MBOX databases)
7955           filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
7956             gz 'gzip -dc' 'gzip -c'  xz 'xz -dc' 'xz -zc' \
7957             zst 'zstd -dc' 'zstd -19 -zc' \
7958             zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
7959
7960           # A real life example of a very huge free mail provider
7961           # Instead of directly placing content inside `account',
7962           # we `define' a macro: like that we can switch "accounts"
7963           # from within *on-compose-splice*, for example!
7964           define XooglX {
7965             set folder=~/spool/XooglX inbox=+syste.mbox sent=+sent
7966             set from='Your Name <address@examp.ple>'
7967
7968             set pop3-no-apop-pop.gmXil.com
7969             shortcut pop %:pop3s://pop.gmXil.com
7970             shortcut imap %:imaps://imap.gmXil.com
7971             # Or, entirely IMAP based setup
7972             #set folder=imaps://imap.gmail.com record="+[Gmail]/Sent Mail" \
7973             #   imap-cache=~/spool/cache
7974
7975             set mta=smtp://USER:PASS@smtp.gmXil.com smtp-use-starttls
7976             # Alternatively:
7977             set mta=smtps://USER:PASS@smtp.gmail.com:465
7978           }
7979           account XooglX {
7980             \call XooglX
7981           }
7982
7983           # Here is a pretty large one which does not allow sending mails
7984           # if there is a domain name mismatch on the SMTP protocol level,
7985           # which would bite us if the value of from does not match, e.g.,
7986           # for people who have a sXXXXeforge project and want to speak
7987           # with the mailing list under their project account (in from),
7988           # still sending the message through their normal mail provider
7989           define XandeX {
7990             set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
7991             set from='Your Name <address@exam.ple>'
7992
7993             shortcut pop %:pop3s://pop.yaXXex.com
7994             shortcut imap %:imaps://imap.yaXXex.com
7995
7996             set mta=smtps://USER:PASS@smtp.yaXXex.com:465 \
7997               hostname=yaXXex.com smtp-hostname=
7998           }
7999           account XandeX {
8000             \call Xandex
8001           }
8002
8003           # Create some new commands so that, e.g., `ls /tmp' will..
8004           commandalias lls '!ls ${LS_COLOUR_FLAG} -aFlrS'
8005           commandalias llS '!ls ${LS_COLOUR_FLAG} -aFlS'
8006
8007           set pipe-message/external-body='?* echo $MAILX_EXTERNAL_BODY_URL'
8008
8009           # We do not support gpg(1) directly yet.  But simple --clearsign'd
8010           # message parts can be dealt with as follows:
8011           define V {
8012             localopts yes
8013             wysh set pipe-text/plain=$'?*#++=?\
8014               < "${MAILX_FILENAME_TEMPORARY}" awk \
8015                   -v TMPFILE="${MAILX_FILENAME_TEMPORARY}" \'\
8016                 BEGIN{done=0}\
8017                 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\
8018                   if(done++ != 0)\
8019                     next;\
8020                   print "--- GPG --verify ---";\
8021                   system("gpg --verify " TMPFILE " 2>&1");\
8022                   print "--- GPG --verify ---";\
8023                   print "";\
8024                   next;\
8025                 }\
8026                 /^-----BEGIN PGP SIGNATURE-----/,\
8027                     /^-----END PGP SIGNATURE-----/{\
8028                   next;\
8029                 }\
8030                 {print}\
8031               \''
8032               print
8033           }
8034           commandalias V '\'call V
8035
8036     When storing passwords in ~/.mailrc appropriate permissions should be set
8037     on this file with ‘$ chmod 0600 ~/.mailrc’.  If the [Option]al
8038     netrc-lookup is available user credentials can be stored in the central
8039     ~/.netrc file instead; e.g., here is a different version of the example
8040     account that sets up SMTP and POP3:
8041
8042           define XandeX {
8043             set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
8044             set from='Your Name <address@exam.ple>'
8045             set netrc-lookup
8046             # Load an encrypted ~/.netrc by uncommenting the next line
8047             #set netrc-pipe='gpg -qd ~/.netrc.pgp'
8048
8049             set mta=smtps://smtp.yXXXXx.ru:465 \
8050                 smtp-hostname= hostname=yXXXXx.com
8051             set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
8052             commandalias xp fi pop3s://pop.yXXXXx.ru
8053           }
8054           account XandeX {
8055             \call XandeX
8056           }
8057
8058     and, in the ~/.netrc file:
8059
8060           machine *.yXXXXx.ru login USER password PASS
8061
8062     This configuration should now work just fine:
8063
8064           $ echo text | s-nail -dvv -AXandeX -s Subject user@exam.ple
8065
8066   S/MIME step by step
8067     [Option] The first thing that is needed for Signed and encrypted messages
8068     with S/MIME is a personal certificate, and a private key.  The certifi‐
8069     cate contains public information, in particular a name and email ad‐
8070     dress(es), and the public key that can be used by others to encrypt mes‐
8071     sages for the certificate holder (the owner of the private key), and to
8072     verify signed messages generated with that certificate('s private key).
8073     Whereas the certificate is included in each signed message, the private
8074     key must be kept secret.  It is used to decrypt messages that were previ‐
8075     ously encrypted with the public key, and to sign messages.
8076
8077     For personal use it is recommended to get a S/MIME certificate from one
8078     of the major CAs on the Internet.  Many CAs offer such certificates for
8079     free.  Usually offered is a combined certificate and private key in
8080     PKCS#12 format which S-nail does not accept directly.  To convert it to
8081     PEM format, the following shell command can be used; please read on for
8082     how to use these PEM files.
8083
8084           $ openssl pkcs12 -in cert.p12 -out certpem.pem -clcerts -nodes
8085           $ # Alternatively
8086           $ openssl pkcs12 -in cert.p12 -out cert.pem -clcerts -nokeys
8087           $ openssl pkcs12 -in cert.p12 -out key.pem -nocerts -nodes
8088
8089     There is also https://www.CAcert.org which issues client and server cer‐
8090     tificates to members of their community for free; their root certificate
8091     (https://www.cacert.org/certs/root.crt) is often not in the default set
8092     of trusted CA root certificates, though, which means their root certifi‐
8093     cate has to be downloaded separately, and needs to be part of the S/MIME
8094     certificate validation chain by including it in smime-ca-dir or as a
8095     vivid member of the smime-ca-file.  But let us take a step-by-step tour
8096     on how to setup S/MIME with a certificate from CAcert.org despite this
8097     situation!
8098
8099     First of all you will have to become a member of the CAcert.org commu‐
8100     nity, simply by registrating yourself via the web interface.  Once you
8101     are, create and verify all email addresses you want to be able to create
8102     signed and encrypted messages for/with using the corresponding entries of
8103     the web interface.  Now ready to create S/MIME certificates, so let us
8104     create a new “client certificate”, ensure to include all email addresses
8105     that should be covered by the certificate in the following web form, and
8106     also to use your name as the “common name”.
8107
8108     Create a private key and a certificate request on your local computer
8109     (please see the manual pages of the used commands for more in-depth
8110     knowledge on what the used arguments etc. do):
8111
8112           $ openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
8113
8114     Afterwards copy-and-paste the content of “creq.pem” into the certificate-
8115     request (CSR) field of the web form on the CAcert.org website (you may
8116     need to unfold some “advanced options” to see the corresponding text
8117     field).  This last step will ensure that your private key (which never
8118     left your box) and the certificate belong together (through the public
8119     key that will find its way into the certificate via the certificate-re‐
8120     quest).  You are now ready and can create your CAcert certified certifi‐
8121     cate.  Download and store or copy-and-paste it as “pub.crt”.
8122
8123     Yay.  In order to use your new S/MIME setup a combined private key/public
8124     key (certificate) file has to be created:
8125
8126           $ cat key.pem pub.crt > ME@HERE.com.paired
8127
8128     This is the file S-nail will work with.  If you have created your private
8129     key with a passphrase then S-nail will ask you for it whenever a message
8130     is signed or decrypted, unless this operation has been automated as de‐
8131     scribed in Signed and encrypted messages with S/MIME.  Set the following
8132     variables to henceforth use S/MIME (setting smime-ca-file is of interest
8133     for verification only):
8134
8135           ? set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \
8136               smime-sign-cert=ME@HERE.com.paired \
8137               smime-sign-digest=SHA512 \
8138               smime-sign from=myname@my.host
8139
8140   Using CRLs with S/MIME or TLS
8141     [Option] Certification authorities (CAs) issue certificate revocation
8142     lists (CRLs) on a regular basis.  These lists contain the serial numbers
8143     of certificates that have been declared invalid after they have been is‐
8144     sued.  Such usually happens because the private key for the certificate
8145     has been compromised, because the owner of the certificate has left the
8146     organization that is mentioned in the certificate, etc.  To seriously use
8147     S/MIME or TLS verification, an up-to-date CRL is required for each
8148     trusted CA.  There is otherwise no method to distinguish between valid
8149     and invalidated certificates.  S-nail currently offers no mechanism to
8150     fetch CRLs, nor to access them on the Internet, so they have to be re‐
8151     trieved by some external mechanism.
8152
8153     S-nail accepts CRLs in PEM format only; CRLs in DER format must be con‐
8154     verted, like, e.g.:
8155
8156           $ openssl crl -inform DER -in crl.der -out crl.pem
8157
8158     To tell S-nail about the CRLs, a directory that contains all CRL files
8159     (and no other files) must be created.  The smime-crl-dir or tls-crl-dir
8160     variables, respectively, must then be set to point to that directory.
8161     After that, S-nail requires a CRL to be present for each CA that is used
8162     to verify a certificate.
8163

FAQ

8165     In general it is a good idea to turn on debug (-d) and / or verbose (-v,
8166     twice) if something does not work well.  Very often a diagnostic message
8167     can be produced that leads to the problems' solution.
8168
8169   S-nail shortly hangs on startup
8170     This can have two reasons, one is the necessity to wait for a file lock
8171     and cannot be helped, the other being that S-nail calls the function
8172     uname(2) in order to query the nodename of the box (sometimes the real
8173     one is needed instead of the one represented by the internal variable
8174     hostname).  One may have varying success by ensuring that the real host‐
8175     name and ‘localhost’ have entries in /etc/hosts, or, more generally, that
8176     the name service is properly setup – and does hostname(1) return the ex‐
8177     pected value?  Does this local hostname have a domain suffix?  RFC 6762
8178     standardized the link-local top-level domain ‘.local’, try again after
8179     adding an (additional) entry with this extension.
8180
8181   I cannot login to Google mail (via OAuth)
8182     Since 2014 some free service providers classify programs as “less secure”
8183     unless they use a special authentication method (OAuth 2.0) which was not
8184     standardized for non-HTTP protocol authentication token query until Au‐
8185     gust 2015 (RFC 7628).
8186
8187     Different to Kerberos / GSSAPI, which is developed since the mid of the
8188     1980s, where a user can easily create a local authentication ticket for
8189     her- and himself with the locally installed kinit(1) program, that proto‐
8190     col has no such local part but instead requires a world-wide-web query to
8191     create or fetch a token; since there is no local cache this query would
8192     have to be performed whenever S-nail is invoked (in interactive sessions
8193     situation may differ).
8194
8195     S-nail does not directly support OAuth.  It, however, supports XOAUTH2 /
8196     OAUTHBEARER, see But, how about XOAUTH2 / OAUTHBEARER? If that is not
8197     used it is necessary to declare S-nail a “less secure app” (on the
8198     providers account web page) in order to read and send mail.  However, it
8199     also seems possible to take the following steps instead:
8200
8201     1.   give the provider the number of a mobile phone,
8202     2.   enable “2-Step Verification”,
8203     3.   create an application specific password (16 characters), and
8204     4.   use that special password instead of the real Google account pass‐
8205          word in S-nail (for more on that see the section On URL syntax and
8206          credential lookup).
8207
8208   But, how about XOAUTH2 / OAUTHBEARER?
8209     Following up I cannot login to Google mail (via OAuth) one OAuth-based
8210     authentication method is available: the OAuth 2.0 bearer token usage as
8211     standardized in RFC 6750 (according SASL mechanism in RFC 7628), also
8212     known as XOAUTH2 and OAUTHBEARER, allows fetching a temporary access to‐
8213     ken via the web that can locally be used as a password.  The protocol is
8214     simple and extendable, token updates or even password changes via a sim‐
8215     ple TLS secured server login would be possible in theory, but today a web
8216     browser and an external support tool are prerequisites for using this au‐
8217     thentication method.  The token times out and must be periodically re‐
8218     freshed via the web.
8219
8220     Some hurdles must be taken before being able to use this method.  Using
8221     GMail as an example, an application (that is a name) must be registered,
8222     for which credentials, a “client ID” and a “client secret”, need to be
8223     created and saved locally (in a secure way).  These initial configuration
8224     steps can be performed at
8225     https://console.developers.google.com/apis/credentials Thereafter a re‐
8226     fresh token can be requested; a python program to do this for GMail ac‐
8227     counts is https://github.com/google/gmail-oauth2-tools/raw/master/python/
8228     oauth2.py:
8229
8230           $ python oauth2.py --user=EMAIL \
8231             --client-id=THE-ID --client-secret=THE-SECRET \
8232             --generate_oauth2_token
8233           To authorize token, visit this url and follow the directions:
8234             https://accounts.google.com/o/oauth2/auth?client_id=...
8235             Enter verification code: ...
8236             Refresh Token: ...
8237             Access Token: ...
8238             Access Token Expiration Seconds: 3600
8239           $ # Of which the last three are actual token responses.
8240           $ # Thereafter access tokens can regularly be refreshed
8241           $ # via the created refresh token (read on)
8242
8243     The generated refresh token must also be saved locally (securely).  The
8244     procedure as a whole can be read at https://github.com/google/gmail-
8245     oauth2-tools/wiki/OAuth2DotPyRunThrough Since periodic timers are not yet
8246     supported, keeping an access token up-to-date (from within S-nail) can
8247     only be performed via the hook on-main-loop-tick, or (for sending only)
8248     on-compose-enter (for more on authentication please see the section On
8249     URL syntax and credential lookup):
8250
8251           set on-main-loop-tick=o-m-l-t on-compose-enter=o-c-e
8252           define o-m-l-t {
8253             xcall update_access_token
8254           }
8255           define o-c-e {
8256             xcall update_access_token
8257           }
8258
8259           set access_token_=0
8260           define update_access_token {
8261             local set i epoch_sec epoch_nsec
8262             vput vexpr i epoch
8263             eval set $i # set epoch_sec/_nsec of vexpr epoch
8264             vput vexpr i + $access_token_ 2100
8265             if $epoch_sec -ge $i
8266               vput ! password python oauth2.py --user=EMAIL \
8267                   --client-id=THE-ID --client-secret=THE-SECRET \
8268                   --refresh-token=THE-REFRESH-TOKEN |\
8269                 sed '1b PASS;d; :PASS s/^.\{1,\}:\(.\{1,\}\)$/\1/'
8270               vput csop password trim "$password"
8271               if -n "$verbose"
8272                 echo password is <$password>
8273               endif
8274               set access_token_=$epoch_sec
8275             endif
8276           }
8277
8278   Not "defunctional", but the editor key does not work
8279     Two thinkable situations: the first is a shadowed sequence; setting
8280     debug, or the most possible verbose mode, causes a printout of the bind
8281     tree after that is built; being a cache, this happens only upon startup
8282     or after modifying bindings.
8283
8284     Or second, terminal libraries (see On terminal control and line editor,
8285     bind, termcap) may report different codes than the terminal really sends,
8286     rendering bindings dysfunctional because expected and received data do
8287     not match; the verbose listing of bindings will show the byte sequences
8288     that are expected.  (One common source of problems is that the — possibly
8289     even non-existing — keypad is not turned on, and the resulting layout re‐
8290     ports the keypad control codes for the normal keyboard keys.)
8291
8292     To overcome the situation use for example the program cat(1) with its op‐
8293     tion -v, if available, to see the byte sequences which are actually pro‐
8294     duced by keypresses, and use the variable termcap to make S-nail aware of
8295     them.  The terminal this is typed on produces some unexpected sequences,
8296     here for an example the shifted home key:
8297
8298           ? set verbose
8299           ? bind*
8300           # 1B 5B=[ 31=1 3B=; 32=2 48=H
8301             bind base :kHOM z0
8302           ? x
8303           $ cat -v
8304           ^[[H
8305           $ s-nail -v -Stermcap='kHOM=\E[H'
8306           ? bind*
8307           # 1B 5B=[ 48=H
8308             bind base :kHOM z0
8309
8310   Can S-nail git-send-email?
8311     Yes.  Put (at least parts of) the following in your ~/.gitconfig:
8312
8313           [sendemail]
8314           smtpserver = /usr/bin/s-nail
8315           smtpserveroption = -t
8316           #smtpserveroption = -Sexpandaddr
8317           smtpserveroption = -Athe-account-you-need
8318           ##
8319           suppresscc = all
8320           suppressfrom = false
8321           assume8bitEncoding = UTF-8
8322           #to = /tmp/OUT
8323           confirm = always
8324           chainreplyto = true
8325           multiedit = false
8326           thread = true
8327           quiet = true
8328           annotate = true
8329
8330     Newer git(1) versions (v2.33.0) added the option sendmailCmd.  Patches
8331     can also be send directly, for example:
8332
8333           $ git format-patch -M --stdout HEAD^ |
8334             s-nail -A the-account-you-need -t RECEIVER
8335
8336   Howto handle stale dotlock files
8337     folder sometimes fails to open MBOX mail databases because creation of
8338     dotlock files is impossible due to existing but unowned lock files.
8339     S-nail does not offer an option to deal with those files, because it is
8340     considered a site policy what counts as unowned, and what not.  The site
8341     policy is usually defined by administrator(s), and expressed in the con‐
8342     figuration of a locally installed MTA (for example Postfix
8343     ‘stale_lock_time=500s’).  Therefore the suggestion:
8344
8345           $ </dev/null s-nail -s 'MTA: be no frog, handle lock' $LOGNAME
8346
8347     By sending a mail to yourself the local MTA can use its normal queue
8348     mechanism to try the delivery multiple times, finally decide a lock file
8349     has become stale, and remove it.
8350

IMAP CLIENT

8352     [Option]ally there is IMAP client support available.  This part of the
8353     program is obsolete and will vanish in v15 with the large MIME and I/O
8354     layer rewrite, because it uses old-style blocking I/O and makes excessive
8355     use of signal based long code jumps.  Support can hopefully be readded
8356     later based on a new-style I/O, with SysV signal handling.  In fact the
8357     IMAP support had already been removed from the codebase, but was rein‐
8358     stantiated on user demand: in effect the IMAP code is at the level of
8359     S-nail v14.8.16 (with imapcodec being the sole exception), and should be
8360     treated with some care.
8361
8362     IMAP uses the ‘imap://’ and ‘imaps://’ protocol prefixes, and an IMAP-
8363     based folder may be used.  IMAP URLs (paths) undergo inspections and pos‐
8364     sible transformations before use (and the command imapcodec can be used
8365     to manually apply them to any given argument).  Hierarchy delimiters are
8366     normalized, a step which is configurable via the imap-delim variable
8367     chain, but defaults to the first seen delimiter otherwise.  S-nail sup‐
8368     ports internationalised IMAP names, and en- and decodes the names from
8369     and to the ttycharset as necessary and possible.  If a mailbox name is
8370     expanded (see Filename transformations) to an IMAP mailbox, all names
8371     that begin with `+' then refer to IMAP mailboxes below the folder target
8372     box, while folder names prefixed by `@' refer to folders below the hier‐
8373     archy base, so the following will list all folders below the current one
8374     when in an IMAP mailbox: ‘folders @’.
8375
8376     Note: some IMAP servers do not accept the creation of mailboxes in the
8377     hierarchy base, but require that they are created as subfolders of `IN‐
8378     BOX' – with such servers a folder name of the form
8379
8380           imaps://mylogin@imap.myisp.example/INBOX.
8381
8382     should be used (the last character is the server's hierarchy delimiter).
8383     The following IMAP-specific commands exist:
8384
8385     cache     Only applicable to cached IMAP mailboxes; takes a message list
8386               and reads the specified messages into the IMAP cache.
8387
8388     connect   If operating in disconnected mode on an IMAP mailbox, switch to
8389               online mode and connect to the mail server while retaining the
8390               mailbox status.  See the description of the disconnected vari‐
8391               able for more information.
8392
8393     disconnect
8394               If operating in online mode on an IMAP mailbox, switch to dis‐
8395               connected mode while retaining the mailbox status.  See the de‐
8396               scription of the disconnected variable for more.  A list of
8397               messages may optionally be given as argument; the respective
8398               messages are then read into the cache before the connection is
8399               closed, thus ‘disco *’ makes the entire mailbox available for
8400               disconnected use.
8401
8402     imap      Sends command strings directly to the current IMAP server.
8403               S-nail operates always in IMAP `selected state' on the current
8404               mailbox; commands that change this will produce undesirable re‐
8405               sults and should be avoided.  Useful IMAP commands are:
8406
8407                     create         Takes the name of an IMAP mailbox as an
8408                                    argument and creates it.
8409
8410                     getquotaroot   (RFC 2087) Takes the name of an IMAP mail‐
8411                                    box as an argument and prints the quotas
8412                                    that apply to the mailbox.  Not all IMAP
8413                                    servers support this command.
8414
8415                     namespace      (RFC 2342) Takes no arguments and prints
8416                                    the Personal Namespaces, the Other User's
8417                                    Namespaces and the Shared Namespaces.
8418                                    Each namespace type is printed in paren‐
8419                                    theses; if there are multiple namespaces
8420                                    of the same type, inner parentheses sepa‐
8421                                    rate them.  For each namespace a prefix
8422                                    and a hierarchy separator is listed.  Not
8423                                    all IMAP servers support this command.
8424
8425     imapcodec
8426               Perform IMAP path transformations.  Supports vput (see Command
8427               modifiers), and manages the error number !.  The first argument
8428               specifies the operation: e[ncode] normalizes hierarchy delim‐
8429               iters (see imap-delim) and converts the strings from the locale
8430               ttycharset to the internationalized variant used by IMAP,
8431               d[ecode] performs the reverse operation.  Encoding will honour
8432               the (global) value of imap-delim.
8433
8434     The following IMAP-specific internal variables exist:
8435
8436     disconnected
8437               (Boolean) When an IMAP mailbox is selected and this variable is
8438               set, no connection to the server is initiated.  Instead, data
8439               is obtained from the local cache (see imap-cache).  Mailboxes
8440               that are not present in the cache and messages that have not
8441               yet entirely been fetched from the server are not available; to
8442               fetch all messages in a mailbox at once, the command `copy *
8443               /dev/null' can be used while still in connected mode.  Changes
8444               that are made to IMAP mailboxes in disconnected mode are queued
8445               and committed later when a connection to that server is made.
8446               This procedure is not completely reliable since it cannot be
8447               guaranteed that the IMAP unique identifiers (UIDs) on the
8448               server still match the ones in the cache at that time.  Data is
8449               saved to DEAD when this problem occurs.
8450
8451     disconnected-USER@HOST
8452               The specified account is handled as described for the
8453               disconnected variable above, but other accounts are not af‐
8454               fected.
8455
8456     imap-auth-USER@HOST, imap-auth
8457               Sets the IMAP authentication method.  Supported are the default
8458               ‘login’, [v15-compat] ‘oauthbearer’ (see FAQ entry But, how
8459               about XOAUTH2 / OAUTHBEARER?), [v15-compat] ‘external’ and
8460               ‘externanon’ (for TLS secured connections which pass a client
8461               certificate via tls-config-pairs), as well as the [Option]al
8462               ‘cram-md5’ and ‘gssapi’.  All methods need a user and a
8463               password except ‘gssapi’ and ‘external’, which only need the
8464               former.  ‘externanon’ solely builds upon the credentials passed
8465               via a client certificate, and is usually the way to go since
8466               tested servers do not actually follow RFC 4422, and fail if ad‐
8467               ditional credentials are actually passed.
8468
8469     imap-cache
8470               Enables caching of IMAP mailboxes.  The value of this variable
8471               must point to a directory that is either existent or can be
8472               created by S-nail.  All contents of the cache can be deleted by
8473               S-nail at any time; it is not safe to make assumptions about
8474               them.
8475
8476     imap-delim-USER@HOST, imap-delim-HOST, imap-delim
8477               The hierarchy separator used by the IMAP server.  Whenever an
8478               IMAP path is specified it will undergo normalization.  One of
8479               the normalization steps is the squeezing and adjustment of hi‐
8480               erarchy separators.  If this variable is set, any occurrence of
8481               any character of the given value that exists in the path will
8482               be replaced by the first member of the value; an empty value
8483               will cause the default to be used, it is ‘/.’.  If not set, we
8484               will reuse the first hierarchy separator character that is dis‐
8485               covered in a user-given mailbox name.
8486
8487     imap-keepalive-USER@HOST, imap-keepalive-HOST, imap-keepalive
8488               IMAP servers may close the connection after a period of inac‐
8489               tivity; the standard requires this to be at least 30 minutes,
8490               but practical experience may vary.  Setting this variable to a
8491               numeric `value' greater than 0 causes a `NOOP' command to be
8492               sent each `value' seconds if no other operation is performed.
8493
8494     imap-list-depth
8495               When retrieving the list of folders on an IMAP server, the
8496               folders command stops after it has reached a certain depth to
8497               avoid possible infinite loops.  The value of this variable sets
8498               the maximum depth allowed.  The default is 2.  If the folder
8499               separator on the current IMAP server is a slash `/', this vari‐
8500               able has no effect and the folders command does not descend to
8501               subfolders.
8502
8503     imap-use-starttls-USER@HOST, imap-use-starttls-HOST, imap-use-starttls
8504               Causes S-nail to issue a `STARTTLS' command to make an unen‐
8505               crypted IMAP session TLS encrypted.  This functionality is not
8506               supported by all servers, and is not used if the session is al‐
8507               ready encrypted by the IMAPS method.
8508

SEE ALSO

8510     bogofilter(1), gpg(1), more(1), newaliases(1), openssl(1), sendmail(1),
8511     sh(1), spamassassin(1), iconv(3), setlocale(3), aliases(5), termcap(5),
8512     terminfo(5), locale(7), mailaddr(7), re_format(7) (or regex(7)),
8513     mailwrapper(8), sendmail(8)
8514

HISTORY

8516     M. Douglas McIlroy writes in his article “A Research UNIX Reader:
8517     Annotated Excerpts from the Programmer's Manual, 1971-1986” that a
8518     mail(1) command already appeared in First Edition UNIX in 1971:
8519
8520           Electronic mail was there from the start.  Never satisfied with its
8521           exact behavior, everybody touched it at one time or another: to as‐
8522           sure the safety of simultaneous access, to improve privacy, to sur‐
8523           vive crashes, to exploit uucp, to screen out foreign freeloaders,
8524           or whatever.  Not until v7 did the interface change (Thompson).
8525           Later, as mail became global in its reach, Dave Presotto took
8526           charge and brought order to communications with a grab-bag of ex‐
8527           ternal networks (v8).
8528
8529     BSD Mail, in large parts compatible with UNIX mail, was written in 1978
8530     by Kurt Shoens and developed as part of the BSD UNIX distribution until
8531     1995.  This manual page is derived from “The Mail Reference Manual” that
8532     Kurt Shoens wrote for Mail 1.3, included in 3BSD in 1980.  The common
8533     UNIX and BSD denominator became standardized as mailx(1) in the X/Open
8534     Portability Guide Issue 2 (January 1987).  After the rise of Open Source
8535     BSD variants Mail saw continuous development in the individual code
8536     forks, noticeably by Christos Zoulas in NetBSD.  Based upon this Nail,
8537     later Heirloom Mailx, was developed by Gunnar Ritter in the years 2000
8538     until 2008.  Since 2012 S-nail is maintained by Steffen Nurpmeso.
8539
8540     Electronic mail exchange in general is a concept even older.  The earli‐
8541     est well documented electronic mail system was part of the Compatible
8542     Time Sharing System (CTSS) at MIT, its MAIL command had been proposed in
8543     a staff planning memo at the end of 1964 and was implemented in mid-1965
8544     when Tom Van Vleck and Noel Morris wrote the necessary code.  Similar
8545     communication programs were built for other timesharing systems.  One of
8546     the most ambitious and influential was Murray Turoff's EMISARI.  Created
8547     in 1971 for the United States Office of Emergency Preparedness, EMISARI
8548     combined private electronic messages with a chat system, public postings,
8549     voting, and a user directory.
8550
8551     During the 1960s it was common to connect a large number of terminals to
8552     a single, central computer.  Connecting two computers together was rela‐
8553     tively unusual.  This began to change with the development of the
8554     ARPANET, the ancestor of today's Internet.  In 1971 Ray Tomlinson adapted
8555     the SNDMSG program, originally developed for the University of California
8556     at Berkeley timesharing system, to give it the ability to transmit a mes‐
8557     sage across the network into the mailbox of a user on a different com‐
8558     puter.  For the first time it was necessary to specify the recipient's
8559     computer as well as an account name.  Tomlinson decided that the under‐
8560     used commercial at ‘@’ would work to separate the two.
8561
8562     Sending a message across the network was originally treated as a special
8563     instance of transmitting a file, and so a MAIL command was included in
8564     RFC 385 on file transfer in 1972.  Because it was not always clear when
8565     or where a message had come from, RFC 561 in 1973 aimed to formalize
8566     electronic mail headers, including “from”, “date”, and “subject”.  In
8567     1975 RFC 680 described fields to help with the transmission of messages
8568     to multiple users, including “to”, “cc”, and “bcc”.  In 1977 these fea‐
8569     tures and others went from best practices to a binding standard in RFC
8570     733.  Queen Elizabeth II of England became the first head of state to
8571     send electronic mail on March 26 1976 while ceremonially opening a build‐
8572     ing in the British Royal Signals and Radar Establishment (RSRE) in
8573     Malvern.
8574

AUTHORS

8576     Kurt Shoens, Edward Wang, Keith Bostic, Christos Zoulas, Gunnar Ritter.
8577     S-nail is developed by Steffen Nurpmeso <s-mailx@lists.sdaoden.eu>.
8578

CAVEATS

8580     [v15 behaviour may differ] Interrupting an operation via SIGINT aka
8581     ‘control-C’ from anywhere else but a command prompt is very problematic
8582     and likely to leave the program in an undefined state: many library func‐
8583     tions cannot deal with the siglongjmp(3) that this software (still) per‐
8584     forms; even though efforts have been taken to address this, no sooner but
8585     in v15 it will have been worked out: interruptions have not been disabled
8586     in order to allow forceful breakage of hanging network connections, for
8587     example (all this is unrelated to ignore).
8588
8589     The SMTP and POP3 protocol support of S-nail is very basic.  Also, if it
8590     fails to contact its upstream SMTP server, it will not make further at‐
8591     tempts to transfer the message at a later time (setting save and sendwait
8592     may be useful).  If this is a concern, it might be better to set up a lo‐
8593     cal SMTP server that is capable of message queuing.
8594

BUGS

8596     When a network-based mailbox is open, directly changing to another net‐
8597     work-based mailbox of a different protocol (i.e., from POP3 to IMAP or
8598     vice versa) will cause a “deadlock”.
8599
8600     After deleting some message of a POP3 mailbox the header summary falsely
8601     claims that there are no messages to display, one needs to perform a
8602     scroll or dot movement to restore proper state.
8603
8604     In ‘thread’ed sort mode a power user may encounter crashes very occasion‐
8605     ally (this is may and very).
8606
8607     Please report bugs to the contact-mail address, for example from within
8608     s-nail: ‘? eval mail $contact-mail’.  Including the verbose output of the
8609     command version may be helpful:
8610
8611           ? wysh set escape=! verbose; vput version xy; unset verbose;\
8612             eval mail $contact-mail
8613           Bug subject
8614           !I xy
8615           !.
8616
8617     Information on the web at ‘$ s-nail -X 'echo $contact-web; x'’.
8618
8619BSD                            November 11, 2021                           BSD
Impressum