Mercurial > hg > xemacs-beta

<!doctype sinfo system>
<!-- $Id: tm-edit-en.sgml,v 1.2 1996/12/28 21:03:28 steve Exp $ -->
<head>
<title>tm-edit 7.100 Reference Manual (English Version)
<author>MORIOKA Tomohiko <mail>morioka@jaist.ac.jp</mail>
<date>1996/12/25

<toc>
</head>

<body>

<abstract>
<p>
This file documents tm-edit, a MIME composer for GNU Emacs.
</abstract>


<h1> What is tm-edit?
<node> Introduction
<p>
<concept>tm-edit</concept> is a general MIME composer for GNU Emacs.
<p>
tm-edit is based on mime.el by UMEDA Masanobu
<mail>umerin@mse.kyutech.ac.jp</mail>, who is famous as the author of
GNUS.  tm-edit expands following points from <file>mime.el</file>:

<ul>
<li>
based on RFC 1521/1522
<li>
<a file="tm-en" node="Content-Disposition">Content-Disposition
field</a> (RFC 1806) supports
<li>
nested <a file="tm-en" node="multipart">multi-part message</a>
<li>
<dref>PGP</dref> (PGP/MIME (RFC 2015) based on security multipart (RFC
1847) and application/pgp based on traditional PGP)
<li>
strength automatic specification for parameter of file type
</ul>

<p>
In <dref file="tm-en">tm-MUA</dref>, you can edit MIME message easily
to use tm-edit.


<h1> mime/editor-mode
<node> mime/editor-mode
<p>
<concept>mime/editor-mode</concept> is a minor mode to compose MIME
message.  In this mode, <concept>tag</concept> represents various
kinds of data, you can edit <a file="tm-en" node="multipart">multi
part</a> message.
<p>
There are 2 kinds of tags:

<ul>
<li> single-part tag
<li> multi-part tag
</ul>
<p>
single-part tag represents single part, this form is following:

<verb>
        --[[TYPE/SUBTYPE;PARAMETERS][ENCODING]
        OPTIONAL-FIELDS]
</verb>
<p>
TYPE/SUBTYPE and PARAMETERS indicates type/subtype and parameters of
<dref file="tm-en">Content-Type field</dref>.  TYPE/SUBTYPE is
required, PARAMETERS is optional.
<p>
ENCODING indicates Content-Transfer-Encoding field.  It is optional
too.
<p>
OPTIONAL-FIELDS is to represent another fields except Content-Type
field and Content-Transfer-Encoding field.
<p>
multi-part tags represent <a file="tm-en" node="multipart">multi
part</a>.  They consist of a pair of <concept>multi-part beginning
tag</concept> and <concept>multi-part ending tag</concept>.
<p>
multi-part beginning tag's form is following:
<p>
<verb>
        --<<TYPE>>-{
</verb>
<p>
multi-part ending tag's form is following:
<p>
<verb>
        --}-<<TYPE>>
</verb>
<p>
A region from multi-part beginning tag to multi-part ending tag is
called as <concept>enclosure</concept>.


<h1> single-part operations
<node> single-part operations
<p>
Operations to make single-part are following:

<kl>
<kt>C-c C-x C-t
<kd>
Insert single-part tag indicates text part.
</kd>
<kt>C-c C-x C-i
<kd>
Insert file as a MIME attachment.  If <kbd>C-u</kbd> is followed by
it, it asks media-type, subtype or encoding even if their default
values are specified. <cf node="tag specification for inserted file">
</kd>
<kt>C-c C-x C-e
<kd>
Insert external part.
</kd>
<kt>C-c C-x C-v
<kd>
Record audio input until <kbd>C-g</kbd> is pressed, and insert as a
audio part. (It requires /dev/audio in default.)
</kd>
<kt>C-c C-x C-y
<kd>
Insert current (mail or news) message. (It is MUA depended.)
</kd>
<kt>C-c C-x C-m
<kd>
Insert mail message. (It is MUA depended.)
</kd>
<dt><key>C-c C-x C-w</key>, <key>C-c C-x C-s</key>
<dd>
Insert signature.
</dd>
<kt>C-c C-x C-k
<kd>
Insert <dref>PGP</dref> public key. (It requires Mailcrypt package.)
</kd>
<kt>C-c C-x t
<kd>
Insert any single-part tag.
</kd>
</kl>


<h1> enclosure operation
<node> enclosure operation
<p>
Operations to make enclosure are following:

<kl>
<kt>C-c C-x a
<kd>
Enclose specified region as multipart/alternative.
</kd>
<kt>C-c C-x p
<kd>
Enclose specified region as multipart/parallel.
</kd>
<kt>C-c C-x m
<kd>
Enclose specified region as multipart/mixed.
</kd>
<kt>C-c C-x d
<kd>
Enclose specified region as multipart/digest.
</kd>
<kt>C-c C-x s
<kd>
Digital-sign to specified region. <cf node="PGP">
</kd>
<kt>C-c C-x e
<kd>
Encrypt to specified region. <cf node="PGP">
<kt>C-c C-x q
<kd>
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.)
</kl>


<h1> other operations of mime/editor-mode
<node> other operations of mime/editor-mode
<p>
There are another operations in mime/editor-mode.

<kl>
<kt>C-c C-c
<kd>
Send current editing message.
</kd>
<kt>C-c C-x C-p
<kd>
Preview current editing message. (<ref file="tm-view-en"
node="mime/viewer-mode">)
</kd>
<kt>C-c C-x C-z
<kd>
Exit mime/editor-mode. (<key>M-x mime/edit-again</key> is available to
reedit.)
</kd>
<kt>C-c C-x ?
<kd>
Display help message.
</kd>
<kt>C-c C-x /
<kd>
Set current editing message to enable automatic splitting or not.
Form of automatic split messages is message/partial.
</kd>
<kt>C-c C-x 7
<kd>
Set <dref file="tm-en">7bit</dref> to <dref>transfer level</dref>.
</kd>
<kt>C-c C-x 8
<kd>
Set <dref file="tm-en">8bit</dref> to <dref>transfer level</dref>.
</kd>
<kt>C-c C-x v
<kd>
Set current editing message to digital-sign or not. <cf node="PGP">
</kd>
<kt>C-c C-x h
<kd>
Set current editing message to encrypt or not. <cf node="PGP">
</kl>


<h1> Default media-type or encoding for inserted file
<node> tag specification for inserted file
<p>
When <kbd>C-c C-x C-i</kbd> (<code>mime-editor/insert-file</code>) is
pressed, tag parameters for inserted file, such as media-type or
encoding, are detected by variable <code>mime-file-types</code>.
<p>
When <kbd>C-u</kbd> is followed by it or parameter is not found from
the variable, it asks from user.  (When <kbd>C-u</kbd> is followed by
it, detected value is used as default value)
<p>
If you want to change default value for file names, please change
variable <code>mime-file-types</code>.


<defvar name="mime-file-types">
<p>
Specification of default value of tag for file name of inserted file.
<p>
It is a list of following list:

<lisp>
	(FILE_PAT TYPE SUBTYPE PARAMS ENCODING
	 DISPOSITION_TYPE DISPOSITION_PARAMS)
</lisp>

Each elements of the list are following:

<dl>
<dt>FILE_PAT
<dd>regular expression of file name
<dt>TYPE
<dd>media type
<dt>SUBTYPE
<dd>media subtype
<dt>PARAMS
<dd>parameters of Content-Type field
<dt>ENCODING
<dd>Content-Transfer-Encoding
<dt>DISPOSITION_TYPE
<dd>disposition-type
<dt>DISPOSITION_PARAMS
<dd>parameters of Content-Disposition field
</dl>

<noindent>
Example: Specify application/rtf as default media type for
<file>*.rtf</file>

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


<h1> transfer level
<node> transfer level
<p>
Contents inserted in a message are represented by <dref
file="tm-en">7bit</dref>, <dref file="tm-en">8bit</dref> or <dref
file="tm-en">binary</dref>.
<p>
If a message is translated by 7bit-through <dref
file="tm-en">MTA</dref>, there is no need to encode 7bit data, but
8bit and binary data must be encoded to 7bit data.
<p>
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.
<p>
<memo>
EBCDIC MTA breaks 7bit data, so in this case, 7bit data must be
encoded by base64.  But I don't know EBCDIC. (^_^;
<p>
Similarly, I wish ASCII-printable only MTA and code-conversion MTA
disappeared. (^_^;
<p>
Maybe there are binary-through MTA, but I think it is not major.
</memo>
<p>
<concept>transfer level</concept> represents how range data is
available.  tm-edit has a variable
<code>mime-editor/transfer-level</code> to represent transfer level.


<defvar name="mime-editor/transfer-level">
<p>
transfer level.
<p>
If transfer level of a data is over it, a data is encoded to 7bit.
<p>
Currently, 7 or 8 is available.  Default value is 7.
<p>
In extension plan, EBCDIC will be 5, ASCII printable only will be 6,
binary will be 9.  But it will not be implemented.
</defvar>


<memo>
transfer level is only for body, not for <a node="header">header</a>.
RFC 1521 extends <dref file="tm-en">RFC 822</dref> to use 8bit data in
body, but it requires to use <dref file="tm-en">us-ascii</dref> in
header.
</memo>


<h1> Using non-ASCII characters in header
<node> header
<p>
<dref file="tm-en">RFC 1522</dref> defines representation of non-ASCII
characters in header.
<p>
It is a format called as <a file="tm-en"
node="encoded-word"><concept>encoded-word</concept></a>, it is
available to represent every non-ASCII characters by <dref
file="tm-en">7bit</dref> to declare <dref file="tm-en">MIME
charset</dref>.


<h2> If you can not allow encoded-word
<node> evil setting in header
<p>
It is wrong to use ``raw'' non-ASCII characters in header not to use
encoded-word.  Because there are various kinds of <a file="tm-en"
node="Coded character set">coded character set</a> in the Internet, so
we can not distinguish them if <dref file="tm-en">MIME charset</dref>
is not declared.
<p>
For example, we can not distinguish <dref
file="tm-en">iso-8859-1</dref> and <dref
file="tm-en">iso-8859-2</dref> if MIME charset is not declared.
<p>
However you can not permit to use encoded-word, please set to
following variables:


<defvar name="mime/field-encoding-method-alist">
<p>
Association-list to specify field encoding method.  Its key is
field-name, value is encoding method.
<p>
field-name allows string or <code>t</code> meaning any fields.
<p>
Encoding method allows following: <code>nil</code> means
no-conversion, <code>mime</code> 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.
<p>
field-name is searched from string.  If it is not found,
<code>t</code> is used.
<p>
Default value of <code>mime/field-encoding-method-alist</code> is
following:

<lisp>
(("X-Nsubject" . iso-2022-jp-2)
 ("Newsgroups" . nil)
 (t            . mime)
 ))
</lisp>
</defvar>

<p>
In addition, if you want to specify by coded character set instead of
field, please use <code>mime-eword/charset-encoding-alist</code>.
<cf node="API about header">


<h2> Functions and variables about header
<node> API about header
<p>
<define type="Command" name="mime/encode-message-header">
<opts> code-conversion
<p>
It translate non-ASCII characters in message header of current buffer
into network representation, such as encoded-words.
<p>
If <var>code-conversion</var> is non-<code>nil</code>, field not
encoded by encoded-word is converted by
<code>mime/field-encoding-method-alist</code>.
</define>

<defun name="mime/encode-field">
<args> string
<p>
It encodes <var>string</var> into encoded-words as a field.
<p>
Long lines are folded.
</defun>

<defun name="mime-eword/encode-string">
<args> string <opts> column mode
<p>
It encodes <var>string</var> into encoded-words.
<p>
Long lines are folded.
<p>
<var>column</var> specifies start column.  If it is omitted, 0 is
used.
<p>
<var>mode</var> specifies where <var>string</var> is in.  Available
values are <code>text</code>, <code>comment</code>,
<code>phrase</code>.  If it is omitted, <code>phrase</code> is used.
</defun>

<defvar name="mime-eword/charset-encoding-alist">
<p>
Association-list of symbol represent MIME charset vs. nil,
<code>"B"</code> or <code>"Q"</code>.
<p>
<code>nil</code> means not to encode as encoded-word.
<code>"B"</code> means to use B-encoding.
<code>"Q"</code> means to use Q-encoding.
</defvar>


<h1> PGP
<node> PGP
<p>
tm-edit provides PGP encryption, signature and inserting public-key
features based on <a file="tm-en"
node="PGP/MIME"><concept>PGP/MIME</concept></a> (RFC 2015) or <a
file="tm-en" node="PGP-kazu"><concept>PGP-kazu</concept></a>
(draft-kazu-pgp-mime-00.txt).
<p>
This feature requires pgp command and <a file="mailcrypt">Mailcrypt
package</a>.
<p>
If you want to use this feature, please set <code>pgp-elkins</code> or
<code>pgp-kazu</code> to variable
<code>mimed-editor/signing-type</code> and variable
<code>mime-editor/encrypting-type</code>.
<p>
If <code>pgp-elkins</code> is specified, PGP/MIME is used.  If
<code>pgp-kazu</code> is specified, PGP-kazu is used.


<defvar name="mime-editor/signing-type">
<p>
Format of PGP signature.
<p>
It allows <code>pgp-elkins</code> or <code>pgp-kazu</code>.
<p>
Default value is <code>nil</code>.
</defvar>

<defvar name="mime-editor/encrypting-type">
<p>
Format of PGP encryption.
<p>
It allows <code>pgp-elkins</code> or <code>pgp-kazu</code>.
<p>
Default value is <code>nil</code>.
</defvar>


<h1> Acknowledgments
<node> Acknowledgments
<p>
First of all, I thank UMEDA Masanobu for his work of
<file>mime.el</file>, which is the origin of tm-edit, and permission
to rewrite his work as tm-edit.
<p>
I thank members of two tm mailing lists, Japanese and English version.


<h1> Concept Index
<node> Concept Index

<cindex>


<h1> Function Index
<node> Function Index

<findex>


<h1> Variable Index
<node> Variable Index

<vindex>

</body>
author	cvs
date	Mon, 13 Aug 2007 09:28:38 +0200
parents	c0c698873ce1
children