tm-edit 7.100 Reference Manual (English Version)
************************************************

   This file documents tm-edit, a MIME composer for GNU Emacs.

What is tm-edit?
****************

   *tm-edit* is a general MIME composer for GNU Emacs.

   tm-edit is based on mime.el by UMEDA Masanobu
<umerin@mse.kyutech.ac.jp>, who is famous as the author of GNUS.
tm-edit expands following points from `mime.el':

   * based on RFC 1521/1522

   * Content-Disposition field (see Content-Disposition (tm-en))
     (RFC 1806) supports

   * nested multi-part message (see multipart (tm-en))

   * PGP (see PGP) (PGP/MIME (RFC 2015) based on security multipart
     (RFC 1847) and application/pgp based on traditional PGP)

   * strength automatic specification for parameter of file type

   In tm-MUA (see tm-MUA (tm-en)), you can edit MIME message easily
to use tm-edit.

mime/editor-mode
****************

   *mime/editor-mode* is a minor mode to compose MIME message.  In this
mode, *tag* represents various kinds of data, you can edit multi part
(see multipart (tm-en)) message.

   There are 2 kinds of tags:

   *  single-part tag

   *  multi-part tag

   single-part tag represents single part, this form is following:

             --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
             OPTIONAL-FIELDS]

   TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
Content-Type field (see Content-Type field (tm-en)).  TYPE/SUBTYPE is
required, PARAMETERS is optional.

   ENCODING indicates Content-Transfer-Encoding field.  It is optional
too.

   OPTIONAL-FIELDS is to represent another fields except Content-Type
field and Content-Transfer-Encoding field.

   multi-part tags represent multi part (see multipart (tm-en)).
They consist of a pair of *multi-part beginning tag* and *multi-part
ending tag*.

   multi-part beginning tag's form is following:

             --<<TYPE>>-{

   multi-part ending tag's form is following:

             --}-<<TYPE>>

   A region from multi-part beginning tag to multi-part ending tag is
called as *enclosure*.

single-part operations
**********************

   Operations to make single-part are following:

`<C-c C-x C-t>'
     Insert single-part tag indicates text part.

`<C-c C-x C-i>'
     Insert file as a MIME attachment.  If `C-u' is followed by it, it
     asks media-type, subtype or encoding even if their default values
     are specified. (cf. tag specification for inserted file)

`<C-c C-x C-e>'
     Insert external part.

`<C-c C-x C-v>'
     Record audio input until `C-g' is pressed, and insert as a audio
     part. (It requires /dev/audio in default.)

`<C-c C-x C-y>'
     Insert current (mail or news) message. (It is MUA depended.)

`<C-c C-x C-m>'
     Insert mail message. (It is MUA depended.)

`<C-c C-x C-w>, <C-c C-x C-s>'
     Insert signature.

`<C-c C-x C-k>'
     Insert PGP (see PGP) public key. (It requires Mailcrypt
     package.)

`<C-c C-x t>'
     Insert any single-part tag.

enclosure operation
*******************

   Operations to make enclosure are following:

`<C-c C-x a>'
     Enclose specified region as multipart/alternative.

`<C-c C-x p>'
     Enclose specified region as multipart/parallel.

`<C-c C-x m>'
     Enclose specified region as multipart/mixed.

`<C-c C-x d>'
     Enclose specified region as multipart/digest.

`<C-c C-x s>'
     Digital-sign to specified region. (cf. PGP)

`<C-c C-x e>'
     Encrypt to specified region. (cf. PGP)

`<C-c C-x q>'
     avoid to encode tags in specified region.  In other words, tags is
     interpreted as such string.  (In current version, it may be
     incomplete.  Maybe PGP-signature does not work for this enclosure.)

other operations of mime/editor-mode
************************************

   There are another operations in mime/editor-mode.

`<C-c C-c>'
     Send current editing message.

`<C-c C-x C-p>'
     Preview current editing message. (see
     mime/viewer-mode (tm-view-en))

`<C-c C-x C-z>'
     Exit mime/editor-mode. (<M-x mime/edit-again> is available to
     reedit.)

`<C-c C-x ?>'
     Display help message.

`<C-c C-x />'
     Set current editing message to enable automatic splitting or not.
     Form of automatic split messages is message/partial.

`<C-c C-x 7>'
     Set 7bit (see 7bit (tm-en)) to transfer level (see transfer level).

`<C-c C-x 8>'
     Set 8bit (see 8bit (tm-en)) to transfer level (see transfer level).

`<C-c C-x v>'
     Set current editing message to digital-sign or not. (cf.
     PGP)

`<C-c C-x h>'
     Set current editing message to encrypt or not. (cf. PGP)

Default media-type or encoding for inserted file
************************************************

   When `C-c C-x C-i' (`mime-editor/insert-file') is pressed, tag
parameters for inserted file, such as media-type or encoding, are
detected by variable `mime-file-types'.

   When `C-u' is followed by it or parameter is not found from the
variable, it asks from user.  (When `C-u' is followed by it, detected
value is used as default value)

   If you want to change default value for file names, please change
variable `mime-file-types'.

 - Variable: mime-file-types
     Specification of default value of tag for file name of inserted
     file.

     It is a list of following list:

          	(FILE_PAT TYPE SUBTYPE PARAMS ENCODING
          	 DISPOSITION_TYPE DISPOSITION_PARAMS)

     Each elements of the list are following:

    `FILE_PAT'
          regular expression of file name

    `TYPE'
          media type

    `SUBTYPE'
          media subtype

    `PARAMS'
          parameters of Content-Type field

    `ENCODING'
          Content-Transfer-Encoding

    `DISPOSITION_TYPE'
          disposition-type

    `DISPOSITION_PARAMS'
          parameters of Content-Disposition field

     Example: Specify application/rtf as default media type for `*.rtf'

          (call-after-loaded
           'tm-edit
           (lambda ()
             (set-alist 'mime-file-types
          	      "\\.rtf$"
          	      '("application" "rtf" nil nil
          		"attachment" (("filename" . file)))
          	      )))

transfer level
**************

   Contents inserted in a message are represented by 7bit (see
7bit (tm-en)), 8bit (see 8bit (tm-en)) or binary (see
binary (tm-en)).

   If a message is translated by 7bit-through MTA (see MTA (tm-en)),
there is no need to encode 7bit data, but 8bit and binary data must be
encoded to 7bit data.

   Similarly, if a message is translated by 8bit-through MTA, there is
no need to encode 7bit or 8bit data, but binary data must be encoded to
7bit or 8bit data.

*[Memo]*
     EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
     encoded by base64.  But I don't know EBCDIC. (^_^;

     Similarly, I wish ASCII-printable only MTA and code-conversion MTA
     disappeared. (^_^;

     Maybe there are binary-through MTA, but I think it is not major.

   *transfer level* represents how range data is available.  tm-edit
has a variable `mime-editor/transfer-level' to represent transfer level.

 - Variable: mime-editor/transfer-level
     transfer level.

     If transfer level of a data is over it, a data is encoded to 7bit.

     Currently, 7 or 8 is available.  Default value is 7.

     In extension plan, EBCDIC will be 5, ASCII printable only will be
     6, binary will be 9.  But it will not be implemented.

*[Memo]*
     transfer level is only for body, not for header (see header).
     RFC 1521 extends RFC 822 (see RFC 822 (tm-en)) to use 8bit data
     in body, but it requires to use us-ascii (see us-ascii (tm-en))
     in header.

Using non-ASCII characters in header
************************************

   RFC 1522 (see RFC 1522 (tm-en)) defines representation of
non-ASCII characters in header.

   It is a format called as *encoded-word* (see
encoded-word (tm-en)), it is available to represent every non-ASCII
characters by 7bit (see 7bit (tm-en)) to declare MIME charset (see
MIME charset (tm-en)).

If you can not allow encoded-word
=================================

   It is wrong to use "raw" non-ASCII characters in header not to use
encoded-word.  Because there are various kinds of coded character set
(see Coded character set (tm-en)) in the Internet, so we can not
distinguish them if MIME charset (see MIME charset (tm-en)) is not
declared.

   For example, we can not distinguish iso-8859-1 (see
iso-8859-1 (tm-en)) and iso-8859-2 (see iso-8859-2 (tm-en)) if MIME
charset is not declared.

   However you can not permit to use encoded-word, please set to
following variables:

 - Variable: mime/field-encoding-method-alist
     Association-list to specify field encoding method.  Its key is
     field-name, value is encoding method.

     field-name allows string or `t' meaning any fields.

     Encoding method allows following: `nil' means no-conversion,
     `mime' means to convert as encoded-word, symbol represent MIME
     charset means to convert as the coded character set instead of to
     convert as encoded-word.

     field-name is searched from string.  If it is not found, `t' is
     used.

     Default value of `mime/field-encoding-method-alist' is following:

          (("X-Nsubject" . iso-2022-jp-2)
           ("Newsgroups" . nil)
           (t            . mime)
           ))

   In addition, if you want to specify by coded character set instead of
field, please use `mime-eword/charset-encoding-alist'.  (cf. API about header)

Functions and variables about header
====================================

 - Command: mime/encode-message-header &optional CODE-CONVERSION
     It translate non-ASCII characters in message header of current
     buffer into network representation, such as encoded-words.

     If CODE-CONVERSION is non-`nil', field not encoded by encoded-word
     is converted by `mime/field-encoding-method-alist'.

 - Function: mime/encode-field STRING
     It encodes STRING into encoded-words as a field.

     Long lines are folded.

 - Function: mime-eword/encode-string STRING &optional COLUMN MODE
     It encodes STRING into encoded-words.

     Long lines are folded.

     COLUMN specifies start column.  If it is omitted, 0 is used.

     MODE specifies where STRING is in.  Available values are `text',
     `comment', `phrase'.  If it is omitted, `phrase' is used.

 - Variable: mime-eword/charset-encoding-alist
     Association-list of symbol represent MIME charset vs. nil, `"B"' or
     `"Q"'.

     `nil' means not to encode as encoded-word.  `"B"' means to use
     B-encoding.  `"Q"' means to use Q-encoding.

PGP
***

   tm-edit provides PGP encryption, signature and inserting public-key
features based on *PGP/MIME* (see PGP/MIME (tm-en)) (RFC 2015) or
*PGP-kazu* (see PGP-kazu (tm-en)) (draft-kazu-pgp-mime-00.txt).

   This feature requires pgp command and Mailcrypt package (see
(mailcrypt)).

   If you want to use this feature, please set `pgp-elkins' or
`pgp-kazu' to variable `mimed-editor/signing-type' and variable
`mime-editor/encrypting-type'.

   If `pgp-elkins' is specified, PGP/MIME is used.  If `pgp-kazu' is
specified, PGP-kazu is used.

 - Variable: mime-editor/signing-type
     Format of PGP signature.

     It allows `pgp-elkins' or `pgp-kazu'.

     Default value is `nil'.

 - Variable: mime-editor/encrypting-type
     Format of PGP encryption.

     It allows `pgp-elkins' or `pgp-kazu'.

     Default value is `nil'.

Acknowledgments
***************

   First of all, I thank UMEDA Masanobu for his work of `mime.el',
which is the origin of tm-edit, and permission to rewrite his work as
tm-edit.

   I thank members of two tm mailing lists, Japanese and English
version.