tm-edit 7.100 Reference Manual (English Version)

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 ((tm-en)Content-Disposition) (RFC 1806) supports

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

  * PGP (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 ((tm-en)tm-MUA), 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 ((tm-en)multipart) 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 ((tm-en)Content-Type field).  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 ((tm-en)multipart).  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 (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. ((tm-view-en)mime/viewer-mode)

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 ((tm-en)7bit) to transfer level (transfer level).

C-c C-x 8
     Set 8bit ((tm-en)8bit) to transfer level (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 ((tm-en)7bit), 8bit ((tm-en)8bit) or binary ((tm-en)binary).

If a message is translated by 7bit-through MTA ((tm-en)MTA), 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 (header).  RFC 1521 extends RFC 822 ((tm-en)RFC 822) to use 8bit data in body, but it requires to use us-ascii ((tm-en)us-ascii) in header.

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

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

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

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 ((tm-en)Coded character set) in the Internet, so we can not distinguish them if MIME charset ((tm-en)MIME charset) is not declared.

For example, we can not distinguish iso-8859-1 ((tm-en)iso-8859-1) and iso-8859-2 ((tm-en)iso-8859-2) 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 ((tm-en)PGP/MIME) (RFC 2015) or PGP-kazu ((tm-en)PGP-kazu) (draft-kazu-pgp-mime-00.txt).

This feature requires pgp command and Mailcrypt package ((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.