2 @setfilename tm-edit-en.info
3 @settitle{tm-edit 7.100 Reference Manual (English Version)}
5 @title tm-edit 7.100 Reference Manual (English Version)
6 @author MORIOKA Tomohiko <morioka@@jaist.ac.jp>
9 @node Top, Introduction, (dir), (dir)
10 @top tm-edit 7.100 Reference Manual (English Version)
14 This file documents tm-edit, a MIME composer for GNU Emacs.
18 * Introduction:: What is tm-edit?
20 * single-part operations::
21 * enclosure operation::
22 * other operations of mime/editor-mode::
23 * tag specification for inserted file:: Default media-type or encoding for inserted file
25 * header:: Using non-ASCII characters in header
33 @node Introduction, mime/editor-mode, Top, Top
34 @chapter What is tm-edit?
37 @strong{tm-edit} is a general MIME composer for GNU Emacs.@refill
39 tm-edit is based on mime.el by UMEDA Masanobu
40 <umerin@@mse.kyutech.ac.jp>, who is famous as the author of
41 GNUS. tm-edit expands following points from @file{mime.el}:
45 based on RFC 1521/1522
47 Content-Disposition field (@ref{(tm-en)Content-Disposition}) (RFC 1806)
50 nested multi-part message (@ref{(tm-en)multipart})
52 PGP (@ref{PGP}) (PGP/MIME (RFC 2015) based on security multipart (RFC
53 1847) and application/pgp based on traditional PGP)
55 strength automatic specification for parameter of file type
59 In tm-MUA (@ref{(tm-en)tm-MUA}), you can edit MIME message easily to use
63 @node mime/editor-mode, single-part operations, Introduction, Top
64 @chapter mime/editor-mode
66 @cindex multi-part ending tag
67 @cindex multi-part beginning tag
69 @cindex mime/editor-mode
71 @strong{mime/editor-mode} is a minor mode to compose MIME message. In
72 this mode, @strong{tag} represents various kinds of data, you can edit
73 multi part (@ref{(tm-en)multipart}) message.@refill
75 There are 2 kinds of tags:
84 single-part tag represents single part, this form is following:
87 --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
91 TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
92 Content-Type field (@ref{(tm-en)Content-Type field}). TYPE/SUBTYPE is
93 required, PARAMETERS is optional.@refill
95 ENCODING indicates Content-Transfer-Encoding field. It is optional
98 OPTIONAL-FIELDS is to represent another fields except Content-Type field
99 and Content-Transfer-Encoding field.@refill
101 multi-part tags represent multi part (@ref{(tm-en)multipart}). They
102 consist of a pair of @strong{multi-part beginning tag} and
103 @strong{multi-part ending tag}.@refill
105 multi-part beginning tag's form is following:@refill
111 multi-part ending tag's form is following:@refill
117 A region from multi-part beginning tag to multi-part ending tag is
118 called as @strong{enclosure}.
121 @node single-part operations, enclosure operation, mime/editor-mode, Top
122 @chapter single-part operations
124 Operations to make single-part are following:
127 @item @key{C-c C-x C-t}
128 Insert single-part tag indicates text part.
130 @item @key{C-c C-x C-i}
131 Insert file as a MIME attachment. If @kbd{C-u} is followed by it, it
132 asks media-type, subtype or encoding even if their default values are
133 specified. (cf. @ref{tag specification for inserted file})
135 @item @key{C-c C-x C-e}
136 Insert external part.
138 @item @key{C-c C-x C-v}
139 Record audio input until @kbd{C-g} is pressed, and insert as a
140 audio part. (It requires /dev/audio in default.)
142 @item @key{C-c C-x C-y}
143 Insert current (mail or news) message. (It is MUA depended.)
145 @item @key{C-c C-x C-m}
146 Insert mail message. (It is MUA depended.)
148 @item @key{C-c C-x C-w}, @key{C-c C-x C-s}
151 @item @key{C-c C-x C-k}
152 Insert PGP (@ref{PGP}) public key. (It requires Mailcrypt package.)
154 @item @key{C-c C-x t}
155 Insert any single-part tag.
161 @node enclosure operation, other operations of mime/editor-mode, single-part operations, Top
162 @chapter enclosure operation
164 Operations to make enclosure are following:
167 @item @key{C-c C-x a}
168 Enclose specified region as multipart/alternative.
170 @item @key{C-c C-x p}
171 Enclose specified region as multipart/parallel.
173 @item @key{C-c C-x m}
174 Enclose specified region as multipart/mixed.
176 @item @key{C-c C-x d}
177 Enclose specified region as multipart/digest.
179 @item @key{C-c C-x s}
180 Digital-sign to specified region. (cf. @ref{PGP})
182 @item @key{C-c C-x e}
183 Encrypt to specified region. (cf. @ref{PGP})
185 @item @key{C-c C-x q}
186 avoid to encode tags in specified region. In other words, tags is
187 interpreted as such string. (In current version, it may be
188 incomplete. Maybe PGP-signature does not work for this enclosure.)
194 @node other operations of mime/editor-mode, tag specification for inserted file, enclosure operation, Top
195 @chapter other operations of mime/editor-mode
197 There are another operations in mime/editor-mode.
201 Send current editing message.
203 @item @key{C-c C-x C-p}
204 Preview current editing message. (@ref{(tm-view-en)mime/viewer-mode})
206 @item @key{C-c C-x C-z}
207 Exit mime/editor-mode. (@key{M-x mime/edit-again} is available to
210 @item @key{C-c C-x ?}
211 Display help message.
213 @item @key{C-c C-x /}
214 Set current editing message to enable automatic splitting or not.
215 Form of automatic split messages is message/partial.
217 @item @key{C-c C-x 7}
218 Set 7bit (@ref{(tm-en)7bit}) to transfer level (@ref{transfer level}).
220 @item @key{C-c C-x 8}
221 Set 8bit (@ref{(tm-en)8bit}) to transfer level (@ref{transfer level}).
223 @item @key{C-c C-x v}
224 Set current editing message to digital-sign or not. (cf. @ref{PGP})
226 @item @key{C-c C-x h}
227 Set current editing message to encrypt or not. (cf. @ref{PGP})
233 @node tag specification for inserted file, transfer level, other operations of mime/editor-mode, Top
234 @chapter Default media-type or encoding for inserted file
236 When @kbd{C-c C-x C-i} (@code{mime-editor/insert-file}) is pressed, tag
237 parameters for inserted file, such as media-type or encoding, are
238 detected by variable @code{mime-file-types}.@refill
240 When @kbd{C-u} is followed by it or parameter is not found from the
241 variable, it asks from user. (When @kbd{C-u} is followed by it,
242 detected value is used as default value)@refill
244 If you want to change default value for file names, please change
245 variable @code{mime-file-types}.
248 @defvar mime-file-types
250 Specification of default value of tag for file name of inserted
253 It is a list of following list:
256 (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
257 DISPOSITION_TYPE DISPOSITION_PARAMS)
261 Each elements of the list are following:
265 regular expression of file name
274 parameters of Content-Type field
277 Content-Transfer-Encoding
279 @item DISPOSITION_TYPE
282 @item DISPOSITION_PARAMS
283 parameters of Content-Disposition field
288 Example: Specify application/rtf as default media type for
295 (set-alist 'mime-file-types
297 '("application" "rtf" nil nil
298 "attachment" (("filename" . file)))
305 @node transfer level, header, tag specification for inserted file, Top
306 @chapter transfer level
307 @cindex transfer level
309 Contents inserted in a message are represented by 7bit
310 (@ref{(tm-en)7bit}), 8bit (@ref{(tm-en)8bit}) or binary
311 (@ref{(tm-en)binary}).@refill
313 If a message is translated by 7bit-through MTA (@ref{(tm-en)MTA}), there
314 is no need to encode 7bit data, but 8bit and binary data must be encoded
317 Similarly, if a message is translated by 8bit-through MTA, there is no
318 need to encode 7bit or 8bit data, but binary data must be encoded to
319 7bit or 8bit data.@refill
324 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
325 encoded by base64. But I don't know EBCDIC. (^_^;
327 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
328 disappeared. (^_^;@refill
330 Maybe there are binary-through MTA, but I think it is not major.
333 @strong{transfer level} represents how range data is
334 available. tm-edit has a variable
335 @code{mime-editor/transfer-level} to represent transfer level.
338 @defvar mime-editor/transfer-level
340 transfer level.@refill
342 If transfer level of a data is over it, a data is encoded to
345 Currently, 7 or 8 is available. Default value is 7.@refill
347 In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
348 binary will be 9. But it will not be implemented.
356 transfer level is only for body, not for header (@ref{header}). RFC
357 1521 extends RFC 822 (@ref{(tm-en)RFC 822}) to use 8bit data in body,
358 but it requires to use us-ascii (@ref{(tm-en)us-ascii}) in header.
363 @node header, PGP, transfer level, Top
364 @chapter Using non-ASCII characters in header
367 RFC 1522 (@ref{(tm-en)RFC 1522}) defines representation of non-ASCII
368 characters in header.@refill
370 It is a format called as @strong{encoded-word}
371 (@ref{(tm-en)encoded-word}), it is available to represent every
372 non-ASCII characters by 7bit (@ref{(tm-en)7bit}) to declare MIME charset
373 (@ref{(tm-en)MIME charset}).
377 * evil setting in header:: If you can not allow encoded-word
378 * API about header:: Functions and variables about header
381 @node evil setting in header, API about header, header, header
382 @section If you can not allow encoded-word
384 It is wrong to use ``raw'' non-ASCII characters in header not to use
385 encoded-word. Because there are various kinds of coded character set
386 (@ref{(tm-en)Coded character set}) in the Internet, so we can not
387 distinguish them if MIME charset (@ref{(tm-en)MIME charset}) is not
390 For example, we can not distinguish iso-8859-1 (@ref{(tm-en)iso-8859-1})
391 and iso-8859-2 (@ref{(tm-en)iso-8859-2}) if MIME charset is not
394 However you can not permit to use encoded-word, please set to
398 @defvar mime/field-encoding-method-alist
400 Association-list to specify field encoding method. Its key is
401 field-name, value is encoding method.@refill
403 field-name allows string or @code{t} meaning any fields.@refill
405 Encoding method allows following: @code{nil} means no-conversion,
406 @code{mime} means to convert as encoded-word, symbol represent MIME
407 charset means to convert as the coded character set instead of to
408 convert as encoded-word.@refill
410 field-name is searched from string. If it is not found, @code{t} is
413 Default value of @code{mime/field-encoding-method-alist} is
417 (("X-Nsubject" . iso-2022-jp-2)
425 In addition, if you want to specify by coded character set instead of
426 field, please use @code{mime-eword/charset-encoding-alist}.
427 (cf. @ref{API about header})
431 @node API about header, , evil setting in header, header
432 @section Functions and variables about header
434 @deffn{Command} mime/encode-message-header &optional code-conversion
436 It translate non-ASCII characters in message header of current buffer
437 into network representation, such as encoded-words.@refill
439 If @var{code-conversion} is non-@code{nil}, field not encoded by
440 encoded-word is converted by @code{mime/field-encoding-method-alist}.
444 @defun mime/encode-field string
446 It encodes @var{string} into encoded-words as a field.@refill
448 Long lines are folded.
452 @defun mime-eword/encode-string string &optional column mode
454 It encodes @var{string} into encoded-words.@refill
456 Long lines are folded.@refill
458 @var{column} specifies start column. If it is omitted, 0 is
461 @var{mode} specifies where @var{string} is in. Available values are
462 @code{text}, @code{comment}, @code{phrase}. If it is omitted,
463 @code{phrase} is used.
467 @defvar mime-eword/charset-encoding-alist
469 Association-list of symbol represent MIME charset vs. nil, @code{"B"} or
472 @code{nil} means not to encode as encoded-word. @code{"B"} means to use
473 B-encoding. @code{"Q"} means to use Q-encoding.
478 @node PGP, Acknowledgments, header, Top
483 tm-edit provides PGP encryption, signature and inserting public-key
484 features based on @strong{PGP/MIME} (@ref{(tm-en)PGP/MIME}) (RFC 2015)
485 or @strong{PGP-kazu} (@ref{(tm-en)PGP-kazu})
486 (draft-kazu-pgp-mime-00.txt).@refill
488 This feature requires pgp command and Mailcrypt package
489 (@ref{(mailcrypt)}).@refill
491 If you want to use this feature, please set @code{pgp-elkins} or
492 @code{pgp-kazu} to variable @code{mimed-editor/signing-type} and
493 variable @code{mime-editor/encrypting-type}.@refill
495 If @code{pgp-elkins} is specified, PGP/MIME is used. If
496 @code{pgp-kazu} is specified, PGP-kazu is used.
499 @defvar mime-editor/signing-type
501 Format of PGP signature.@refill
503 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
505 Default value is @code{nil}.
509 @defvar mime-editor/encrypting-type
511 Format of PGP encryption.@refill
513 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
515 Default value is @code{nil}.
520 @node Acknowledgments, Concept Index, PGP, Top
521 @chapter Acknowledgments
523 First of all, I thank UMEDA Masanobu for his work of @file{mime.el},
524 which is the origin of tm-edit, and permission to rewrite his work as
527 I thank members of two tm mailing lists, Japanese and English version.
530 @node Concept Index, Function Index, Acknowledgments, Top
531 @chapter Concept Index
535 @node Function Index, Variable Index, Concept Index, Top
536 @chapter Function Index
540 @node Variable Index, , Function Index, Top
541 @chapter Variable Index