From 4cfb4869e6871f6d5893f69a542ee5be45122ee0 Mon Sep 17 00:00:00 2001 From: Reiner Steib Date: Thu, 23 Oct 2003 13:05:08 +0000 Subject: [PATCH] * emacs-mime.texi: Markup: Use @acronym for MML and MIME. * message.texi: Ditto. * gnus.texi: Ditto. --- texi/ChangeLog | 8 ++++++ texi/emacs-mime.texi | 56 ++++++++++++++++++++------------------- texi/gnus.texi | 18 ++++++------- texi/message.texi | 63 +++++++++++++++++++++++--------------------- 4 files changed, 79 insertions(+), 66 deletions(-) diff --git a/texi/ChangeLog b/texi/ChangeLog index 8607ca4ed..00460c200 100644 --- a/texi/ChangeLog +++ b/texi/ChangeLog @@ -1,3 +1,11 @@ +2003-10-23 Reiner Steib + + * emacs-mime.texi: Markup: Use @acronym for MML and MIME. + + * message.texi: Ditto. + + * gnus.texi: Ditto. + 2003-10-23 Simon Josefsson * emacs-mime.texi (MML Definition): Add format. diff --git a/texi/emacs-mime.texi b/texi/emacs-mime.texi index d45142c4c..0a3329625 100644 --- a/texi/emacs-mime.texi +++ b/texi/emacs-mime.texi @@ -93,7 +93,7 @@ read at least RFC2045 and RFC2047. @menu * Decoding and Viewing:: A framework for decoding and viewing. -* Composing:: MML; a language for describing @acronym{MIME} parts. +* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. * Interface Functions:: An abstraction over the basic functions. * Basic Functions:: Utility and basic parsing functions. * Standards:: A summary of RFCs and working documents used. @@ -508,9 +508,10 @@ tell it to insert, but it also sets things up so that the text can be @cindex MML @cindex MIME Meta Language -Creating a @acronym{MIME} message is boring and non-trivial. Therefore, a -library called @code{mml} has been defined that parses a language called -MML (@acronym{MIME} Meta Language) and generates @acronym{MIME} messages. +Creating a @acronym{MIME} message is boring and non-trivial. Therefore, +a library called @code{mml} has been defined that parses a language +called @acronym{MML} (@acronym{MIME} Meta Language) and generates +@acronym{MIME} messages. @findex mml-generate-mime The main interface function is @code{mml-generate-mime}. It will @@ -518,12 +519,12 @@ examine the contents of the current (narrowed-to) buffer and return a string containing the @acronym{MIME} message. @menu -* Simple MML Example:: An example MML document. -* MML Definition:: All valid MML elements. -* Advanced MML Example:: Another example MML document. +* Simple MML Example:: An example @acronym{MML} document. +* MML Definition:: All valid @acronym{MML} elements. +* Advanced MML Example:: Another example @acronym{MML} document. * Encoding Customization:: Variables that affect encoding. * Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. -* Conversion:: Going from @acronym{MIME} to MML and vice versa. +* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. * Flowed text:: Soft and hard newlines. @end menu @@ -565,10 +566,10 @@ Content-Type: text/enriched @node MML Definition @section MML Definition -The MML language is very simple. It looks a bit like an SGML +The @acronym{MML} language is very simple. It looks a bit like an SGML application, but it's not. -The main concept of MML is the @dfn{part}. Each part can be of a +The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a different type or use a different charset. The way to delineate a part is with a @samp{<#part ...>} tag. Multipart parts can be introduced with the @samp{<#multipart ...>} tag. Parts are ended by the @@ -583,8 +584,8 @@ Each tag can contain zero or more parameters on the form but that's not necessary unless the value contains white space. So @samp{filename=/home/user/#hello$^yes} is perfectly valid. -The following parameters have meaning in MML; parameters that have no -meaning are ignored. The MML parameter names are the same as the +The following parameters have meaning in @acronym{MML}; parameters that have no +meaning are ignored. The @acronym{MML} parameter names are the same as the @acronym{MIME} parameter names; the things in the parentheses say which header it will be used in. @@ -637,11 +638,11 @@ default key used. The size (in octets) of the part (@code{Content-Disposition}). @item sign -What technology to sign this MML part with (@code{smime}, @code{pgp} +What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} or @code{pgpmime}) @item encrypt -What technology to encrypt this MML part with (@code{smime}, +What technology to encrypt this @acronym{MML} part with (@code{smime}, @code{pgp} or @code{pgpmime}) @end table @@ -813,7 +814,7 @@ default is As an example, if you do not want to have ISO-8859-1 characters quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to this variable. You can override this setting on a per-message basis -by using the @code{encoding} MML tag (@pxref{MML Definition}). +by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). @item mm-coding-system-priorities @vindex mm-coding-system-priorities @@ -825,7 +826,7 @@ an alias in this variable). For example, if you have configured Emacs to prefer UTF-8, but wish that outgoing messages should be sent in ISO-8859-1 if possible, you can set this variable to @code{(iso-latin-1)}. You can override this setting on a per-message -basis by using the @code{charset} MML tag (@pxref{MML Definition}). +basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}). @item mm-content-transfer-encoding-defaults @vindex mm-content-transfer-encoding-defaults @@ -835,7 +836,7 @@ used except, e.g., when other requirements force a safer encoding @acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for each case the most efficient of quoted-printable and base64 should be used. You can override this setting on a per-message basis by using -the @code{encoding} MML tag (@pxref{MML Definition}). +the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). @item mm-use-ultra-safe-encoding @vindex mm-use-ultra-safe-encoding @@ -853,8 +854,9 @@ encoding messages that are to be digitally signed). @section Charset Translation @cindex charsets -During translation from MML to @acronym{MIME}, for each @acronym{MIME} part which -has been composed inside Emacs, an appropriate charset has to be chosen. +During translation from @acronym{MML} to @acronym{MIME}, for each +@acronym{MIME} part which has been composed inside Emacs, an appropriate +charset has to be chosen. @vindex mail-parse-charset If you are running a non-@sc{mule} Emacs, this process is simple: If the @@ -895,7 +897,7 @@ messages. You can modify this by altering the Customization}). The charset to be used can be overridden by setting the @code{charset} -MML tag (@pxref{MML Definition}) when composing the message. +@acronym{MML} tag (@pxref{MML Definition}) when composing the message. The encoding of characters (quoted-printable, 8bit etc) is orthogonal to the discussion here, and is controlled by the variables @@ -907,15 +909,15 @@ Customization}). @section Conversion @findex mime-to-mml -A (multipart) @acronym{MIME} message can be converted to MML with the -@code{mime-to-mml} function. It works on the message in the current -buffer, and substitutes MML markup for @acronym{MIME} boundaries. -Non-textual parts do not have their contents in the buffer, but instead -have the contents in separate buffers that are referred to from the MML -tags. +A (multipart) @acronym{MIME} message can be converted to @acronym{MML} +with the @code{mime-to-mml} function. It works on the message in the +current buffer, and substitutes @acronym{MML} markup for @acronym{MIME} +boundaries. Non-textual parts do not have their contents in the buffer, +but instead have the contents in separate buffers that are referred to +from the @acronym{MML} tags. @findex mml-to-mime -An MML message can be converted back to @acronym{MIME} by the +An @acronym{MML} message can be converted back to @acronym{MIME} by the @code{mml-to-mime} function. These functions are in certain senses ``lossy''---you will not get back diff --git a/texi/gnus.texi b/texi/gnus.texi index deb070717..4f6a380e1 100644 --- a/texi/gnus.texi +++ b/texi/gnus.texi @@ -11929,9 +11929,9 @@ are in reply to encrypted messages. Gnus offers @code{gnus-message-replysignencrypted} (on by default) will sign automatically encrypted messages. -Instructing MML to perform security operations on a @acronym{MIME} part is -done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c -C-m c} key map for encryption, as follows. +Instructing @acronym{MML} to perform security operations on a +@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for +signing and the @kbd{C-c C-m c} key map for encryption, as follows. @table @kbd @@ -11974,7 +11974,7 @@ Digitally encrypt current message using @acronym{PGP/MIME}. @item C-c C-m C-n @kindex C-c C-m C-n @findex mml-unsecure-message -Remove security related MML tags from message. +Remove security related @acronym{MML} tags from message. @end table @@ -25553,12 +25553,12 @@ This change was made to avoid conflict with the standard binding of @code{back-to-indentation}, which is also useful in message mode. @item -The default for message-forward-show-mml changed to symbol @code{best}. +The default for @code{message-forward-show-mml} changed to symbol @code{best}. -The behaviour for the @code{best} value is to show MML (i.e., convert MIME -to MML) when appropriate. MML will not be used when forwarding signed -or encrypted messages, as the conversion invalidate the digital -signature. +The behaviour for the @code{best} value is to show @acronym{MML} (i.e., +convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be +used when forwarding signed or encrypted messages, as the conversion +invalidate the digital signature. @end itemize @iftex diff --git a/texi/message.texi b/texi/message.texi index 4f8315f12..b8e937fd4 100644 --- a/texi/message.texi +++ b/texi/message.texi @@ -831,7 +831,7 @@ The most typical thing users want to use the multipart things in be done with the @kbd{C-c C-a} command, which will prompt for a file name and a @acronym{MIME} type. -You can also create arbitrarily complex multiparts using the MML +You can also create arbitrarily complex multiparts using the @acronym{MML} language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME Manual}). @@ -877,12 +877,13 @@ Libidn} installed in order to use this functionality. @cindex encrypt @cindex secure -Using the MML language, Message is able to create digitally signed and -digitally encrypted messages. Message (or rather MML) currently -support @acronym{PGP} (RFC 1991), @acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. -Instructing MML to perform security operations on a @acronym{MIME} part is -done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c -C-m c} key map for encryption, as follows. +Using the @acronym{MML} language, Message is able to create digitally +signed and digitally encrypted messages. Message (or rather +@acronym{MML}) currently support @acronym{PGP} (RFC 1991), +@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. Instructing +@acronym{MML} to perform security operations on a @acronym{MIME} part is +done using the @kbd{C-c C-m s} key map for signing and the @kbd{C-c C-m +c} key map for encryption, as follows. @table @kbd @@ -925,21 +926,22 @@ Digitally encrypt current message using @acronym{PGP/MIME}. @item C-c C-m C-n @kindex C-c C-m C-n @findex mml-unsecure-message -Remove security related MML tags from message. +Remove security related @acronym{MML} tags from message. @end table These commands do not immediately sign or encrypt the message, they -merely insert the proper MML secure tag to instruct the MML engine to -perform that operation when the message is actually sent. They may -perform other operations too, such as locating and retrieving a -@acronym{S/MIME} certificate of the person you wish to send encrypted mail -to. When the mml parsing engine converts your MML into a properly -encoded @acronym{MIME} message, the secure tag will be replaced with either -a part or a multipart tag. If your message contains other mml parts, -a multipart tag will be used; if no other parts are present in your -message a single part tag will be used. This way, message mode will -do the Right Thing (TM) with signed/encrypted multipart messages. +merely insert the proper @acronym{MML} secure tag to instruct the +@acronym{MML} engine to perform that operation when the message is +actually sent. They may perform other operations too, such as locating +and retrieving a @acronym{S/MIME} certificate of the person you wish to +send encrypted mail to. When the mml parsing engine converts your +@acronym{MML} into a properly encoded @acronym{MIME} message, the secure +tag will be replaced with either a part or a multipart tag. If your +message contains other mml parts, a multipart tag will be used; if no +other parts are present in your message a single part tag will be used. +This way, message mode will do the Right Thing (TM) with +signed/encrypted multipart messages. Since signing and especially encryption often is used when sensitive information is sent, you may want to have some way to ensure that your @@ -971,24 +973,25 @@ programs are required to make things work, and some small general hints. modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and so on. -The @acronym{S/MIME} support in Message (and MML) require OpenSSL. OpenSSL -performs the actual @acronym{S/MIME} sign/encrypt operations. OpenSSL can -be found at @uref{http://www.openssl.org/}. OpenSSL 0.9.6 and later -should work. Version 0.9.5a cannot extract mail addresses from -certificates, and it insert a spurious CR character into @acronym{MIME} -separators so you may wish to avoid it if you would like to avoid -being regarded as someone who send strange mail. (Although by sending -@acronym{S/MIME} messages you've probably already lost that contest.) +The @acronym{S/MIME} support in Message (and @acronym{MML}) require +OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt +operations. OpenSSL can be found at @uref{http://www.openssl.org/}. +OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail +addresses from certificates, and it insert a spurious CR character into +@acronym{MIME} separators so you may wish to avoid it if you would like +to avoid being regarded as someone who send strange mail. (Although by +sending @acronym{S/MIME} messages you've probably already lost that +contest.) To be able to send encrypted mail, a personal certificate is not -required. Message (MML) need a certificate for the person to whom you +required. Message (@acronym{MML}) need a certificate for the person to whom you wish to communicate with though. You're asked for this when you type @kbd{C-c C-m c s}. Currently there are two ways to retrieve this certificate, from a local file or from DNS. If you chose a local file, it need to contain a X.509 certificate in @acronym{PEM} format. If you chose DNS, you're asked for the domain name where the certificate is stored, the default is a good guess. To my belief, -Message (MML) is the first mail agent in the world to support +Message (@acronym{MML}) is the first mail agent in the world to support retrieving @acronym{S/MIME} certificates from DNS, so you're not likely to find very many certificates out there. At least there should be one, stored at the domain @code{simon.josefsson.org}. LDAP @@ -998,8 +1001,8 @@ command line to retrieve a certificate into a file and use it.) As for signing messages, OpenSSL can't perform signing operations without some kind of configuration. Especially, you need to tell it -where your private key and your certificate is stored. MML uses an -Emacs interface to OpenSSL, aptly named @code{smime.el}, and it +where your private key and your certificate is stored. @acronym{MML} +uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it contain a @code{custom} group used for this configuration. So, try @kbd{M-x customize-group RET smime RET} and look around. -- 2.25.1