gnus-mime 0.10 reference manual (English Version)
*************************************************

This file documents gnus-mime, a MIME extension for Gnus.

What is gnus-mime?
******************

gnus-mime is a MIME ((tm-en)MIME) extender for Gnus ((gnus)) using tm ((tm-en)tm-kernel).

[Notice]

     gnus-mime is for only Gnus.  Please use tm-gnus ((tm-gnus_en)) for GNUS.

gnus-mime supports automatic MIME preview in "*Article*" buffer using tm-view ((tm-view-en)).  In particular, with XEmacs, it decodes images as same as text.

In addition, gnus-mime supports multilingual/internationalization feature for mule such as MULE ((tm-en)mule), XEmacs/mule and mule merged Emacs.  It supports code-conversion by MIME charset or depended default MIME charset of newsgroups.

For RFC 1522, original Gnus supports only Q-encoded iso-8859-1 ((tm-en)iso-8859-1) encoded-word ((tm-en)encoded-word).  So gnus-mime supports more MIME charsets, such as iso-8859-2 ((tm-en)iso-8859-2), iso-8859-3 ((tm-en)iso-8859-3), ..., iso-2022-jp ((tm-en)iso-2022-jp), euc-kr ((tm-en)euc-kr), iso-2022-kr ((tm-en)iso-2022-kr), gb2312, hz-gb-2312 ((tm-en)hz-gb-2312), cn-big5 ((tm-en)cn-big5), and B-encoding.  In addition, original Gnus does not support unfolding or space elimination rule of RFC 1522.  gnus-mime is more rightful.

Inline display for MIME message
*******************************

automatic MIME preview feature is available for gnus-mime.  In automatic MIME preview mode, when reading an article in summary mode, gnus-mime displays preview buffer processed by tm-view instead of raw article buffer. (cf. (tm-view-en))

Therefore if an article is encoded by Base64 ((tm-en)Base64) or Quoted-Printable ((tm-en)Quoted-Printable), a decoded article is displayed.  Or rich text article, such as text/enriched ((tm-en)text/enriched) format, is automatic formated.  Of course, multipart ((tm-en)multipart) article is dealt with correctly.

In addition, in XEmacs, images are displayed in preview buffer as same as text.

Different from using metamail, speaker does not roar just then read an article includes audio content, video player does not play just then read an article includes video content, it does not do anonymous ftp ((tm-en)ftp) or send mail when read an article includes external-message.  These contents are played when you do decoding command in preview buffer.

However if you use a slow machine, or are just really impatient, you can stop automatic MIME preview.

How to process MIME in Article Buffer
=====================================

When gnus-show-mime is not nil and an article has Mime-Version field in its message header, namely it is a MIME message, Gnus calls gnus-show-mime-method to process MIME.

When gnus-strict-mime is nil and gnus-show-mime is not nil, Gnus calls gnus-show-mime-method even if an message does not have Mime-Version field in its message header.

Gnus 5.2 or later calls gnus-show-mime-method when gnus-strict-mime is not nil and an article does not have Mime-Version field.  Notice that old Gnus does not have it, so it may be better to set gnus-strict-mime to nil.

 -- Variable: gnus-show-mime

     If it is not nil, Gnus do automatic MIME preview.  Default value is t.

     It is a variable of Gnus, so if gnus is loaded before gnus-mime is loaded, default value is not guaranteed.

     (cf. (gnus)Using MIME)

 -- Variable: gnus-show-mime-method

     Gnus calls function bound by it to process MIME.  Default value is gnus-article-preview-mime-message.

     It is a variable of Gnus, so if gnus is loaded before gnus-mime is loaded, default value is not guaranteed.

     (cf. (gnus)Using MIME)

 -- Variable: gnus-decode-encoded-word-method

     Gnus calls function bound by it to decode encoded-words.  Default value is gnus-article-decode-encoded-word.

     It is a variable of Gnus, so if gnus is loaded before gnus-mime is loaded, default value is not guaranteed.

     In addition, it is not available at Gnus 5.0.* or Gnus 5.1.

[Notice]

     gnus-mime uses some variables of Gnus and defines different default values by defvar.  For example, gnus-mime's default value of gnus-show-mime is t instead of nil.  Or its default value of gnus-show-mime-method is gnus-article-preview-mime-message instead of metamail-buffer.  (cf. (gnus)Using MIME)

     gnus-mime uses defvar instead of setq, because of respect user's setting before gnus-mime is loaded, such as using ~/.emacs.  But it has a problem.  If gnus is loaded before gnus-mime is loaded, features of gnus-mime is not available in default even if gnus-mime is loaded.  Therefore there is serious problem to load gnus before gnus-mime is loaded.  In other words, setting in ~/.gnus, such as to load gnus-mime or mime-setup, is not good way.  If you want such way, please do setting for gnus-show-mime and gnus-show-mime-method.

Mechanism of Automatic MIME preview
===================================

Gnus 5.2 or later has two buffers for an article, gnus-original-article-buffer (" *Original Article*") and gnus-article-buffer ("*Article*").  The former is called raw article buffer, the latter is called preview buffer.

Content of raw article buffer is non-processed ``raw message''.  In particular, for emacs variants includes mule ((tm-en)mule) features, message is not code-converted in it.

Content of preview buffer is MIME processed message to display for user. In particular, for emacs variants includes mule features, non-ASCII message is code-converted in it by MIME charset or default MIME charset ((tm-en)MIME charset) for selected newsgroup.

Gnus 5.0.* and Gnus 5.1 don't have distinction between raw article buffer and preview buffer.  So gnus-mime emulate raw article buffer.  It is unnatural, so it may be better to use Gnus 5.2 or later, which are designed for tm-view.

(cf. (tm-view-en)Two buffers for an article)

Internationalization
********************

For emacs variants includes mule feature, such as MULE ((tm-en)MULE), XEmacs/mule and Emacs/mule(*1), gnus-mime supports code-conversion by MIME charset ((tm-en)MIME charset) or default-mime-charset of selected newsgroup.

[Memo]

     (*1) It means next generation of Emacs includes mule features.  Now (October 1996), HANDA Ken'ichi and RMS are developing it.

Detail of code conversion is following:

 1. If a newsgroup is selected, MIME charset for the newsgroup is searched from gnus-newsgroup-default-charset-alist.  If it is found, it is set to buffer local variable default-mime-charset of Summary Buffer.  If not found, global value of default-mime-charset is used.

 2. Non-ASCII characters in Summary Buffer are code-converted by default-mime-charset in Summary Buffer.

 3. encoded-word ((tm-en)encoded-word) are code-converted by their specified MIME charset ((tm-en)MIME charset).

 4. Code-conversion of articles are following:

      1. If a part of a MIME message has charset parameter of Content-Type field ((tm-en)Content-Type field), it is code-converted by the MIME charset.

      2. When there are no specified MIME charset, such as message header or non-MIME message, they are code-converted by default-mime-charset in Summary Buffer.

 -- Variable: gnus-newsgroup-default-charset-alist

     Association-list regexp for newsgroup vs. symbol for default MIME charset.

     Default setting are following:

     alt.chinese.*
          hz-gb-2312 ((tm-en)hz-gb-2312)

     alt.chinese.text.big5, hk.*, hkstar.*, tw.*
          cn-big5 ((tm-en)cn-big5)

     fj.*
          iso-2022-jp-2 ((tm-en)iso-2022-jp-2)

     han.*
          euc-kr ((tm-en)euc-kr)

     relcom.*
          koi8-r ((tm-en)koi8-r)

     If there is no MIME charsets for a newsgroup, default-mime-charset is used as default MIME charset.

 -- Function: gnus-set-newsgroup-default-charsetnewsgroup charset

     Set default MIME CHARSET of NEWSGROUP to gnus-newsgroup-default-charset-alist.

     NEWSGROUP is string of newsgroup name or category, for "gnu.emacs.gnus", "gnu.emacs", "gnu".

     CHARSET is symbol of MIME charset, for example iso-8859-1, iso-2022-jp.

Composing MIME messages
***********************

If using mime-setup ((tm-en)mime-setup), you can edit MIME message in message-mode using tm-edit ((tm-edit-en)).

[Notice]

     Default setting of mime-setup avoids automatic inserting signature when sending a message.

     (cf. (tm-en)mime-setup)

gnus-mime does not have implementation for C-c C-x C-m (mime-editor/insert-mail).  Because gnus-mime does not know which mail-reader should be used.  In addition, C-c C-x C-y (mime-editor/insert-message) is enough to insert mail (namely to select a mail group and select a message to insert, then it is available to insert the mail message).

However you can use C-c C-x C-m to specify an implementation of message-mode to mime-editor/mail-inserter-alist.

Example: same as C-c C-x C-m
============================

     (set-alist 'mime-editor/mail-inserter-alist
     	   'message-mode (function message-mime-insert-article))

Example: including from MH folder
=================================

     (autoload 'tm-mh-e/insert-mail "tm-mh-e")

     (set-alist 'mime-editor/mail-inserter-alist
     	   'message-mode (function tm-mh-e/insert-mail))