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