1 <!doctype sinfo system>
2 <!-- $Id: tm-edit-en.sgml,v 3.1 1996/12/25 19:02:42 morioka Exp $ -->
4 <title>tm-edit 7.100 Reference Manual (English Version)
5 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
15 This file documents tm-edit, a MIME composer for GNU Emacs.
22 <concept>tm-edit</concept> is a general MIME composer for GNU Emacs.
24 tm-edit is based on mime.el by UMEDA Masanobu
25 <mail>umerin@mse.kyutech.ac.jp</mail>, who is famous as the author of
26 GNUS. tm-edit expands following points from <file>mime.el</file>:
30 based on RFC 1521/1522
32 <a file="tm-en" node="Content-Disposition">Content-Disposition
33 field</a> (RFC 1806) supports
35 nested <a file="tm-en" node="multipart">multi-part message</a>
37 <dref>PGP</dref> (PGP/MIME (RFC 2015) based on security multipart (RFC
38 1847) and application/pgp based on traditional PGP)
40 strength automatic specification for parameter of file type
44 In <dref file="tm-en">tm-MUA</dref>, you can edit MIME message easily
49 <node> mime/editor-mode
51 <concept>mime/editor-mode</concept> is a minor mode to compose MIME
52 message. In this mode, <concept>tag</concept> represents various
53 kinds of data, you can edit <a file="tm-en" node="multipart">multi
56 There are 2 kinds of tags:
63 single-part tag represents single part, this form is following:
66 --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
70 TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
71 <dref file="tm-en">Content-Type field</dref>. TYPE/SUBTYPE is
72 required, PARAMETERS is optional.
74 ENCODING indicates Content-Transfer-Encoding field. It is optional
77 OPTIONAL-FIELDS is to represent another fields except Content-Type
78 field and Content-Transfer-Encoding field.
80 multi-part tags represent <a file="tm-en" node="multipart">multi
81 part</a>. They consist of a pair of <concept>multi-part beginning
82 tag</concept> and <concept>multi-part ending tag</concept>.
84 multi-part beginning tag's form is following:
90 multi-part ending tag's form is following:
96 A region from multi-part beginning tag to multi-part ending tag is
97 called as <concept>enclosure</concept>.
100 <h1> single-part operations
101 <node> single-part operations
103 Operations to make single-part are following:
108 Insert single-part tag indicates text part.
112 Insert file as a MIME attachment. If <kbd>C-u</kbd> is followed by
113 it, it asks media-type, subtype or encoding even if their default
114 values are specified. <cf node="tag specification for inserted file">
118 Insert external part.
122 Record audio input until <kbd>C-g</kbd> is pressed, and insert as a
123 audio part. (It requires /dev/audio in default.)
127 Insert current (mail or news) message. (It is MUA depended.)
131 Insert mail message. (It is MUA depended.)
133 <dt><key>C-c C-x C-w</key>, <key>C-c C-x C-s</key>
139 Insert <dref>PGP</dref> public key. (It requires Mailcrypt package.)
143 Insert any single-part tag.
148 <h1> enclosure operation
149 <node> enclosure operation
151 Operations to make enclosure are following:
156 Enclose specified region as multipart/alternative.
160 Enclose specified region as multipart/parallel.
164 Enclose specified region as multipart/mixed.
168 Enclose specified region as multipart/digest.
172 Digital-sign to specified region. <cf node="PGP">
176 Encrypt to specified region. <cf node="PGP">
179 avoid to encode tags in specified region. In other words, tags is
180 interpreted as such string. (In current version, it may be
181 incomplete. Maybe PGP-signature does not work for this enclosure.)
185 <h1> other operations of mime/editor-mode
186 <node> other operations of mime/editor-mode
188 There are another operations in mime/editor-mode.
193 Send current editing message.
197 Preview current editing message. (<ref file="tm-view-en"
198 node="mime/viewer-mode">)
202 Exit mime/editor-mode. (<key>M-x mime/edit-again</key> is available to
207 Display help message.
211 Set current editing message to enable automatic splitting or not.
212 Form of automatic split messages is message/partial.
216 Set <dref file="tm-en">7bit</dref> to <dref>transfer level</dref>.
220 Set <dref file="tm-en">8bit</dref> to <dref>transfer level</dref>.
224 Set current editing message to digital-sign or not. <cf node="PGP">
228 Set current editing message to encrypt or not. <cf node="PGP">
232 <h1> Default media-type or encoding for inserted file
233 <node> tag specification for inserted file
235 When <kbd>C-c C-x C-i</kbd> (<code>mime-editor/insert-file</code>) is
236 pressed, tag parameters for inserted file, such as media-type or
237 encoding, are detected by variable <code>mime-file-types</code>.
239 When <kbd>C-u</kbd> is followed by it or parameter is not found from
240 the variable, it asks from user. (When <kbd>C-u</kbd> is followed by
241 it, detected value is used as default value)
243 If you want to change default value for file names, please change
244 variable <code>mime-file-types</code>.
247 <defvar name="mime-file-types">
249 Specification of default value of tag for file name of inserted file.
251 It is a list of following list:
254 (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
255 DISPOSITION_TYPE DISPOSITION_PARAMS)
258 Each elements of the list are following:
262 <dd>regular expression of file name
268 <dd>parameters of Content-Type field
270 <dd>Content-Transfer-Encoding
273 <dt>DISPOSITION_PARAMS
274 <dd>parameters of Content-Disposition field
278 Example: Specify application/rtf as default media type for
285 (set-alist 'mime-file-types
287 '("application" "rtf" nil nil
288 "attachment" (("filename" . file)))
295 <node> transfer level
297 Contents inserted in a message are represented by <dref
298 file="tm-en">7bit</dref>, <dref file="tm-en">8bit</dref> or <dref
299 file="tm-en">binary</dref>.
301 If a message is translated by 7bit-through <dref
302 file="tm-en">MTA</dref>, there is no need to encode 7bit data, but
303 8bit and binary data must be encoded to 7bit data.
305 Similarly, if a message is translated by 8bit-through MTA, there is no
306 need to encode 7bit or 8bit data, but binary data must be encoded to
310 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
311 encoded by base64. But I don't know EBCDIC. (^_^;
313 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
316 Maybe there are binary-through MTA, but I think it is not major.
319 <concept>transfer level</concept> represents how range data is
320 available. tm-edit has a variable
321 <code>mime-editor/transfer-level</code> to represent transfer level.
324 <defvar name="mime-editor/transfer-level">
328 If transfer level of a data is over it, a data is encoded to 7bit.
330 Currently, 7 or 8 is available. Default value is 7.
332 In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
333 binary will be 9. But it will not be implemented.
338 transfer level is only for body, not for <a node="header">header</a>.
339 RFC 1521 extends <dref file="tm-en">RFC 822</dref> to use 8bit data in
340 body, but it requires to use <dref file="tm-en">us-ascii</dref> in
345 <h1> Using non-ASCII characters in header
348 <dref file="tm-en">RFC 1522</dref> defines representation of non-ASCII
349 characters in header.
351 It is a format called as <a file="tm-en"
352 node="encoded-word"><concept>encoded-word</concept></a>, it is
353 available to represent every non-ASCII characters by <dref
354 file="tm-en">7bit</dref> to declare <dref file="tm-en">MIME
358 <h2> If you can not allow encoded-word
359 <node> evil setting in header
361 It is wrong to use ``raw'' non-ASCII characters in header not to use
362 encoded-word. Because there are various kinds of <a file="tm-en"
363 node="Coded character set">coded character set</a> in the Internet, so
364 we can not distinguish them if <dref file="tm-en">MIME charset</dref>
367 For example, we can not distinguish <dref
368 file="tm-en">iso-8859-1</dref> and <dref
369 file="tm-en">iso-8859-2</dref> if MIME charset is not declared.
371 However you can not permit to use encoded-word, please set to
375 <defvar name="mime/field-encoding-method-alist">
377 Association-list to specify field encoding method. Its key is
378 field-name, value is encoding method.
380 field-name allows string or <code>t</code> meaning any fields.
382 Encoding method allows following: <code>nil</code> means
383 no-conversion, <code>mime</code> means to convert as encoded-word,
384 symbol represent MIME charset means to convert as the coded character
385 set instead of to convert as encoded-word.
387 field-name is searched from string. If it is not found,
388 <code>t</code> is used.
390 Default value of <code>mime/field-encoding-method-alist</code> is
394 (("X-Nsubject" . iso-2022-jp-2)
402 In addition, if you want to specify by coded character set instead of
403 field, please use <code>mime-eword/charset-encoding-alist</code>.
404 <cf node="API about header">
407 <h2> Functions and variables about header
408 <node> API about header
410 <define type="Command" name="mime/encode-message-header">
411 <opts> code-conversion
413 It translate non-ASCII characters in message header of current buffer
414 into network representation, such as encoded-words.
416 If <var>code-conversion</var> is non-<code>nil</code>, field not
417 encoded by encoded-word is converted by
418 <code>mime/field-encoding-method-alist</code>.
421 <defun name="mime/encode-field">
424 It encodes <var>string</var> into encoded-words as a field.
426 Long lines are folded.
429 <defun name="mime-eword/encode-string">
430 <args> string <opts> column mode
432 It encodes <var>string</var> into encoded-words.
434 Long lines are folded.
436 <var>column</var> specifies start column. If it is omitted, 0 is
439 <var>mode</var> specifies where <var>string</var> is in. Available
440 values are <code>text</code>, <code>comment</code>,
441 <code>phrase</code>. If it is omitted, <code>phrase</code> is used.
444 <defvar name="mime-eword/charset-encoding-alist">
446 Association-list of symbol represent MIME charset vs. nil,
447 <code>"B"</code> or <code>"Q"</code>.
449 <code>nil</code> means not to encode as encoded-word.
450 <code>"B"</code> means to use B-encoding.
451 <code>"Q"</code> means to use Q-encoding.
458 tm-edit provides PGP encryption, signature and inserting public-key
459 features based on <a file="tm-en"
460 node="PGP/MIME"><concept>PGP/MIME</concept></a> (RFC 2015) or <a
461 file="tm-en" node="PGP-kazu"><concept>PGP-kazu</concept></a>
462 (draft-kazu-pgp-mime-00.txt).
464 This feature requires pgp command and <a file="mailcrypt">Mailcrypt
467 If you want to use this feature, please set <code>pgp-elkins</code> or
468 <code>pgp-kazu</code> to variable
469 <code>mimed-editor/signing-type</code> and variable
470 <code>mime-editor/encrypting-type</code>.
472 If <code>pgp-elkins</code> is specified, PGP/MIME is used. If
473 <code>pgp-kazu</code> is specified, PGP-kazu is used.
476 <defvar name="mime-editor/signing-type">
478 Format of PGP signature.
480 It allows <code>pgp-elkins</code> or <code>pgp-kazu</code>.
482 Default value is <code>nil</code>.
485 <defvar name="mime-editor/encrypting-type">
487 Format of PGP encryption.
489 It allows <code>pgp-elkins</code> or <code>pgp-kazu</code>.
491 Default value is <code>nil</code>.
496 <node> Acknowledgments
498 First of all, I thank UMEDA Masanobu for his work of
499 <file>mime.el</file>, which is the origin of tm-edit, and permission
500 to rewrite his work as tm-edit.
502 I thank members of two tm mailing lists, Japanese and English version.
512 <node> Function Index
518 <node> Variable Index