doc/tm-view-en.sgml

   1 <!doctype sinfo system>
   2 <!-- $Id: tm-view-en.sgml,v 1.1 1996/11/29 19:09:27 morioka Exp $ -->
   3 <head>
   4 <title>tm-view 7.77 Reference Manual (English Version)
   5 <author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
   6 <date>1996/10/11
   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>n
 357 <kd>
 358 goes to the next content
 359 </kd>
 360 <kt>SPC
 361 <kd>
 362 scrolls up
 363 </kd>
 364 <kt>M-SPC
 365 <kd>
 366 scrolls down
 367 </kd>
 368 <kt>DEL
 369 <kd>
 370 scrolls down
 371 </kd>
 372 <kt>RET
 373 <kd>
 374 goes to the next line
 375 </kd>
 376 <kt>M-RET
 377 <kd>
 378 goes to the previous line
 379 </kd>
 380 <kt>&lt;
 381 <kd>
 382 goes to the beginning of message
 383 </kd>
 384 <kt>&gt;
 385 <kd>
 386 goes to the end of message
 387 </kd>
 388 <kt>v
 389 <kd>
 390 playbacks a part (*2)
 391 </kd>
 392 <kt>e
 393 <kd>
 394 extracts a file from a part (*2)
 395 </kd>
 396 <kt>C-c C-p
 397 <kd>
 398 prints a part (*2)
 399 </kd>
 400 <kt>f
 401 <kd>
 402 displays X-Face in the message
 403 </kd>
 404 <kt>mouse-button-2
 405 <kd>
 406 drives mouse button in preview-buffer.
 407 <p>
 408 For content-button, it playbacks a part (*2)
 409 <p>
 410 For URL-button, it drives WWW browser
 411 </kd>
 412 </kl>
 413 <p>
 414 <memo title="Notice">
 415 <p>
 416 (*1) Not return to the Summary mode unless tm-view has been setup
 417 using tm-mh-e, tm-vm, gnus-mime, tm-gnus, tm-rmail etc.
 418 <p>
 419 (*2) Actual playback/extract/print will be performed by a method.
 420 </memo>
 421
 422
 423 <h1> Mechanism of decoding
 424 <node> method
 425 <p>
 426 In <code>mime/viewer-mode</code>, you can do play (<kbd>v</kbd>),
 427 extract (<kbd>e</kbd>), or print (<kbd>C-c C-p</kbd>) for each parts.
 428 These operations are called <concept>decoding operation(s) (for a
 429 part)</concept>.  And kind of decoding operations are called
 430 <concept>decoding-mode</concept>.
 431 <p>
 432 When decoding operation is driven, tm-view calls a procedure matched
 433 for the condition, such as <dref file="tm-en">content-type</dref> of
 434 the part or its environment.  This procedure is called
 435 <concept>method</concept>.
 436 <p>
 437 There are two kinds of methods.  One is Emacs Lisp function, called
 438 <concept>internal method</concept>.  Another one is external program,
 439 called <concept>external method</concept>.
 440 <p>
 441 Internal method operates in Emacs, so it can do carefully.
 442 <p>
 443 External method is called as asynchronous process, so Emacs does not
 444 wait while method is running.  So it is good for big data, such as
 445 audio, image or video.
 446
 447
 448 <h2> Setting decoding condition for parts
 449 <node> decoding-condition
 450 <p>
 451 When decoding operation is driven, tm-view calls a method matched for
 452 the condition searched from the variable
 453 <code>mime/content-decoding-condition</code>.
 454 <p>
 455 Variable <code>mime/content-decoding-condition</code> is defined as a
 456 list with the following syntax:
 457 <p>
 458 <lisp>
 459         (condition_1 condition_2 ...)
 460 </lisp>
 461 <p>
 462 Each condition are association-list with the following syntax:
 463 <p>
 464 <lisp>
 465         ((field-type_1 . value_1)
 466          (field-type_2 . value_2)
 467          ...)
 468 </lisp>
 469 <p>
 470 For example, if you want to call the external method named tm-plain to
 471 decode every <dref file="tm-en">text/plain</dref> type parts, you can
 472 define the condition like:
 473 <p>
 474 <lisp>
 475         ((type . "text/plain")
 476          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
 477 </lisp>
 478 <p>
 479 This condition definition will match all parts whose <dref
 480 file="tm-en">content-type</dref> are text/plain.  Here is an another
 481 example:
 482 <p>
 483 <lisp>
 484         ((type . "text/plain")
 485          (method "tm-plain" nil 'file 'type 'encoding 'mode 'name)
 486          (mode . "play"))
 487 </lisp>
 488 <p>
 489 This will match the part whose type is text/plain and the mode is
 490 play.
 491 <p>
 492 Here is an another example:
 493 <p>
 494 <lisp>
 495         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file)
 496          (mode . "play"))
 497 </lisp>
 498 <p>
 499 This will match all parts which have a mode of play.
 500 <p>
 501 The conditions defined in a variable
 502 <code>mime/content-decoding-condition</code> are examined from top to
 503 bottom.  The first matching condition becomes valid and the method
 504 specified in that condition definition will be executed.
 505
 506
 507 <h3> Format of method value
 508 <node> method value
 509 <p>
 510 You can specify the method field of the decoding-condition definition
 511 in two different ways,
 512 <p>
 513 <lisp>
 514         (method . SYMBOL)
 515 </lisp>
 516 <p>
 517 <noindent>
 518 or
 519 <p>
 520 <lisp>
 521         (method  STRING  FLAG  arg1  arg2  ...)
 522 </lisp>
 523 <p>
 524 <noindent>
 525 can be accepted.
 526 <p>
 527 When a symbol is specified in the method field, a function whose name
 528 is SYMBOL will be called as an internal method.
 529 <p>
 530 When a list is specified in the method field, it will be called as an
 531 external method.
 532 <p>
 533 The list below shows the meaning of the parameters when the external
 534 method is specified in the method field.
 535 <p>
 536 <dl>
 537 <dt>STRING
 538 <dd>name of an external method
 539 </dd>
 540 <dt>FLAG
 541 <dd>If <code>t</code>, both the content-header and the content-body
 542 are passed to an external method.
 543 <p>
 544 If <code>nil</code>, only the content-body is passed to an external
 545 method.
 546 </dd>
 547 <dt>ARGUMENTs
 548 <dd>list of arguments passed to an external method
 549 </dd>
 550 </dl>
 551 <p>
 552 An argument passed to an external method can be in one of the
 553 following formats:
 554 <p>
 555 <dl>
 556 <dt>STRING
 557 <dd>string itself
 558 </dd>
 559 <dt>'SYMBOL
 560 <dd>value gotten using SYMBOL as a key from decoding-condition
 561 </dd>
 562 <dt>'STRING
 563 <dd>value gotten using STRING as a key from decoding-condition
 564 </dd>
 565 </dl>
 566 <p>
 567 <code>'SYMBOL</code> can be one of the following:
 568 <p>
 569 <dl>
 570 <dt>'file
 571 <dd>name of a file holding the original content
 572 </dd>
 573 <dt>'type
 574 <dd>content-type/sub-type of Content-Type field
 575 </dd>
 576 <dt>'encoding
 577 <dd>field body of Content-Transfer-Encoding field
 578 </dd>
 579 <dt>'mode
 580 <dd>decoding-mode
 581 </dd>
 582 <dt>'name
 583 <dd>name of a file created by decode operation
 584 </dd>
 585 </dl>
 586
 587 <p>
 588 <code>'STRING</code> is used to search a parameter of the Content-Type
 589 field whose name matches with it, and pass the value of that parameter
 590 to the external method.
 591
 592
 593 <h3> Example of decoding-condition
 594 <node> Example of decoding-condition
 595 <p>
 596 Following is an example of decoding-condition:
 597
 598 <lisp>
 599 (defvar mime/content-decoding-condition
 600   '(((type . "text/plain")
 601      (method "tm-plain" nil 'file 'type 'encoding 'mode 'name))
 602     ((type . "text/x-latex")
 603      (method "tm-latex" nil 'file 'type 'encoding 'mode 'name))
 604     ((type . "audio/basic")
 605      (method "tm-au"    nil 'file 'type 'encoding 'mode 'name))
 606     ((type . "image/gif")
 607      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 608     ((type . "image/jpeg")
 609      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 610     ((type . "image/tiff")
 611      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 612     ((type . "image/x-tiff")
 613      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 614     ((type . "image/x-xbm")
 615      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 616     ((type . "image/x-pic")
 617      (method "tm-image" nil 'file 'type 'encoding 'mode 'name))
 618     ((type . "video/mpeg")`
 619      (method "tm-mpeg"  nil 'file 'type 'encoding 'mode 'name))
 620     ((type . "application/octet-stream")
 621      (method "tm-file"  nil 'file 'type 'encoding 'mode 'name))
 622     ((type . "message/partial")
 623      (method . mime/decode-message/partial-region))
 624     ((method "metamail" t
 625              "-m" "tm" "-x" "-d" "-z" "-e" 'file)(mode . "play"))
 626     ))
 627 </lisp>
 628
 629 <p>
 630 For example, if you want to use metamail to decode any contents,
 631
 632 <lisp>
 633 (setq mime/content-decoding-condition
 634       '(
 635         ((method "metamail" t "-m" "tm" "-x" "-d" "-z" "-e" 'file))
 636        ))
 637 </lisp>
 638
 639 <noindent>
 640 will work.
 641 <p>
 642 Variable <code>mime/content-decoding-condition</code> provides you of
 643 very flexible way to define the conditions of decoding.  It can be
 644 simple if you only need the a few decoding methods, while it can be
 645 very complicated if you want to use the separate decoding method for
 646 each type/mode combination.
 647 <p>
 648 Following function may be useful to set decoding-condition.  It is a
 649 function of <file>tl-atype.el</file>.
 650
 651
 652 <defun name="set-atype">
 653 <args> symbol alist
 654 <p>
 655 Add condition <var>alist</var> to <var>symbol</var>.
 656
 657 <memo title="Example">
 658 <p>
 659 <lisp>
 660 (set-atype 'mime/content-decoding-condition
 661            '((type . "message/external-body")
 662              ("access-type" . "anon-ftp")
 663              (method . mime/decode-message/external-ftp)
 664              ))
 665 </lisp>
 666 </memo>
 667 </defun>
 668
 669
 670 <h2> Environment variables
 671 <node> environment variables
 672 <p>
 673 Standard methods of tm-view reference some environment variables.  You
 674 can specify them to customize.
 675
 676 <vl>
 677 <dt>TM_TMP_DIR
 678 <dd>
 679 Directory for temporary files or extracted files.  If it is omitted,
 680 <file>/tmp/</file> is used.
 681 </dd>
 682 <dt>VIDEO_DITHER
 683 <dd>
 684 Dither for mpeg_play.  If it is omitted, `gray' is used.
 685 </dd>
 686 <dt>TM_WWW_BROWSER
 687 <dd>
 688 WWW browser name.  If it is omitted, `netscape' is used.
 689 </vl>
 690
 691
 692 <h1> raw-article-buffer and preview-buffer
 693 <node> Two buffers for an article
 694 <p>
 695 tm-view managements two buffers, one is for raw message called
 696 <concept>raw-article-buffer</concept>, another one is to preview for
 697 user called <concept>preview-buffer</concept>.  major-mode of
 698 raw-article-buffer is same as major-mode for article of original MUA,
 699 major-mode of preview-buffer is <a
 700 node="mime/viewer-mode"><code>mime/viewer-mode</code></a>.
 701 <p>
 702 When called <code>mime/viewer-mode</code>, tm-view analyzes
 703 raw-article-buffer, and sets its result to the variable
 704 <code>mime::article/content-info</code>.
 705 <p>
 706 After that, tm-view create a preview-buffer corresponded to the
 707 raw-article-buffer.  As this time, tm-view modifies header and body of
 708 each parts of the message by specified conditions.  Filter program for
 709 header is called <a
 710 node="content-header"><concept>header-filter</concept></a>, filter
 711 program for body is called <a
 712 node="content-body"><concept>content-filter</concept></a>, and they
 713 are called <concept>filter</concept>.
 714 <p>
 715 When preview-buffer is made, buffer local variable of preview-buffer
 716 <code>mime::preview/content-list</code> is made to register structure
 717 of preview-buffer.  tm-view manages message by
 718 <code>mime::article/content-info</code> in raw-article-buffer and
 719 <code>mime::preview/content-list</code> in preview-buffer.
 720 <p>
 721 <memo title="Notice">
 722 In this document, I call ``content-type'' as content-type/subtype of
 723 Content-Type field.
 724 </memo>
 725
 726
 727 <h2> buffer local variables of raw-article-buffer
 728 <node> raw-article-buffer
 729 <p>
 730 <define type="Structure" name="mime::content-info">
 731 <args> rcnum point-min point-max type parameters encoding children
 732 <p>
 733 structure to represent MIME content in raw-article-buffer.  It is
 734 called by <concept>content-info</concept>.
 735 <p>
 736 Please use reference function
 737 <code>mime::content-info/SLOT-NAME</code> to reference slot of
 738 content-info.  Their argument is only content-info.
 739 <p>
 740 Following is a list of slots of the structure:
 741
 742 <vl>
 743 <dt>rcnum<dd>``reversed content-number'' (list)
 744 </dd>
 745 <dt>point-min<dd>beginning point of region in raw-article-buffer
 746 </dd>
 747 <dt>point-max<dd>end point of region in raw-article-buffer
 748 </dd>
 749 <dt>type<dd>content-type/sub-type (string or nil)
 750 </dd>
 751 <dt>parameters<dd>parameter of Content-Type field (association list)
 752 </dd>
 753 <dt>encoding<dd>Content-Transfer-Encoding (string or nil)
 754 </dd>
 755 <dt>children<dd>parts included in this part (list of content-infos)
 756 </dd>
 757 </vl>
 758 <p>
 759 If a part includes other parts in its contents, such as multipart or
 760 message/rfc822, content-infos of other parts are included in
 761 <var>children</var>, so content-info become a tree.
 762 </define>
 763
 764 <defvar name="mime::article/content-info">
 765 <p>
 766 result of MIME parsing of raw-article-buffer (content-info)
 767 </defvar>
 768
 769 <defvar name="mime::article/preview-buffer">
 770 <p>
 771 preview-buffer corresponded by this buffer
 772 </defvar>
 773
 774 <defun name="mime-article/point-content-number">
 775 <args> point <opts> cinfo
 776 <p>
 777 In a region managed by content-info <var>cinfo</var>, it returns
 778 content-number corresponded by <var>point</var>.
 779 <p>
 780 If <var>cinfo</var> is omitted,
 781 <code>mime::article/content-info</code> is used as default value.
 782 </defun>
 783
 784 <defun name="mime-article/rcnum-to-cinfo">
 785 <args> rcnum <opts> cinfo
 786 <p>
 787 In a region managed by content-info <var>cinfo</var>, it returns
 788 content-info corresponded by reversed-content-number <var>rcnum</var>.
 789 <p>
 790 If <var>cinfo</var> is omitted,
 791 <code>mime::article/content-info</code> is used as default value.
 792 </defun>
 793
 794 <defun name="mime-article/cnum-to-cinfo">
 795 <args> rcnum <opts> cinfo
 796 <p>
 797 In a region managed by content-info <var>cinfo</var>, it returns
 798 content-info corresponded by content-number <var>rcnum</var>.
 799 <p>
 800 If <var>cinfo</var> is omitted,
 801 <code>mime::article/content-info</code> is used as default value.
 802 </defun>
 803
 804 <defun name="mime/flatten-content-info">
 805 <args> <opts> cinfo
 806 <p>
 807 It returns flatten list of content-info from content-info
 808 <var>cinfo</var> tree.
 809 <p>
 810 If <var>cinfo</var> is omitted,
 811 <code>mime::article/content-info</code> is used as default value.
 812 </defun>
 813
 814
 815 <h2> Buffer local variables of preview-buffer
 816 <node> preview-buffer
 817 <p>
 818 <defvar name="mime::preview/mother-buffer">
 819 <p>
 820 Mother buffer of this preview-buffer.
 821 </defvar>
 822
 823 <define type="Structure" name="mime::preview-content-info">
 824 <args> point-min point-max buffer content-info
 825 <p>
 826 structure to represent MIME content in preview-buffer.  It is called
 827 by <concept>preview-content-info</concept>.
 828 <p>
 829 Please use reference function
 830 <code>mime::preview-content-info/SLOT-NAME</code> to reference slot of
 831 preview-content-info.  Their argument is only preview-content-info.
 832 <p>
 833 Following is a list of slots of the structure:
 834
 835 <vl>
 836 <dt>point-min<dd>beginning point of region in preview-buffer
 837 </dd>
 838 <dt> point-max<dd>end point of region in preview-buffer
 839 </dd>
 840 <dt>buffer<dd>raw-article-buffer corresponding a part
 841 </dd>
 842 <dt>content-info<dd>content-info corresponding a part
 843 </dd>
 844 </vl>
 845 </define>
 846
 847
 848 <defvar name="mime::preview/content-list">
 849 <p>
 850 List of preview-content-info to represent structure of this
 851 preview-buffer.
 852 </defvar>
 853
 854
 855 <defvar name="mime::preview/article-buffer">
 856 <p>
 857 raw-article-buffer corresponded by this preview-buffer.
 858 </defvar>
 859
 860
 861 <defvar name="mime::preview/original-major-mode">
 862 <p>
 863 major-mode of original buffer.
 864 </defvar>
 865
 866
 867 <defvar name="mime::preview/original-window-configuration">
 868 <p>
 869 window-configuration just before made this preview-buffer.
 870 </defvar>
 871
 872
 873 <defun name="mime-preview/point-pcinfo">
 874 <args> point <opts> pcl
 875 <p>
 876 In a region of preview-buffer managed by preview-content-info
 877 <var>pcl</var>, it returns preview-content-info corresponded by
 878 <var>point</var>.
 879 <p>
 880 If <var>cinfo</var> is omitted,
 881 <code>mime::preview/content-list</code> is used.
 882 </defun>
 883
 884
 885 <h1> Functions to decode MIME message
 886 <node> API
 887 <p>
 888 tm-view provides some available functions to decode and navigate MIME
 889 message to each <a file="tm-en" node="MUA">MUA</a>s.
 890 <p>
 891 There are 2 kinds of functions, one is for MIME preview, another one
 892 is to decode RFC 1522 <dref file="tm-en">encoded-word</dref>.
 893
 894
 895 <h2> Function to preview MIME message
 896 <node> API about MIME preview
 897 <p>
 898
 899 <define type="Command" name="mime/viewer-mode">
 900 <opts> mother ctl encoding ibuf obuf mother-keymap
 901 <p>
 902 Parse <var>ibuf</var> as a MIME message, and create preview-buffer
 903 into <var>obuf</var> to display to user, then enter <a
 904 node="mime/viewer-mode"><code>mime/viewer-mode</code></a>.
 905 <p>
 906 If <var>ibuf</var> is omitted, current buffer is used.
 907 <p>
 908 <var>mother</var> is used to specify original raw-article-buffer.  It
 909 may be useful when a raw-article-buffer is assembled from
 910 message/partial messages.
 911 <p>
 912 <var>ctl</var> is used to specify <dref file="tm-en">Content-Type
 913 field</dref> information.  Its format is output format of
 914 <code>mime/Content-Type</code>.  When <var>ctl</var> is specified,
 915 tm-view uses it instead of Content-Type field of the
 916 raw-article-buffer.
 917 <p>
 918 <var>encoding</var> is used to specify field-body of
 919 Content-Transfer-Encoding field.  When is is specified, tm-view uses
 920 it instead of Content-Type field of the raw-article-buffer.
 921 <p>
 922 If <var>mother-keymap</var> is specified, keymap of
 923 <code>mime/viewer-mode</code> includes it.
 924 </define>
 925
 926
 927 <h2> encoded-word decoder
 928 <node> encoded-word decoding
 929 <p>
 930 tm-view has functions to decode RFC 1522 <dref
 931 file="tm-en">encoded-word</dref>.
 932
 933
 934 <define type="Command" name="mime/decode-message-header">
 935 <p>
 936 It decodes encoded-words in message header of current buffer.
 937 <p>
 938 If an encoded-word is broken or invalid, or it has non supported <a
 939 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 940 </define>
 941
 942
 943 <define type="Command" name="mime-eword/decode-region">
 944 <args> start end <opts> unfolding must-unfold
 945 <p>
 946 It decodes encoded-words in region <var>start</var> to <var>end</var>.
 947 <p>
 948 If an encoded-word is broken or invalid, or it has non supported <a
 949 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 950 <p>
 951 If <var>unfolding</var> is non-nil, it unfolds folded fields.
 952 <p>
 953 If <var>must-fold</var> is non-nil and decoded result of an
 954 encoded-word has folding or raw CR or LF, it unfolds or delete raw CR
 955 or LF.
 956 </define>
 957
 958
 959 <defun name="mime-eword/decode-string">
 960 <args> string <opts> must-unfold
 961 <p>
 962 It decodes encoded-words in <var>string</var> and returns decoded
 963 string.
 964 <p>
 965 If an encoded-word is broken or invalid, or it has non supported <a
 966 file="tm-en" node="MIME charset">MIME charset</a>, it is not decoded.
 967 <p>
 968 If <var>string</var> is folded, it unfolds <var>string</var> before
 969 decoding.
 970 <p>
 971 If <var>must-fold</var> is non-nil and decoded result of an
 972 encoded-word has folding or raw CR or LF, it unfolds or delete raw CR
 973 or LF.
 974 </defun>
 975
 976
 977 <h1> Concept Index
 978 <node> Concept Index
 979
 980 <cindex>
 981
 982
 983 <h1> Function Index
 984 <node> Function Index
 985
 986 <findex>
 987
 988
 989 <h1> Variable Index
 990 <node> Variable Index
 991
 992 <vindex>
 993
 994 </body>