doc/tm-edit-en.texi

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