tm / texi / tm-edit-en.texi

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

@ifinfo

This file documents tm-edit, a MIME composer for GNU Emacs.
@end ifinfo

@menu
* Introduction::                What is tm-edit?
* mime/editor-mode::            
* single-part operations::      
* enclosure operation::         
* other operations of mime/editor-mode::  
* tag specification for inserted file::  Default media-type or encoding for inserted file
* transfer level::              
* header::                      Using non-ASCII characters in header
* PGP::                         
* Acknowledgments::             
* Concept Index::               
* Function Index::              
* Variable Index::              
@end menu

@node Introduction, mime/editor-mode, Top, Top
@chapter What is tm-edit?
@cindex tm-edit

@strong{tm-edit} is a general MIME composer for GNU Emacs.@refill

tm-edit is based on mime.el by UMEDA Masanobu
<umerin@@mse.kyutech.ac.jp>, who is famous as the author of
GNUS.  tm-edit expands following points from @file{mime.el}:

@itemize @bullet
@item
based on RFC 1521/1522
@item
Content-Disposition field (@ref{(tm-en)Content-Disposition}) (RFC 1806)
supports
@item
nested multi-part message (@ref{(tm-en)multipart})
@item
PGP (@ref{PGP}) (PGP/MIME (RFC 2015) based on security multipart (RFC
1847) and application/pgp based on traditional PGP)
@item
strength automatic specification for parameter of file type
@end itemize


In tm-MUA (@ref{(tm-en)tm-MUA}), you can edit MIME message easily to use
tm-edit.


@node mime/editor-mode, single-part operations, Introduction, Top
@chapter mime/editor-mode
@cindex enclosure
@cindex multi-part ending tag
@cindex multi-part beginning tag
@cindex tag
@cindex mime/editor-mode

@strong{mime/editor-mode} is a minor mode to compose MIME message.  In
this mode, @strong{tag} represents various kinds of data, you can edit
multi part (@ref{(tm-en)multipart}) message.@refill

There are 2 kinds of tags:

@itemize @bullet
@item
 single-part tag
@item
 multi-part tag
@end itemize

single-part tag represents single part, this form is following:

@example
        --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
        OPTIONAL-FIELDS]
@end example

TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
Content-Type field (@ref{(tm-en)Content-Type field}).  TYPE/SUBTYPE is
required, PARAMETERS is optional.@refill

ENCODING indicates Content-Transfer-Encoding field.  It is optional
too.@refill

OPTIONAL-FIELDS is to represent another fields except Content-Type field
and Content-Transfer-Encoding field.@refill

multi-part tags represent multi part (@ref{(tm-en)multipart}).  They
consist of a pair of @strong{multi-part beginning tag} and
@strong{multi-part ending tag}.@refill

multi-part beginning tag's form is following:@refill

@example
        --<<TYPE>>-@{
@end example

multi-part ending tag's form is following:@refill

@example
        --@}-<<TYPE>>
@end example

A region from multi-part beginning tag to multi-part ending tag is
called as @strong{enclosure}.


@node single-part operations, enclosure operation, mime/editor-mode, Top
@chapter single-part operations

Operations to make single-part are following:

@table @kbd
@item @key{C-c C-x C-t}
Insert single-part tag indicates text part.

@item @key{C-c C-x C-i}
Insert file as a MIME attachment.  If @kbd{C-u} is followed by it, it
asks media-type, subtype or encoding even if their default values are
specified. (cf. @ref{tag specification for inserted file})

@item @key{C-c C-x C-e}
Insert external part.

@item @key{C-c C-x C-v}
Record audio input until @kbd{C-g} is pressed, and insert as a
audio part. (It requires /dev/audio in default.)

@item @key{C-c C-x C-y}
Insert current (mail or news) message. (It is MUA depended.)

@item @key{C-c C-x C-m}
Insert mail message. (It is MUA depended.)

@item @key{C-c C-x C-w}, @key{C-c C-x C-s}
Insert signature.

@item @key{C-c C-x C-k}
Insert PGP (@ref{PGP}) public key. (It requires Mailcrypt package.)

@item @key{C-c C-x t}
Insert any single-part tag.

@end table



@node enclosure operation, other operations of mime/editor-mode, single-part operations, Top
@chapter enclosure operation

Operations to make enclosure are following:

@table @kbd
@item @key{C-c C-x a}
Enclose specified region as multipart/alternative.

@item @key{C-c C-x p}
Enclose specified region as multipart/parallel.

@item @key{C-c C-x m}
Enclose specified region as multipart/mixed.

@item @key{C-c C-x d}
Enclose specified region as multipart/digest.

@item @key{C-c C-x s}
Digital-sign to specified region. (cf. @ref{PGP})

@item @key{C-c C-x e}
Encrypt to specified region. (cf. @ref{PGP})

@item @key{C-c C-x q}
avoid to encode tags in specified region.  In other words, tags is
interpreted as such string.  (In current version, it may be
incomplete.  Maybe PGP-signature does not work for this enclosure.)

@end table



@node other operations of mime/editor-mode, tag specification for inserted file, enclosure operation, Top
@chapter other operations of mime/editor-mode

There are another operations in mime/editor-mode.

@table @kbd
@item @key{C-c C-c}
Send current editing message.

@item @key{C-c C-x C-p}
Preview current editing message. (@ref{(tm-view-en)mime/viewer-mode})

@item @key{C-c C-x C-z}
Exit mime/editor-mode. (@key{M-x mime/edit-again} is available to
reedit.)

@item @key{C-c C-x ?}
Display help message.

@item @key{C-c C-x /}
Set current editing message to enable automatic splitting or not.
Form of automatic split messages is message/partial.

@item @key{C-c C-x 7}
Set 7bit (@ref{(tm-en)7bit}) to transfer level (@ref{transfer level}).

@item @key{C-c C-x 8}
Set 8bit (@ref{(tm-en)8bit}) to transfer level (@ref{transfer level}).

@item @key{C-c C-x v}
Set current editing message to digital-sign or not. (cf. @ref{PGP})

@item @key{C-c C-x h}
Set current editing message to encrypt or not. (cf. @ref{PGP})

@end table



@node tag specification for inserted file, transfer level, other operations of mime/editor-mode, Top
@chapter Default media-type or encoding for inserted file

When @kbd{C-c C-x C-i} (@code{mime-editor/insert-file}) is pressed, tag
parameters for inserted file, such as media-type or encoding, are
detected by variable @code{mime-file-types}.@refill

When @kbd{C-u} is followed by it or parameter is not found from the
variable, it asks from user.  (When @kbd{C-u} is followed by it,
detected value is used as default value)@refill

If you want to change default value for file names, please change
variable @code{mime-file-types}.


@defvar mime-file-types

Specification of default value of tag for file name of inserted
file.@refill

It is a list of following list:

@lisp
	(FILE_PAT TYPE SUBTYPE PARAMS ENCODING
	 DISPOSITION_TYPE DISPOSITION_PARAMS)
@end lisp


Each elements of the list are following:

@table @samp
@item FILE_PAT
regular expression of file name

@item TYPE
media type

@item SUBTYPE
media subtype

@item PARAMS
parameters of Content-Type field

@item ENCODING
Content-Transfer-Encoding

@item DISPOSITION_TYPE
disposition-type

@item DISPOSITION_PARAMS
parameters of Content-Disposition field

@end table

@noindent
Example: Specify application/rtf as default media type for
@file{*.rtf}

@lisp
(call-after-loaded
 'tm-edit
 (lambda ()
   (set-alist 'mime-file-types
	      "\\.rtf$"
	      '("application" "rtf" nil nil
		"attachment" (("filename" . file)))
	      )))
@end lisp
@end defvar



@node transfer level, header, tag specification for inserted file, Top
@chapter transfer level
@cindex transfer level

Contents inserted in a message are represented by 7bit
(@ref{(tm-en)7bit}), 8bit (@ref{(tm-en)8bit}) or binary
(@ref{(tm-en)binary}).@refill

If a message is translated by 7bit-through MTA (@ref{(tm-en)MTA}), there
is no need to encode 7bit data, but 8bit and binary data must be encoded
to 7bit data.@refill

Similarly, if a message is translated by 8bit-through MTA, there is no
need to encode 7bit or 8bit data, but binary data must be encoded to
7bit or 8bit data.@refill

@noindent
@strong{[Memo]}
@quotation
EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
encoded by base64.  But I don't know EBCDIC. (^_^;

Similarly, I wish ASCII-printable only MTA and code-conversion MTA
disappeared. (^_^;@refill

Maybe there are binary-through MTA, but I think it is not major.
@end quotation

@strong{transfer level} represents how range data is
available.  tm-edit has a variable
@code{mime-editor/transfer-level} to represent transfer level.


@defvar mime-editor/transfer-level

transfer level.@refill

If transfer level of a data is over it, a data is encoded to
7bit.@refill

Currently, 7 or 8 is available.  Default value is 7.@refill

In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
binary will be 9.  But it will not be implemented.
@end defvar



@noindent
@strong{[Memo]}
@quotation
transfer level is only for body, not for header (@ref{header}).  RFC
1521 extends RFC 822 (@ref{(tm-en)RFC 822}) to use 8bit data in body,
but it requires to use us-ascii (@ref{(tm-en)us-ascii}) in header.
@end quotation



@node header, PGP, transfer level, Top
@chapter Using non-ASCII characters in header
@cindex encoded-word

RFC 1522 (@ref{(tm-en)RFC 1522}) defines representation of non-ASCII
characters in header.@refill

It is a format called as @strong{encoded-word}
(@ref{(tm-en)encoded-word}), it is available to represent every
non-ASCII characters by 7bit (@ref{(tm-en)7bit}) to declare MIME charset
(@ref{(tm-en)MIME charset}).


@menu
* evil setting in header::      If you can not allow encoded-word
* API about header::            Functions and variables about header
@end menu

@node evil setting in header, API about header, header, header
@section If you can not allow encoded-word

It is wrong to use ``raw'' non-ASCII characters in header not to use
encoded-word.  Because there are various kinds of coded character set
(@ref{(tm-en)Coded character set}) in the Internet, so we can not
distinguish them if MIME charset (@ref{(tm-en)MIME charset}) is not
declared.@refill

For example, we can not distinguish iso-8859-1 (@ref{(tm-en)iso-8859-1})
and iso-8859-2 (@ref{(tm-en)iso-8859-2}) if MIME charset is not
declared.@refill

However you can not permit to use encoded-word, please set to
following variables:


@defvar mime/field-encoding-method-alist

Association-list to specify field encoding method.  Its key is
field-name, value is encoding method.@refill

field-name allows string or @code{t} meaning any fields.@refill

Encoding method allows following: @code{nil} means no-conversion,
@code{mime} means to convert as encoded-word, symbol represent MIME
charset means to convert as the coded character set instead of to
convert as encoded-word.@refill

field-name is searched from string.  If it is not found, @code{t} is
used.@refill

Default value of @code{mime/field-encoding-method-alist} is
following:

@lisp
(("X-Nsubject" . iso-2022-jp-2)
 ("Newsgroups" . nil)
 (t            . mime)
 ))
@end lisp
@end defvar


In addition, if you want to specify by coded character set instead of
field, please use @code{mime-eword/charset-encoding-alist}.
(cf. @ref{API about header})



@node API about header,  , evil setting in header, header
@section Functions and variables about header

@deffn{Command} mime/encode-message-header &optional  code-conversion

It translate non-ASCII characters in message header of current buffer
into network representation, such as encoded-words.@refill

If @var{code-conversion} is non-@code{nil}, field not encoded by
encoded-word is converted by @code{mime/field-encoding-method-alist}.
@end deffn


@defun mime/encode-field string

It encodes @var{string} into encoded-words as a field.@refill

Long lines are folded.
@end defun


@defun mime-eword/encode-string string  &optional  column mode

It encodes @var{string} into encoded-words.@refill

Long lines are folded.@refill

@var{column} specifies start column.  If it is omitted, 0 is
used.@refill

@var{mode} specifies where @var{string} is in.  Available values are
@code{text}, @code{comment}, @code{phrase}.  If it is omitted,
@code{phrase} is used.
@end defun


@defvar mime-eword/charset-encoding-alist

Association-list of symbol represent MIME charset vs. nil, @code{"B"} or
@code{"Q"}.@refill

@code{nil} means not to encode as encoded-word.  @code{"B"} means to use
B-encoding.  @code{"Q"} means to use Q-encoding.
@end defvar



@node PGP, Acknowledgments, header, Top
@chapter PGP
@cindex PGP-kazu
@cindex PGP/MIME

tm-edit provides PGP encryption, signature and inserting public-key
features based on @strong{PGP/MIME} (@ref{(tm-en)PGP/MIME}) (RFC 2015)
or @strong{PGP-kazu} (@ref{(tm-en)PGP-kazu})
(draft-kazu-pgp-mime-00.txt).@refill

This feature requires pgp command and Mailcrypt package
(@ref{(mailcrypt)}).@refill

If you want to use this feature, please set @code{pgp-elkins} or
@code{pgp-kazu} to variable @code{mimed-editor/signing-type} and
variable @code{mime-editor/encrypting-type}.@refill

If @code{pgp-elkins} is specified, PGP/MIME is used.  If
@code{pgp-kazu} is specified, PGP-kazu is used.


@defvar mime-editor/signing-type

Format of PGP signature.@refill

It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill

Default value is @code{nil}.
@end defvar


@defvar mime-editor/encrypting-type

Format of PGP encryption.@refill

It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill

Default value is @code{nil}.
@end defvar



@node Acknowledgments, Concept Index, PGP, Top
@chapter Acknowledgments

First of all, I thank UMEDA Masanobu for his work of @file{mime.el},
which is the origin of tm-edit, and permission to rewrite his work as
tm-edit.@refill

I thank members of two tm mailing lists, Japanese and English version.


@node Concept Index, Function Index, Acknowledgments, Top
@chapter Concept Index

@printindex cp

@node Function Index, Variable Index, Concept Index, Top
@chapter Function Index

@printindex fn

@node Variable Index,  , Function Index, Top
@chapter Variable Index

@printindex vr
@bye
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.