doc/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 @titlepage
   5 @title tm-edit 7.100 Reference Manual (English Version)
   6 @author MORIOKA Tomohiko <morioka@@jaist.ac.jp>
   7 @subtitle 1996/12/25
   8 @end titlepage
   9 @node Top, Introduction, (dir), (dir)
  10 @top tm-edit 7.100 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 * tag specification for inserted file::  Default media-type or encoding for inserted file
  24 * transfer level::
  25 * header::                      Using non-ASCII characters in header
  26 * PGP::
  27 * Acknowledgments::
  28 * Concept Index::
  29 * Function Index::
  30 * Variable Index::
  31 @end menu
  32
  33 @node Introduction, mime/editor-mode, Top, Top
  34 @chapter What is tm-edit?
  35 @cindex tm-edit
  36
  37 @strong{tm-edit} is a general MIME composer for GNU Emacs.@refill
  38
  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}:
  42
  43 @itemize @bullet
  44 @item
  45 based on RFC 1521/1522
  46 @item
  47 Content-Disposition field (@ref{(tm-en)Content-Disposition}) (RFC 1806)
  48 supports
  49 @item
  50 nested multi-part message (@ref{(tm-en)multipart})
  51 @item
  52 PGP (@ref{PGP}) (PGP/MIME (RFC 2015) based on security multipart (RFC
  53 1847) and application/pgp based on traditional PGP)
  54 @item
  55 strength automatic specification for parameter of file type
  56 @end itemize
  57
  58
  59 In tm-MUA (@ref{(tm-en)tm-MUA}), you can edit MIME message easily to use
  60 tm-edit.
  61
  62
  63 @node mime/editor-mode, single-part operations, Introduction, Top
  64 @chapter mime/editor-mode
  65 @cindex enclosure
  66 @cindex multi-part ending tag
  67 @cindex multi-part beginning tag
  68 @cindex tag
  69 @cindex mime/editor-mode
  70
  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
  74
  75 There are 2 kinds of tags:
  76
  77 @itemize @bullet
  78 @item
  79  single-part tag
  80 @item
  81  multi-part tag
  82 @end itemize
  83
  84 single-part tag represents single part, this form is following:
  85
  86 @example
  87         --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
  88         OPTIONAL-FIELDS]
  89 @end example
  90
  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
  94
  95 ENCODING indicates Content-Transfer-Encoding field.  It is optional
  96 too.@refill
  97
  98 OPTIONAL-FIELDS is to represent another fields except Content-Type field
  99 and Content-Transfer-Encoding field.@refill
 100
 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
 104
 105 multi-part beginning tag's form is following:@refill
 106
 107 @example
 108         --<<TYPE>>-@{
 109 @end example
 110
 111 multi-part ending tag's form is following:@refill
 112
 113 @example
 114         --@}-<<TYPE>>
 115 @end example
 116
 117 A region from multi-part beginning tag to multi-part ending tag is
 118 called as @strong{enclosure}.
 119
 120
 121 @node single-part operations, enclosure operation, mime/editor-mode, Top
 122 @chapter single-part operations
 123
 124 Operations to make single-part are following:
 125
 126 @table @kbd
 127 @item @key{C-c C-x C-t}
 128 Insert single-part tag indicates text part.
 129
 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})
 134
 135 @item @key{C-c C-x C-e}
 136 Insert external part.
 137
 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.)
 141
 142 @item @key{C-c C-x C-y}
 143 Insert current (mail or news) message. (It is MUA depended.)
 144
 145 @item @key{C-c C-x C-m}
 146 Insert mail message. (It is MUA depended.)
 147
 148 @item @key{C-c C-x C-w}, @key{C-c C-x C-s}
 149 Insert signature.
 150
 151 @item @key{C-c C-x C-k}
 152 Insert PGP (@ref{PGP}) public key. (It requires Mailcrypt package.)
 153
 154 @item @key{C-c C-x t}
 155 Insert any single-part tag.
 156
 157 @end table
 158
 159
 160
 161 @node enclosure operation, other operations of mime/editor-mode, single-part operations, Top
 162 @chapter enclosure operation
 163
 164 Operations to make enclosure are following:
 165
 166 @table @kbd
 167 @item @key{C-c C-x a}
 168 Enclose specified region as multipart/alternative.
 169
 170 @item @key{C-c C-x p}
 171 Enclose specified region as multipart/parallel.
 172
 173 @item @key{C-c C-x m}
 174 Enclose specified region as multipart/mixed.
 175
 176 @item @key{C-c C-x d}
 177 Enclose specified region as multipart/digest.
 178
 179 @item @key{C-c C-x s}
 180 Digital-sign to specified region. (cf. @ref{PGP})
 181
 182 @item @key{C-c C-x e}
 183 Encrypt to specified region. (cf. @ref{PGP})
 184
 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.)
 189
 190 @end table
 191
 192
 193
 194 @node other operations of mime/editor-mode, tag specification for inserted file, enclosure operation, Top
 195 @chapter other operations of mime/editor-mode
 196
 197 There are another operations in mime/editor-mode.
 198
 199 @table @kbd
 200 @item @key{C-c C-c}
 201 Send current editing message.
 202
 203 @item @key{C-c C-x C-p}
 204 Preview current editing message. (@ref{(tm-view-en)mime/viewer-mode})
 205
 206 @item @key{C-c C-x C-z}
 207 Exit mime/editor-mode. (@key{M-x mime/edit-again} is available to
 208 reedit.)
 209
 210 @item @key{C-c C-x ?}
 211 Display help message.
 212
 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.
 216
 217 @item @key{C-c C-x 7}
 218 Set 7bit (@ref{(tm-en)7bit}) to transfer level (@ref{transfer level}).
 219
 220 @item @key{C-c C-x 8}
 221 Set 8bit (@ref{(tm-en)8bit}) to transfer level (@ref{transfer level}).
 222
 223 @item @key{C-c C-x v}
 224 Set current editing message to digital-sign or not. (cf. @ref{PGP})
 225
 226 @item @key{C-c C-x h}
 227 Set current editing message to encrypt or not. (cf. @ref{PGP})
 228
 229 @end table
 230
 231
 232
 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
 235
 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
 239
 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
 243
 244 If you want to change default value for file names, please change
 245 variable @code{mime-file-types}.
 246
 247
 248 @defvar mime-file-types
 249
 250 Specification of default value of tag for file name of inserted
 251 file.@refill
 252
 253 It is a list of following list:
 254
 255 @lisp
 256         (FILE_PAT TYPE SUBTYPE PARAMS ENCODING
 257          DISPOSITION_TYPE DISPOSITION_PARAMS)
 258 @end lisp
 259
 260
 261 Each elements of the list are following:
 262
 263 @table @samp
 264 @item FILE_PAT
 265 regular expression of file name
 266
 267 @item TYPE
 268 media type
 269
 270 @item SUBTYPE
 271 media subtype
 272
 273 @item PARAMS
 274 parameters of Content-Type field
 275
 276 @item ENCODING
 277 Content-Transfer-Encoding
 278
 279 @item DISPOSITION_TYPE
 280 disposition-type
 281
 282 @item DISPOSITION_PARAMS
 283 parameters of Content-Disposition field
 284
 285 @end table
 286
 287 @noindent
 288 Example: Specify application/rtf as default media type for
 289 @file{*.rtf}
 290
 291 @lisp
 292 (call-after-loaded
 293  'tm-edit
 294  (lambda ()
 295    (set-alist 'mime-file-types
 296               "\\.rtf$"
 297               '("application" "rtf" nil nil
 298                 "attachment" (("filename" . file)))
 299               )))
 300 @end lisp
 301 @end defvar
 302
 303
 304
 305 @node transfer level, header, tag specification for inserted file, Top
 306 @chapter transfer level
 307 @cindex transfer level
 308
 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
 312
 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
 315 to 7bit data.@refill
 316
 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
 320
 321 @noindent
 322 @strong{[Memo]}
 323 @quotation
 324 EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
 325 encoded by base64.  But I don't know EBCDIC. (^_^;
 326
 327 Similarly, I wish ASCII-printable only MTA and code-conversion MTA
 328 disappeared. (^_^;@refill
 329
 330 Maybe there are binary-through MTA, but I think it is not major.
 331 @end quotation
 332
 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.
 336
 337
 338 @defvar mime-editor/transfer-level
 339
 340 transfer level.@refill
 341
 342 If transfer level of a data is over it, a data is encoded to
 343 7bit.@refill
 344
 345 Currently, 7 or 8 is available.  Default value is 7.@refill
 346
 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.
 349 @end defvar
 350
 351
 352
 353 @noindent
 354 @strong{[Memo]}
 355 @quotation
 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.
 359 @end quotation
 360
 361
 362
 363 @node header, PGP, transfer level, Top
 364 @chapter Using non-ASCII characters in header
 365 @cindex encoded-word
 366
 367 RFC 1522 (@ref{(tm-en)RFC 1522}) defines representation of non-ASCII
 368 characters in header.@refill
 369
 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}).
 374
 375
 376 @menu
 377 * evil setting in header::      If you can not allow encoded-word
 378 * API about header::            Functions and variables about header
 379 @end menu
 380
 381 @node evil setting in header, API about header, header, header
 382 @section If you can not allow encoded-word
 383
 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
 388 declared.@refill
 389
 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
 392 declared.@refill
 393
 394 However you can not permit to use encoded-word, please set to
 395 following variables:
 396
 397
 398 @defvar mime/field-encoding-method-alist
 399
 400 Association-list to specify field encoding method.  Its key is
 401 field-name, value is encoding method.@refill
 402
 403 field-name allows string or @code{t} meaning any fields.@refill
 404
 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
 409
 410 field-name is searched from string.  If it is not found, @code{t} is
 411 used.@refill
 412
 413 Default value of @code{mime/field-encoding-method-alist} is
 414 following:
 415
 416 @lisp
 417 (("X-Nsubject" . iso-2022-jp-2)
 418  ("Newsgroups" . nil)
 419  (t            . mime)
 420  ))
 421 @end lisp
 422 @end defvar
 423
 424
 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})
 428
 429
 430
 431 @node API about header,  , evil setting in header, header
 432 @section Functions and variables about header
 433
 434 @deffn{Command} mime/encode-message-header &optional  code-conversion
 435
 436 It translate non-ASCII characters in message header of current buffer
 437 into network representation, such as encoded-words.@refill
 438
 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}.
 441 @end deffn
 442
 443
 444 @defun mime/encode-field string
 445
 446 It encodes @var{string} into encoded-words as a field.@refill
 447
 448 Long lines are folded.
 449 @end defun
 450
 451
 452 @defun mime-eword/encode-string string  &optional  column mode
 453
 454 It encodes @var{string} into encoded-words.@refill
 455
 456 Long lines are folded.@refill
 457
 458 @var{column} specifies start column.  If it is omitted, 0 is
 459 used.@refill
 460
 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.
 464 @end defun
 465
 466
 467 @defvar mime-eword/charset-encoding-alist
 468
 469 Association-list of symbol represent MIME charset vs. nil, @code{"B"} or
 470 @code{"Q"}.@refill
 471
 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.
 474 @end defvar
 475
 476
 477
 478 @node PGP, Acknowledgments, header, Top
 479 @chapter PGP
 480 @cindex PGP-kazu
 481 @cindex PGP/MIME
 482
 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
 487
 488 This feature requires pgp command and Mailcrypt package
 489 (@ref{(mailcrypt)}).@refill
 490
 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
 494
 495 If @code{pgp-elkins} is specified, PGP/MIME is used.  If
 496 @code{pgp-kazu} is specified, PGP-kazu is used.
 497
 498
 499 @defvar mime-editor/signing-type
 500
 501 Format of PGP signature.@refill
 502
 503 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
 504
 505 Default value is @code{nil}.
 506 @end defvar
 507
 508
 509 @defvar mime-editor/encrypting-type
 510
 511 Format of PGP encryption.@refill
 512
 513 It allows @code{pgp-elkins} or @code{pgp-kazu}.@refill
 514
 515 Default value is @code{nil}.
 516 @end defvar
 517
 518
 519
 520 @node Acknowledgments, Concept Index, PGP, Top
 521 @chapter Acknowledgments
 522
 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
 525 tm-edit.@refill
 526
 527 I thank members of two tm mailing lists, Japanese and English version.
 528
 529
 530 @node Concept Index, Function Index, Acknowledgments, Top
 531 @chapter Concept Index
 532
 533 @printindex cp
 534
 535 @node Function Index, Variable Index, Concept Index, Top
 536 @chapter Function Index
 537
 538 @printindex fn
 539
 540 @node Variable Index,  , Function Index, Top
 541 @chapter Variable Index
 542
 543 @printindex vr
 544 @bye