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

   1 <!doctype sinfo system>
   2 <!-- $Id: tm-view-en.sgml,v 1.1.1.1 1998-01-14 06:27:58 steve Exp $ -->
   3 <head>
   4 <title>tm-view 7.80 Reference Manual (English Version)
   5 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
   6 <date>1997/1/31
   7
   8 <toc>
   9 </head>
  10
  11 <body>
  12
  13 <abstract>
  14 <p>
  15 This file documents tm-view, a MIME Viewer for GNU Emacs.
  16 </abstract>
  17
  18
  19 <h1> What is tm-view?
  20 <node> Introduction
  21 <p>
  22 The tm-view is a general MIME viewer running on GNU Emacs.
  23 <p>
  24 tm-view provides the major-mode called <a
  25 node="mime/viewer-mode"><code>mime/viewer-mode</code> </a> to read
  26 MIME message for MUA.  <a file="tm-en" node="MUA">MUA</a> implementer
  27 can use it to add MIME function.
  28 <p>
  29 tm-view is a user interface kernel to view and navigate MIME message.
  30 tm-view drives some programs to navigate each <dref
  31 file="tm-en">content-type</dref>s, they are called <a
  32 node="method"><concept>method</concept></a>.  tm-view calls some
  33 programs to display each contents and headers in preview buffer, they
  34 are called <a node="Two buffers for an
  35 article"><concept>filter</concept></a>.  Method and filters are
  36 tm-view application program.  They expand tm-view to treat various
  37 kinds of MIME types.
  38
  39
  40 <h1> Structure of display in mime/viewer-mode
  41 <node> MIME display
  42 <p>
  43 In <a node="mime/viewer-mode">mime/viewer-mode</a>, following are
  44 displayed for each parts:
  45 <p>
  46 <verb>
  47         [content-button]
  48         (content-header)
  49
  50         (content-body)
  51         (content-separator)
  52 </verb>
  53 <p>
  54 You can change design or stop to display if you specify for each
  55 conditions, such as content-types.
  56 <p>
  57 Example:
  58
  59 <verb>
  60 From: morioka@jaist.ac.jp (MORIOKA Tomohiko)
  61 Subject: Re: Question
  62 Newsgroups: zxr.message.mime
  63 Date: 22 Oct 93 11:02:44
  64 Mime-Version: 1.0
  65 Organization: Japan Advanced Institute of Science and Technology,
  66         Ishikawa, Japan
  67
  68 [1  (text/plain)]
  69   How to compose MIME message in MIME-Edit mode.
  70
  71   Press `C-c C-x ?' then help message will be displayed:
  72
  73 C-c C-x C-t     insert a text message.
  74 C-c C-x TAB     insert a (binary) file.
  75 C-c C-x C-e     insert a reference to external body.
  76 C-c C-x C-v     insert a voice message.
  77 C-c C-x C-y     insert a mail or news message.
  78 C-c C-x RET     insert a mail message.
  79 C-c C-x C-s     insert a signature file at end.
  80 C-c C-x t       insert a new MIME tag.
  81 C-c C-x a       enclose as multipart/alternative.
  82 C-c C-x p       enclose as multipart/parallel.
  83 C-c C-x m       enclose as multipart/mixed.
  84 C-c C-x d       enclose as multipart/digest.
  85 C-c C-x s       enclose as PGP signed.
  86 C-c C-x e       enclose as PGP encrypted.
  87 C-c C-x C-k     insert PGP public key.
  88 C-c C-x C-p     preview editing MIME message.
  89 ...
  90
  91 So press `C-c C-x C-i' and specify file name you want to include.
  92
  93   MIME encoding for binary file is normally Base64.
  94
  95 [2  (image/gif)]
  96
  97 [3  (text/plain)]
  98
  99   In this way, it is finish a message attaching a picture.
 100
 101 ======================== A cup of Russian tea ========================
 102 ============  * not by jam, not by marmalade, by honey *  ============
 103 ============               MORIOKA Tomohiko               ============
 104 =============== Internet E-mail: <morioka@jaist.ac.jp> ===============
 105 </verb>
 106
 107
 108 <h2> content-button
 109 <node> content-button
 110 <p>
 111 content-subject displays abstract for the part.  It is placed in top
 112 of the part.
 113 <p>
 114 In default, it is displayed following design:
 115
 116 <verb>
 117         [1.3 test (text/plain)]
 118 </verb>
 119
 120 <p>
 121 First number field represents position of a content in the part.  It
 122 is called <concept>content-number</concept>.  It can be considered as
 123 the chapter number in the message.
 124 <p>
 125 Second string part represents title.  It is created by following:
 126
 127 <ol>
 128 <li>name paramater or x-name parameter in <dref
 129 file="tm-en">Content-Type field</dref>
 130 </li>
 131 <li><dref file="tm-en">Content-Description field</dref> or Subject
 132 field
 133 </li>
 134 <li> filename of uuencode
 135 </ol>
 136
 137 <p>
 138 If they are not exists, space is displayed.
 139 <p>
 140 Third parenthesis part represents content-type/subtype of the part.
 141 If it is non-MIME part, <code>nil</code> is displayed.
 142 <p>
 143 Content-button is used like icon when <dref>content-header</dref> and
 144 <dref>content-body</dref> are hidden.  For example:
 145
 146 <verb>
 147         [2  (image/gif)]
 148 </verb>
 149
 150 <noindent>
 151 if you press <kbd>v</kbd> key, GIF image is displayed.
 152 <p>
 153 If mouse operations are available, you can press content-button by
 154 mouse button-2 (center button of 3 button-mouse) to play, similarly to
 155 press <kbd>v</kbd> key. <cf node="mime/viewer-mode">
 156 <p>
 157 By the way, it is annoying to display content-button if content-header
 158 is displayed.  So tm-view provides a mechanism to specify conditions
 159 to display content-button.
 160
 161
 162 <defvar name="mime-viewer/content-button-ignored-ctype-list">
 163 <p>
 164 List of content-types.
 165 <p>
 166 If content-type of a part is a member of this list, its content-button
 167 is not displayed.
 168 </defvar>
 169
 170
 171 <h2> content-header
 172 <node> content-header
 173 <p>
 174 A content header displays the header portion of a part in the
 175 preview-buffer.  However it is annoying to display header for every
 176 parts, so tm-view provides a mechanism to specify its condition.
 177 <p>
 178 When the function <code>mime-viewer/header-visible-p</code> returns
 179 <code>t</code> for reversed-content-number of a part, content-header
 180 is displayed.
 181 <p>
 182 This judge function returns <code>t</code> when a part is root or
 183 content-type of its parent is a member of the variable
 184 <code>mime-viewer/childrens-header-showing-Content-Type-list</code>.
 185 <p>
 186 If you want to change this condition, please redefine it.  Notice that
 187 it refers variable
 188 <code>mime-viewer/childrens-header-showing-Content-Type-list</code>,
 189 however if you redefine function
 190 <code>mime-viewer/header-visible-p</code>, it may not work.  So if you
 191 want to redefine it, it should be refer variable
 192 <code>mime-viewer/childrens-header-showing-Content-Type-list</code>.
 193 <p>
 194 When content-header is displayed, content-header are formated by the
 195 program called by <concept>content-header-filter</concept>.
 196 Content-header-filter is searched from variable
 197 <code>mime-viewer/content-header-filter-alist</code>.  Its key is
 198 major-mode of the <a node="raw-article-buffer">raw-article-buffer</a>.
 199 If not found, function
 200 <code>mime-viewer/default-content-header-filter</code> is called.
 201 <p>
 202
 203 <defvar name="mime-viewer/childrens-header-showing-Content-Type-list">
 204 <p>
 205 List of content-types.  If content-type of parent of a part is a
 206 member of this variable, its content-header is displayed.  Default
 207 value is <code>'("message/rfc822" "message/news")</code>.
 208 <p>
 209 This variable is referred by the function
 210 <code>mime-viewer/header-visible-p</code>.
 211 </defvar>
 212
 213
 214 <defun name="mime-viewer/header-visible-p">
 215 <args> rcnum cinfo <opts> ctype
 216 <p>
 217 Returns <code>t</code> if a part which reversed-content-number is
 218 <var>rcnum</var> in content-info <var>cinfo</var> is displayed.
 219 <p>
 220 If you know content-type, you can specify by <var>ctype</var>.
 221 </defun>
 222
 223
 224 <defvar name="mime-viewer/content-header-filter-alist">
 225 <p>
 226 Association-list whose key is major-mode of a raw-article-buffer,
 227 value is content-header-filter.
 228 </defvar>
 229
 230
 231 <defun name="mime-viewer/default-content-header-filter">
 232 <p>
 233 It is called when content-header-filter is not found in variable
 234 <code>mime-viewer/content-header-filter-alist</code>.
 235 <p>
 236 It refers <code>mime-viewer/ignored-field-regexp</code>.
 237 </defun>
 238
 239
 240 <defvar name="mime-viewer/ignored-field-list">
 241 <p>
 242 List of regular expression to represent invisible fields even if
 243 content-header is displayed.
 244 <p>
 245 Variable <code>mime-viewer/ignored-field-regexp</code> is created from
 246 it.
 247 <p>
 248 Please use function <code>tm:add-fields</code> or
 249 <code>tm:delete-fields</code> to set it.
 250 </defvar>
 251
 252
 253 <h2> content-body
 254 <node> content-body
 255 <p>
 256 <concept>content-body</concept> represents content of the part.
 257 <p>
 258 tm-view does not display raw content body.  For example, if a content
 259 has binary, it is hidden.  If a content has text/enriched, it is
 260 formated.  Namely content body is hidden or formated.
 261 <p>
 262 Function <code>mime-viewer/body-visible-p</code> is a judge function
 263 whether content-body of a content is displayed.  If it returns
 264 <code>nil</code>, content-body is hidden.  In default, it returns
 265 non-<code>nil</code> when content-type of a part is a member of
 266 variable <code>mime-viewer/default-showing-Content-Type-list</code>.
 267 <p>
 268 When content-body of a content is displayed, content-body is formated
 269 by <concept>content-filter</concept>.  Content-filter is searched from
 270 variable <code>mime-viewer/content-filter-alist</code>.  At this time,
 271 major-mode of the <dref>raw-article-buffer</dref> is used as the key.
 272
 273 If it is not found, function
 274 <code>mime-viewer/default-content-filter</code> is called.
 275
 276
 277 <defvar name="mime-viewer/default-showing-Content-Type-list">
 278 <p>
 279 List of content-type.  If content-type of a part is a member of this
 280 variable, its body is displayed.
 281 </defvar>
 282
 283
 284 <defun name="mime-viewer/body-visible-p">
 285 <args> rcnum cinfo <opts> ctype
 286 <p>
 287 Return non-<code>nil</code>, if content-type of a part is displayed.
 288 <var>rcnum</var> is reversed-content-number of a part.
 289 <var>cinfo</var> is content-info of the message.  If you know
 290 content-type of a part, you can specify it as argument
 291 <var>ctype</var>.
 292 </defun>
 293
 294
 295 <defvar name="mime-viewer/content-filter-alist">
 296 <p>
 297 Association-list whose key is major-mode of a raw-article-buffer,
 298 value is content-filter.
 299 </defvar>
 300
 301
 302 <defun name="mime-viewer/default-content-filter">
 303 <args> rcnum cinfo ctype params subj
 304 <p>
 305 It is called when content-body of a part should be displayed and
 306 content-filter is not found in
 307 <code>mime-viewer/content-filter-alist</code>.
 308 <p>
 309 In default, it does nothing.
 310 </defun>
 311
 312
 313 <h2> content-separator
 314 <node> content-separator
 315 <p>
 316 <concept>content-separator</concept> is displayed to represent
 317 boundary of contents.
 318 <p>
 319 Content-separator is displayed by function
 320 <code>mime-viewer/default-content-separator</code>.  In default, it
 321 displays line-break when content-header and content-body are not
 322 displayed.
 323 <p>
 324 If you want to change this condition, please redefine this function.
 325
 326
 327 <defun name="mime-viewer/default-content-separator">
 328 <args> rcnum cinfo ctype params subj
 329 <p>
 330 Display content-separator.  <var>cnum</var> is content-number of a
 331 content.  <var>cinfo</var> is content-info of the message.
 332 <var>ctype</var> is content-type of a content.  <var>params</var> is
 333 Content-Type field parameters of a content.  <var>subj</var> is
 334 subject.
 335 <p>
 336 In default, it displays line-break when content-header and
 337 content-body are not displayed.
 338 </defun>
 339
 340
 341 <h1> Navigation in mime/viewer-mode
 342 <node> mime/viewer-mode
 343 <p>
 344 <code>mime/viewer-mode</code> has following functions:
 345 <p>
 346 <kl>
 347 <kt>u
 348 <kd>
 349 goes to the upper content (returns to the Summary mode if the cursor
 350 is sitting on the top content (*1))
 351 </kd>
 352 <kt>p
 353 <kd>
 354 goes to the previous content
 355 </kd>
 356 <kt>M-TAB
 357 <kd>
 358 goes to the previous content
 359 </kd>
 360 <kt>n
 361 <kd>
 362 goes to the next content
 363 </kd>
 364 <kt>TAB
 365 <kd>
 366 goes to the next content
 367 </kd>
 368 <kt>SPC
 369 <kd>
 370 scrolls up
 371 </kd>
 372 <kt>M-SPC
 373 <kd>
 374 scrolls down
 375 </kd>
 376 <kt>DEL
 377 <kd>
 378 scrolls down
 379 </kd>
 380 <kt>RET
 381 <kd>
 382 goes to the next line
 383 </kd>
 384 <kt>M-RET
 385 <kd>
 386 goes to the previous line
 387 </kd>
 388 <kt>&lt;
 389 <kd>
 390 goes to the beginning of message
 391 </kd>
 392 <kt>&gt;
 393 <kd>
 394 goes to the end of message
 395 </kd>
 396 <kt>v
 397 <kd>
 398 playbacks a part (*2)
 399 </kd>
 400 <kt>e
 401 <kd>
 402 extracts a file from a part (*2)
 403 </kd>
 404 <kt>C-c C-p
 405 <kd>
 406 prints a part (*2)
 407 </kd>
 408 <kt>f
 409 <kd>
 410 displays X-Face in the message
 411 </kd>
 412 <kt>mouse-button-2
 413 <kd>
 414 drives mouse button in preview-buffer.
 415 <p>
 416 For content-button, it playbacks a part (*2)
 417 <p>
 418 For URL-button, it drives WWW browser
 419 </kd>
 420 </kl>
 421 <p>
 422 <memo title="Notice">
 423 <p>
 424 (*1) Not return to the Summary mode unless tm-view has been setup
 425 using tm-mh-e, tm-vm, gnus-mime, tm-gnus, tm-rmail etc.
 426 <p>
 427 (*2) Actual playback/extract/print will be performed by a method.
 428 </memo>
 429
 430
 431 <h1> Mechanism of decoding
 432 <node> method
 433 <p>
 434 In <code>mime/viewer-mode</code>, you can do play (<kbd>v</kbd>),
 435 extract (<kbd>e</kbd>), or print (<kbd>C-c C-p</kbd>) for each parts.
 436 These operations are called <concept>decoding operation(s) (for a
 437 part)</concept>.  And kind of decoding operations are called
 438 <concept>decoding-mode</concept>.
 439 <p>
 440 When decoding operation is driven, tm-view calls a procedure matched
 441 for the condition, such as <dref file="tm-en">content-type</dref> of
 442 the part or its environment.  This procedure is called
 443 <concept>method</concept>.
 444 <p>
 445 There are two kinds of methods.  One is Emacs Lisp function, called
 446 <concept>internal method</concept>.  Another one is external program,
 447 called <concept>external method</concept>.
 448 <p>
 449 Internal method operates in Emacs, so it can do carefully.
 450 <p>
 451 External method is called as asynchronous process, so Emacs does not
 452 wait while method is running.  So it is good for big data, such as
 453 audio, image or video.
 454
 455
 456 <h2> Setting decoding condition for parts
 457 <node> decoding-condition
 458 <p>
 459 When decoding operation is driven, tm-view calls a method matched for
 460 the condition searched from the variable
 461 <code>mime/content-decoding-condition</code>.
 462 <p>
 463 Variable <code>mime/content-decoding-condition</code> is defined as a
 464 list with the following syntax:
 465 <p>
 466 <lisp>
 467         (condition_1 condition_2 ...)
 468 </lisp>
 469 <p>
 470 Each condition are association-list with the following syntax:
 471 <p>
 472 <lisp>
 473         ((field-type_1 . value_1)
 474          (field-type_2 . value_2)
 475          ...)
 476 </lisp>
 477 <p>
 478 For example, if you want to call the external method named tm-plain to
 479 decode every <dref file="tm-en">text/plain</dref> type parts, you can
 480 define the condition like:
 481 <p>
 482 <lisp>
 483         ((type . "text/plain")
 484          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
 485 </lisp>
 486 <p>
 487 This condition definition will match all parts whose <dref
 488 file="tm-en">content-type</dref> are text/plain.  Here is an another
 489 example:
 490 <p>
 491 <lisp>
 492         ((type . "text/plain")
 493          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
 494          (mode . "play"))
 495 </lisp>
 496 <p>
 497 This will match the part whose type is text/plain and the mode is
 498 play.
 499 <p>
 500 Here is an another example:
 501 <p>
 502 <lisp>
 503         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
 504          (mode . "play"))
 505 </lisp>
 506 <p>
 507 This will match all parts which have a mode of play.
 508 <p>
 509 The conditions defined in a variable
 510 <code>mime/content-decoding-condition</code> are examined from top to
 511 bottom.  The first matching condition becomes valid and the method
 512 specified in that condition definition will be executed.
 513
 514
 515 <h3> Format of method value
 516 <node> method value
 517 <p>
 518 You can specify the method field of the decoding-condition definition
 519 in two different ways,
 520 <p>
 521 <lisp>
 522         (method . SYMBOL)
 523 </lisp>
 524 <p>
 525 <noindent>
 526 or
 527 <p>
 528 <lisp>
 529         (method  STRING  FLAG  arg1  arg2  ...)
 530 </lisp>
 531 <p>
 532 <noindent>
 533 can be accepted.
 534 <p>
 535 When a symbol is specified in the method field, a function whose name
 536 is SYMBOL will be called as an internal method.
 537 <p>
 538 When a list is specified in the method field, it will be called as an
 539 external method.
 540 <p>
 541 The list below shows the meaning of the parameters when the external
 542 method is specified in the method field.
 543 <p>
 544 <dl>
 545 <dt>STRING
 546 <dd>name of an external method
 547 </dd>
 548 <dt>FLAG
 549 <dd>If <code>t</code>, both the content-header and the content-body
 550 are passed to an external method.
 551 <p>
 552 If <code>nil</code>, only the content-body is passed to an external
 553 method.
 554 </dd>
 555 <dt>ARGUMENTs
 556 <dd>list of arguments passed to an external method
 557 </dd>
 558 </dl>
 559 <p>
 560 An argument passed to an external method can be in one of the
 561 following formats:
 562 <p>
 563 <dl>
 564 <dt>STRING
 565 <dd>string itself
 566 </dd>
 567 <dt>'SYMBOL
 568 <dd>value gotten using SYMBOL as a key from decoding-condition
 569 </dd>
 570 <dt>'STRING
 571 <dd>value gotten using STRING as a key from decoding-condition
 572 </dd>
 573 </dl>
 574 <p>
 575 <code>'SYMBOL</code> can be one of the following:
 576 <p>
 577 <dl>
 578 <dt>'file
 579 <dd>name of a file holding the original content
 580 </dd>
 581 <dt>'type
 582 <dd>content-type/sub-type of Content-Type field
 583 </dd>
 584 <dt>'encoding
 585 <dd>field body of Content-Transfer-Encoding field
 586 </dd>
 587 <dt>'mode
 588 <dd>decoding-mode
 589 </dd>
 590 <dt>'name
 591 <dd>name of a file created by decode operation
 592 </dd>
 593 </dl>
 594
 595 <p>
 596 <code>'STRING</code> is used to search a parameter of the Content-Type
 597 field whose name matches with it, and pass the value of that parameter
 598 to the external method.
 599
 600
 601 <h3> Example of decoding-condition
 602 <node> Example of decoding-condition
 603 <p>
 604 Following is an example of decoding-condition:
 605
 606 <lisp>
 607 (defvar mime/content-decoding-condition
 608   '(((type . "text/plain")
 609      (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
 610     ((type . "text/x-latex")
 611      (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
 612     ((type . "audio/basic")
 613      (method "tm-au"    nil 'file 'type 'encoding 'mode 'name))
 614     ((type . "image/gif")
 615      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 616     ((type . "image/jpeg")
 617      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 618     ((type . "image/tiff")
 619      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 620     ((type . "image/x-tiff")
 621      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 622     ((type . "image/x-xbm")
 623      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 624     ((type . "image/x-pic")
 625      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 626     ((type . "video/mpeg")`
 627      (method "tm-mpeg"  nil 'file 'type 'encoding 'mode 'name))
 628     ((type . "application/octet-stream")
 629      (method "tm-file"  nil 'file 'type 'encoding 'mode 'name))
 630     ((type . "message/partial")
 631      (method . mime/decode-message/partial-region))
 632     ((method "metamail" t
 633              "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
 634     ))
 635 </lisp>
 636
 637 <p>
 638 For example, if you want to use metamail to decode any contents,
 639
 640 <lisp>
 641 (setq mime/content-decoding-condition
 642       '(
 643         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
 644        ))
 645 </lisp>
 646
 647 <noindent>
 648 will work.
 649 <p>
 650 Variable <code>mime/content-decoding-condition</code> provides you of
 651 very flexible way to define the conditions of decoding.  It can be
 652 simple if you only need the a few decoding methods, while it can be
 653 very complicated if you want to use the separate decoding method for
 654 each type/mode combination.
 655 <p>
 656 Following function may be useful to set decoding-condition.  It is a
 657 function of <file>tl-atype.el</file>.
 658
 659
 660 <defun name="set-atype">
 661 <args> symbol alist
 662 <p>
 663 Add condition <var>alist</var> to <var>symbol</var>.
 664
 665 <memo title="Example">
 666 <p>
 667 <lisp>
 668 (set-atype 'mime/content-decoding-condition
 669            '((type . "message/external-body")
 670              ("access-type" . "anon-ftp")
 671              (method . mime/decode-message/external-ftp)
 672              ))
 673 </lisp>
 674 </memo>
 675 </defun>
 676
 677
 678 <h2> Environment variables
 679 <node> environment variables
 680 <p>
 681 Standard methods of tm-view reference some environment variables.  You
 682 can specify them to customize.
 683
 684 <vl>
 685 <dt>TM_TMP_DIR
 686 <dd>
 687 Directory for temporary files or extracted files.  If it is omitted,
 688 <file>/tmp/</file> is used.
 689 </dd>
 690 <dt>VIDEO_DITHER
 691 <dd>
 692 Dither for mpeg_play.  If it is omitted, `gray' is used.
 693 </dd>
 694 <dt>TM_WWW_BROWSER
 695 <dd>
 696 WWW browser name.  If it is omitted, `netscape' is used.
 697 </vl>
 698
 699
 700 <h1> raw-article-buffer and preview-buffer
 701 <node> Two buffers for an article
 702 <p>
 703 tm-view managements two buffers, one is for raw message called
 704 <concept>raw-article-buffer</concept>, another one is to preview for
 705 user called <concept>preview-buffer</concept>.  major-mode of
 706 raw-article-buffer is same as major-mode for article of original MUA,
 707 major-mode of preview-buffer is <a
 708 node="mime/viewer-mode"><code>mime/viewer-mode</code></a>.
 709 <p>
 710 When called <code>mime/viewer-mode</code>, tm-view analyzes
 711 raw-article-buffer, and sets its result to the variable
 712 <code>mime::article/content-info</code>.
 713 <p>
 714 After that, tm-view create a preview-buffer corresponded to the
 715 raw-article-buffer.  As this time, tm-view modifies header and body of
 716 each parts of the message by specified conditions.  Filter program for
 717 header is called <a
 718 node="content-header"><concept>header-filter</concept></a>, filter
 719 program for body is called <a
 720 node="content-body"><concept>content-filter</concept></a>, and they
 721 are called <concept>filter</concept>.
 722 <p>
 723 When preview-buffer is made, buffer local variable of preview-buffer
 724 <code>mime::preview/content-list</code> is made to register structure
 725 of preview-buffer.  tm-view manages message by
 726 <code>mime::article/content-info</code> in raw-article-buffer and
 727 <code>mime::preview/content-list</code> in preview-buffer.
 728 <p>
 729 <memo title="Notice">
 730 In this document, I call ``content-type'' as content-type/subtype of
 731 Content-Type field.
 732 </memo>
 733
 734
 735 <h2> buffer local variables of raw-article-buffer
 736 <node> raw-article-buffer
 737 <p>
 738 <define type="Structure" name="mime::content-info">
 739 <args> rcnum point-min point-max type parameters encoding children
 740 <p>
 741 structure to represent MIME content in raw-article-buffer.  It is
 742 called by <concept>content-info</concept>.
 743 <p>
 744 Please use reference function
 745 <code>mime::content-info/SLOT-NAME</code> to reference slot of
 746 content-info.  Their argument is only content-info.
 747 <p>
 748 Following is a list of slots of the structure:
 749
 750 <vl>
 751 <dt>rcnum<dd>``reversed content-number'' (list)
 752 </dd>
 753 <dt>point-min<dd>beginning point of region in raw-article-buffer
 754 </dd>
 755 <dt>point-max<dd>end point of region in raw-article-buffer
 756 </dd>
 757 <dt>type<dd>content-type/sub-type (string or nil)
 758 </dd>
 759 <dt>parameters<dd>parameter of Content-Type field (association list)
 760 </dd>
 761 <dt>encoding<dd>Content-Transfer-Encoding (string or nil)
 762 </dd>
 763 <dt>children<dd>parts included in this part (list of content-infos)
 764 </dd>
 765 </vl>
 766 <p>
 767 If a part includes other parts in its contents, such as multipart or
 768 message/rfc822, content-infos of other parts are included in
 769 <var>children</var>, so content-info become a tree.
 770 </define>
 771
 772 <defvar name="mime::article/content-info">
 773 <p>
 774 result of MIME parsing of raw-article-buffer (content-info)
 775 </defvar>
 776
 777 <defvar name="mime::article/preview-buffer">
 778 <p>
 779 preview-buffer corresponded by this buffer
 780 </defvar>
 781
 782 <defun name="mime-article/point-content-number">
 783 <args> point <opts> cinfo
 784 <p>
 785 In a region managed by content-info <var>cinfo</var>, it returns
 786 content-number corresponded by <var>point</var>.
 787 <p>
 788 If <var>cinfo</var> is omitted,
 789 <code>mime::article/content-info</code> is used as default value.
 790 </defun>
 791
 792 <defun name="mime-article/rcnum-to-cinfo">
 793 <args> rcnum <opts> cinfo
 794 <p>
 795 In a region managed by content-info <var>cinfo</var>, it returns
 796 content-info corresponded by reversed-content-number <var>rcnum</var>.
 797 <p>
 798 If <var>cinfo</var> is omitted,
 799 <code>mime::article/content-info</code> is used as default value.
 800 </defun>
 801
 802 <defun name="mime-article/cnum-to-cinfo">
 803 <args> rcnum <opts> cinfo
 804 <p>
 805 In a region managed by content-info <var>cinfo</var>, it returns
 806 content-info corresponded by content-number <var>rcnum</var>.
 807 <p>
 808 If <var>cinfo</var> is omitted,
 809 <code>mime::article/content-info</code> is used as default value.
 810 </defun>
 811
 812 <defun name="mime/flatten-content-info">
 813 <args> <opts> cinfo
 814 <p>
 815 It returns flatten list of content-info from content-info
 816 <var>cinfo</var> tree.
 817 <p>
 818 If <var>cinfo</var> is omitted,
 819 <code>mime::article/content-info</code> is used as default value.
 820 </defun>
 821
 822
 823 <h2> Buffer local variables of preview-buffer
 824 <node> preview-buffer
 825 <p>
 826 <defvar name="mime::preview/mother-buffer">
 827 <p>
 828 Mother buffer of this preview-buffer.
 829 </defvar>
 830
 831 <define type="Structure" name="mime::preview-content-info">
 832 <args> point-min point-max buffer content-info
 833 <p>
 834 structure to represent MIME content in preview-buffer.  It is called
 835 by <concept>preview-content-info</concept>.
 836 <p>
 837 Please use reference function
 838 <code>mime::preview-content-info/SLOT-NAME</code> to reference slot of
 839 preview-content-info.  Their argument is only preview-content-info.
 840 <p>
 841 Following is a list of slots of the structure:
 842
 843 <vl>
 844 <dt>point-min<dd>beginning point of region in preview-buffer
 845 </dd>
 846 <dt> point-max<dd>end point of region in preview-buffer
 847 </dd>
 848 <dt>buffer<dd>raw-article-buffer corresponding a part
 849 </dd>
 850 <dt>content-info<dd>content-info corresponding a part
 851 </dd>
 852 </vl>
 853 </define>
 854
 855
 856 <defvar name="mime::preview/content-list">
 857 <p>
 858 List of preview-content-info to represent structure of this
 859 preview-buffer.
 860 </defvar>
 861
 862
 863 <defvar name="mime::preview/article-buffer">
 864 <p>
 865 raw-article-buffer corresponded by this preview-buffer.
 866 </defvar>
 867
 868
 869 <defvar name="mime::preview/original-major-mode">
 870 <p>
 871 major-mode of original buffer.
 872 </defvar>
 873
 874
 875 <defvar name="mime::preview/original-window-configuration">
 876 <p>
 877 window-configuration just before made this preview-buffer.
 878 </defvar>
 879
 880
 881 <defun name="mime-preview/point-pcinfo">
 882 <args> point <opts> pcl
 883 <p>
 884 In a region of preview-buffer managed by preview-content-info
 885 <var>pcl</var>, it returns preview-content-info corresponded by
 886 <var>point</var>.
 887 <p>
 888 If <var>cinfo</var> is omitted,
 889 <code>mime::preview/content-list</code> is used.
 890 </defun>
 891
 892
 893 <h1> Functions to decode MIME message
 894 <node> API
 895 <p>
 896 tm-view provides some available functions to decode and navigate MIME
 897 message to each <a file="tm-en" node="MUA">MUA</a>s.
 898 <p>
 899 There are 2 kinds of functions, one is for MIME preview, another one
 900 is to decode RFC 1522 <dref file="tm-en">encoded-word</dref>.
 901
 902
 903 <h2> Function to preview MIME message
 904 <node> API about MIME preview
 905 <p>
 906
 907 <define type="Command" name="mime/viewer-mode">
 908 <opts> mother ctl encoding ibuf obuf mother-keymap
 909 <p>
 910 Parse <var>ibuf</var> as a MIME message, and create preview-buffer
 911 into <var>obuf</var> to display to user, then enter <a
 912 node="mime/viewer-mode"><code>mime/viewer-mode</code></a>.
 913 <p>
 914 If <var>ibuf</var> is omitted, current buffer is used.
 915 <p>
 916 <var>mother</var> is used to specify original raw-article-buffer.  It
 917 may be useful when a raw-article-buffer is assembled from
 918 message/partial messages.
 919 <p>
 920 <var>ctl</var> is used to specify <dref file="tm-en">Content-Type
 921 field</dref> information.  Its format is output format of
 922 <code>mime/Content-Type</code>.  When <var>ctl</var> is specified,
 923 tm-view uses it instead of Content-Type field of the
 924 raw-article-buffer.
 925 <p>
 926 <var>encoding</var> is used to specify field-body of
 927 Content-Transfer-Encoding field.  When is is specified, tm-view uses
 928 it instead of Content-Type field of the raw-article-buffer.
 929 <p>
 930 If <var>mother-keymap</var> is specified, keymap of
 931 <code>mime/viewer-mode</code> includes it.
 932 </define>
 933
 934
 935 <h2> encoded-word decoder
 936 <node> encoded-word decoding
 937 <p>
 938 tm-view has functions to decode RFC 1522 <dref
 939 file="tm-en">encoded-word</dref>.
 940
 941
 942 <define type="Command" name="mime/decode-message-header">
 943 <p>
 944 It decodes encoded-words in message header of current buffer.
 945 <p>
 946 If an encoded-word is broken or invalid, or it has non supported <a
 947 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 948 </define>
 949
 950
 951 <define type="Command" name="mime-eword/decode-region">
 952 <args> start end <opts> unfolding must-unfold
 953 <p>
 954 It decodes encoded-words in region <var>start</var> to <var>end</var>.
 955 <p>
 956 If an encoded-word is broken or invalid, or it has non supported <a
 957 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 958 <p>
 959 If <var>unfolding</var> is non-nil, it unfolds folded fields.
 960 <p>
 961 If <var>must-fold</var> is non-nil and decoded result of an
 962 encoded-word has folding or raw CR or LF, it unfolds or delete raw CR
 963 or LF.
 964 </define>
 965
 966
 967 <defun name="mime-eword/decode-string">
 968 <args> string <opts> must-unfold
 969 <p>
 970 It decodes encoded-words in <var>string</var> and returns decoded
 971 string.
 972 <p>
 973 If an encoded-word is broken or invalid, or it has non supported <a
 974 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 975 <p>
 976 If <var>string</var> is folded, it unfolds <var>string</var> before
 977 decoding.
 978 <p>
 979 If <var>must-fold</var> is non-nil and decoded result of an
 980 encoded-word has folding or raw CR or LF, it unfolds or delete raw CR
 981 or LF.
 982 </defun>
 983
 984
 985 <h1> Acknowledgments
 986 <node> Acknowledgments
 987 <p>
 988 First of all, I thank MASUTANI Yasuhiro.  He requested me a lot of
 989 important features and gave me a lot of suggestions when tm-view was
 990 born.  tm-view is based on his influence.
 991 <p>
 992 I thank ENAMI Tsugutomo for work of <file>mime.el</file>, which is an
 993 origin of <file>tm-ew-d.el</file> and <file>mel-b.el</file>, and
 994 permission to rewrite for tm.
 995 <p>
 996 I thank OKABE Yasuo for work of internal method for LaTeX and
 997 automatic assembling method for message/partial.  I thank UENO
 998 Hiroshi for work of internal method for tar archive.
 999 <p>
1000 Last of all, I thank members of two tm mailing lists, Japanese and
1001 English version.
1002
1003
1004 <h1> Concept Index
1005 <node> Concept Index
1006
1007 <cindex>
1008
1009
1010 <h1> Function Index
1011 <node> Function Index
1012
1013 <findex>
1014
1015
1016 <h1> Variable Index
1017 <node> Variable Index
1018
1019 <vindex>
1020
1021 </body>