doc/tm-edit-en.sgml

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