tm 7.95.
[elisp/tm.git] / doc / tm-edit-en.texi
1 \input texinfo.tex
2 @setfilename tm-edit-en.info
3 @settitle{tm-edit 7.90 Reference Manual (English Version)}
4 @titlepage
5 @title tm-edit 7.90 Reference Manual (English Version)
6 @author MORIOKA Tomohiko <morioka@@jaist.ac.jp>
7 @subtitle 1996/10/11
8 @end titlepage
9 @node Top, Introduction, (dir), (dir)
10 @top tm-edit 7.90 Reference Manual (English Version)
11
12 @ifinfo
13
14 This file documents tm-edit, a MIME composer for GNU Emacs.
15 @end ifinfo
16
17 @menu
18 * Introduction::                What is tm-edit?
19 * mime/editor-mode::            
20 * single-part operations::      
21 * enclosure operation::         
22 * other operations of mime/editor-mode::  
23 * transfer level::              
24 * header::                      Using non-ASCII characters in header
25 * PGP::                         
26 * Concept Index::               
27 * Function Index::              
28 * Variable Index::              
29 @end menu
30
31 @node Introduction, mime/editor-mode, Top, Top
32 @chapter What is tm-edit?
33
34 @cindex{tm-edit}@strong{tm-edit} is a general MIME composer for GNU
35 Emacs.@refill
36
37 tm-edit is based on mime.el by UMEDA Masanobu
38 <umerin@@mse.kyutech.ac.jp>, who is famous as the author of
39 GNUS.  tm-edit expands following points from @file{mime.el}:
40
41 @itemize @bullet
42 @item
43 based on RFC 1521/1522
44 @item
45 Content-Disposition field (@ref{(tm-en)Content-Disposition}) (RFC 1806)
46 supports
47 @item
48 nested multi-part message (@ref{(tm-en)multipart})
49 @item
50 PGP (@ref{PGP}) (PGP/MIME (RFC 2015) based on security multipart (RFC
51 1847) and application/pgp based on traditional PGP)
52 @item
53 strength automatic specification for parameter of file type
54 @end itemize
55
56
57 In tm-MUA (@ref{(tm-en)tm-MUA}), you can edit MIME message easily to use
58 tm-edit.
59
60
61 @node mime/editor-mode, single-part operations, Introduction, Top
62 @chapter mime/editor-mode
63
64 @cindex{mime/editor-mode}@strong{mime/editor-mode} is a minor mode to
65 compose MIME message.  In this mode, @cindex{tag}@strong{tag} represents
66 various kinds of data, you can edit multi part (@ref{(tm-en)multipart})
67 message.@refill
68
69 There are 2 kinds of tags:
70
71 @itemize @bullet
72 @item
73  single-part tag
74 @item
75  multi-part tag
76 @end itemize
77
78 single-part tag represents single part, this form is following:
79
80 @example
81         --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
82         OPTIONAL-FIELDS]
83 @end example
84
85 TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
86 Content-Type field (@ref{(tm-en)Content-Type field}).  TYPE/SUBTYPE is
87 required, PARAMETERS is optional.@refill
88
89 ENCODING indicates Content-Transfer-Encoding field.  It is optional
90 too.@refill
91
92 OPTIONAL-FIELDS is to represent another fields except Content-Type field
93 and Content-Transfer-Encoding field.@refill
94
95 multi-part tags represent multi part (@ref{(tm-en)multipart}).  They
96 consist of a pair of @cindex{multi-part beginning tag}@strong{multi-part
97 beginning tag} and @cindex{multi-part ending tag}@strong{multi-part
98 ending tag}.@refill
99
100 multi-part beginning tag's form is following:@refill
101
102 @example
103         --<<TYPE>>-@{
104 @end example
105
106 multi-part ending tag's form is following:@refill
107
108 @example
109         --@}-<<TYPE>>
110 @end example
111
112 A region from multi-part beginning tag to multi-part ending tag is
113 called as @cindex{enclosure}@strong{enclosure}.
114
115
116 @node single-part operations, enclosure operation, mime/editor-mode, Top
117 @chapter single-part operations
118
119 Operations to make single-part are following:
120
121 @table @kbd
122 @item @key{C-c C-x C-t}
123 Insert single-part tag indicates text part.
124
125 @item @key{C-c C-x C-i}
126 Insert file as a MIME attachment.
127
128 @item @key{C-c C-x C-e}
129 Insert external part.
130
131 @item @key{C-c C-x C-v}
132 Record audio input until @kbd{C-g} is pressed, and insert as a
133 audio part. (It requires /dev/audio in default.)
134
135 @item @key{C-c C-x C-y}
136 Insert current (mail or news) message. (It is MUA depended.)
137
138 @item @key{C-c C-x C-m}
139 Insert mail message. (It is MUA depended.)
140
141 @item @key{C-c C-x C-w}, @key{C-c C-x C-s}
142 Insert signature.
143
144 @item @key{C-c C-x C-k}
145 Insert PGP (@ref{PGP}) public key. (It requires Mailcrypt package.)
146
147 @item @key{C-c C-x t}
148 Insert any single-part tag.
149
150 @end table
151
152
153
154 @node enclosure operation, other operations of mime/editor-mode, single-part operations, Top
155 @chapter enclosure operation
156
157 Operations to make enclosure are following:
158
159 @table @kbd
160 @item @key{C-c C-x a}
161 Enclose specified region as multipart/alternative.
162
163 @item @key{C-c C-x p}
164 Enclose specified region as multipart/parallel.
165
166 @item @key{C-c C-x m}
167 Enclose specified region as multipart/mixed.
168
169 @item @key{C-c C-x d}
170 Enclose specified region as multipart/digest.
171
172 @item @key{C-c C-x s}
173 Digital-sign to specified region. (cf. @ref{PGP})
174
175 @item @key{C-c C-x e}
176 Encrypt to specified region. (cf. @ref{PGP})
177
178 @item @key{C-c C-x q}
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.)
182
183 @end table
184
185
186
187 @node other operations of mime/editor-mode, transfer level, enclosure operation, Top
188 @chapter other operations of mime/editor-mode
189
190 There are another operations in mime/editor-mode.
191
192 @table @kbd
193 @item @key{C-c C-c}
194 Send current editing message.
195
196 @item @key{C-c C-x C-p}
197 Preview current editing message. (@ref{(tm-view-en)mime/viewer-mode})
198
199 @item @key{C-c C-x C-z}
200 Exit mime/editor-mode. (@key{M-x mime/edit-again} is available to
201 reedit.)
202
203 @item @key{C-c C-x ?}
204 Display help message.
205
206 @item @key{C-c C-x /}
207 Set current editing message to enable automatic splitting or not.
208 Form of automatic split messages is message/partial.
209
210 @item @key{C-c C-x 7}
211 Set 7bit (@ref{(tm-en)7bit}) to transfer level (@ref{transfer level}).
212
213 @item @key{C-c C-x 8}
214 Set 8bit (@ref{(tm-en)8bit}) to transfer level (@ref{transfer level}).
215
216 @item @key{C-c C-x v}
217 Set current editing message to digital-sign or not. (cf. @ref{PGP})
218
219 @item @key{C-c C-x h}
220 Set current editing message to encrypt or not. (cf. @ref{PGP})
221
222 @end table
223
224
225
226 @node transfer level, header, other operations of mime/editor-mode, Top
227 @chapter transfer level
228
229 Contents inserted in a message are represented by 7bit
230 (@ref{(tm-en)7bit}), 8bit (@ref{(tm-en)8bit}) or binary
231 (@ref{(tm-en)binary}).@refill
232
233 If a message is translated by 7bit-through MTA (@ref{(tm-en)MTA}), there
234 is no need to encode 7bit data, but 8bit and binary data must be encoded
235 to 7bit data.@refill
236
237 Similarly, if a message is translated by 8bit-through MTA, there is no
238 need to encode 7bit or 8bit data, but binary data must be encoded to
239 7bit or 8bit data.@refill
240
241 @noindent
242 @strong{[Memo]}
243 @quotation
244 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
245 encoded by base64.  But I don't know EBCDIC. (^_^;
246
247 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
248 disappeared. (^_^;@refill
249
250 Maybe there are binary-through MTA, but I think it is not major.
251 @end quotation
252
253 @cindex{transfer level}@strong{transfer level} represents how range data is
254 available.  tm-edit has a variable
255 @code{mime-editor/transfer-level} to represent transfer level.
256
257
258 @defvar mime-editor/transfer-level
259
260 transfer level.@refill
261
262 If transfer level of a data is over it, a data is encoded to
263 7bit.@refill
264
265 Currently, 7 or 8 is available.  Default value is 7.@refill
266
267 In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
268 binary will be 9.  But it will not be implemented.
269 @end defvar
270
271
272
273 @noindent
274 @strong{[Memo]}
275 @quotation
276 transfer level is only for body, not for header (@ref{header}).  RFC
277 1521 extends RFC 822 (@ref{(tm-en)RFC 822}) to use 8bit data in body,
278 but it requires to use us-ascii (@ref{(tm-en)us-ascii}) in header.
279 @end quotation
280
281
282
283 @node header, PGP, transfer level, Top
284 @chapter Using non-ASCII characters in header
285
286 RFC 1522 (@ref{(tm-en)RFC 1522}) defines representation of non-ASCII
287 characters in header.@refill
288
289 It is a format called as @cindex{encoded-word}@strong{encoded-word}
290 (@ref{(tm-en)encoded-word}), it is available to represent every
291 non-ASCII characters by 7bit (@ref{(tm-en)7bit}) to declare MIME charset
292 (@ref{(tm-en)MIME charset}).
293
294
295 @menu
296 * evil setting in header::      If you can not allow encoded-word
297 * API about header::            Functions and variables about header
298 @end menu
299
300 @node evil setting in header, API about header, header, header
301 @section If you can not allow encoded-word
302
303 It is wrong to use ``raw'' non-ASCII characters in header not to use
304 encoded-word.  Because there are various kinds of coded character set
305 (@ref{(tm-en)Coded character set}) in the Internet, so we can not
306 distinguish them if MIME charset (@ref{(tm-en)MIME charset}) is not
307 declared.@refill
308
309 For example, we can not distinguish iso-8859-1 (@ref{(tm-en)iso-8859-1})
310 and iso-8859-2 (@ref{(tm-en)iso-8859-2}) if MIME charset is not
311 declared.@refill
312
313 However you can not permit to use encoded-word, please set to
314 following variables:
315
316
317 @defvar mime/field-encoding-method-alist
318
319 Association-list to specify field encoding method.  Its key is
320 field-name, value is encoding method.@refill
321
322 field-name allows string or @code{t} meaning any fields.@refill
323
324 Encoding method allows following: @code{nil} means no-conversion,
325 @code{mime} means to convert as encoded-word, symbol represent MIME
326 charset means to convert as the coded character set instead of to
327 convert as encoded-word.@refill
328
329 field-name is searched from string.  If it is not found, @code{t} is
330 used.@refill
331
332 Default value of @code{mime/field-encoding-method-alist} is
333 following:
334
335 @lisp
336 (("X-Nsubject" . iso-2022-jp-2)
337  ("Newsgroups" . nil)
338  (t            . mime)
339  ))
340 @end lisp
341 @end defvar
342
343
344 In addition, if you want to specify by coded character set instead of
345 field, please use @code{mime-eword/charset-encoding-alist}.
346 (cf. @ref{API about header})
347
348
349
350 @node API about header,  , evil setting in header, header
351 @section Functions and variables about header
352
353 @deffn{Command} mime/encode-message-header &optional  code-conversion
354
355 It translate non-ASCII characters in message header of current buffer
356 into network representation, such as encoded-words.@refill
357
358 If @var{code-conversion} is non-@code{nil}, field not encoded by
359 encoded-word is converted by @code{mime/field-encoding-method-alist}.
360 @end deffn
361
362
363 @defun mime/encode-field string
364
365 It encodes @var{string} into encoded-words as a field.@refill
366
367 Long lines are folded.
368 @end defun
369
370
371 @defun mime-eword/encode-string string  &optional  column mode
372
373 It encodes @var{string} into encoded-words.@refill
374
375 Long lines are folded.@refill
376
377 @var{column} specifies start column.  If it is omitted, 0 is
378 used.@refill
379
380 @var{mode} specifies where @var{string} is in.  Available values are
381 @code{text}, @code{comment}, @code{phrase}.  If it is omitted,
382 @code{phrase} is used.
383 @end defun
384
385
386 @defvar mime-eword/charset-encoding-alist
387
388 Association-list of symbol represent MIME charset vs. nil, @code{"B"} or
389 @code{"Q"}.@refill
390
391 @code{nil} means not to encode as encoded-word.  @code{"B"} means to use
392 B-encoding.  @code{"Q"} means to use Q-encoding.
393 @end defvar
394
395
396
397 @node PGP, Concept Index, header, Top
398 @chapter PGP
399
400 tm-edit provides PGP encryption, signature and inserting public-key
401 features based on @cindex{PGP/MIME}@strong{PGP/MIME}
402 (@ref{(tm-en)PGP/MIME}) (RFC 2015) or @cindex{PGP-kazu}@strong{PGP-kazu}
403 (@ref{(tm-en)PGP-kazu}) (draft-kazu-pgp-mime-00.txt).@refill
404
405 This feature requires pgp command and Mailcrypt package
406 (@ref{(mailcrypt)}).@refill
407
408 If you want to use this feature, please set @code{pgp-elkins} or
409 @code{pgp-kazu} to variable @code{mimed-editor/signing-type} and
410 variable @code{mime-editor/encrypting-type}.@refill
411
412 If @code{pgp-elkins} is specified, PGP/MIME is used.  If
413 @code{pgp-kazu} is specified, PGP-kazu is used.
414
415
416 @defvar mime-editor/signing-type
417
418 Format of PGP signature.@refill
419
420 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
421
422 Default value is @code{nil}.
423 @end defvar
424
425
426 @defvar mime-editor/encrypting-type
427
428 Format of PGP encryption.@refill
429
430 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
431
432 Default value is @code{nil}.
433 @end defvar
434
435
436
437 @node Concept Index, Function Index, PGP, Top
438 @chapter Concept Index
439
440 @printindex cp
441
442 @node Function Index, Variable Index, Concept Index, Top
443 @chapter Function Index
444
445 @printindex fn
446
447 @node Variable Index,  , Function Index, Top
448 @chapter Variable Index
449
450 @printindex vr
451 @bye