cgit.sxemacs.org Git - packages/blob - xemacs-packages/tm/texi/tm-edit-en.texi

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