;; rs-gnus-unify.el -- Setup translation to, from and via Unicode
;; $Id: rs-gnus-unify.el,v 1.35 2007/10/20 14:45:25 ste Exp $

;; Author: Reiner Steib <reiner.steib@gmx.de>
;; Keywords: news i18n
;; X-URL: http://my.gnus.org/howtos/unify
;; X-URL: http://theotp1.physik.uni-ulm.de/~ste/comp/emacs/gnus/rs-gnus-unify.el

;;; This program is free software; you can redistribute it and/or modify
;;; it under the terms of the GNU General Public License as published by
;;; the Free Software Foundation; either version 2 of the License, or
;;; (at your option) any later version.
;;;
;;; This program is distributed in the hope that it will be useful,
;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;; GNU General Public License for more details.
;;;
;;; You should have received a copy of the GNU General Public License
;;; along with this program; if not, write to the Free Software
;;; Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

;;; Translation:

;; A german translation is available from:
;;
;; <URL: http://www.fhaun.de/files/rs-gnus-unify-german-doc.txt>
;;
;; Eine deutsche Übersetzung dieser Datei steht unter der oben genannten URL
;; zur Verfügung.

;;; Commentary:

;; The problem:
;;
;; For Emacs (and thus Gnus), an `Ä' from ISO-8859-1 [1] is different than an
;; `Ä' from ISO-8859-15 [1].  Thus, when you reply to a message, the quote may
;; contain characters from ISO-8859-1.  When you enter characters from
;; ISO-8859-15, you'll end up in a buffer that contains characters from
;; different charsets.  Therefore Gnus splits the message into ISO-8859-1 and
;; ISO-8859-15 parts.  Gnus will prompt you: "A message part needs to be split
;; into N charset parts.  Really send?".  Unfortunately users with other news-
;; and mailreaders don't like this kind of messages ("Content-Type:
;; multipart/mixed").
;;
;; [1] ISO-8859-1 (aka Latin-1) and ISO-8859-15 (aka Latin-9 or Latin-0) are
;; just examples here, though the most important ones in western Europe.
;;
;; The solution (for Emacs 21):
;;
;; `ucs-tables.el' provides a solution for by `unifying' equivalent characters
;; from those ISO-8859 character sets if possible.  See the documentation in
;; `ucs-tables.el' for more details.  For users of Emacs 21.1 and 21.2 the
;; proper setup of `ucs-tables.el' is a little bit tricky, so I try to give a
;; simple step by step how-to here.

;;; Preparation:

;; Required files for Emacs 21.1 or 21.2:
;;
;; - This file `rs-gnus-unify.el'.
;;
;; - `utf-8.el' and `ucs-tables.el'
;;
;;   You can get the files either from <URL:http://savannah.gnu.org>:
;;
;;   - `utf-8.el'
;;     <URL: http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/emacs/emacs/
;;     lisp/international/utf-8.el?rev=1.13&content-type=text/plain>
;;
;;   - `ucs-tables.el'
;;     <URL: http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/emacs/emacs/
;;     lisp/international/ucs-tables.el?rev=1.8&content-type=text/plain>
;;
;;   Note that more recent versions of `utf-8.el' and `ucs-tables.el' (newer
;;   than the above mentioned ones) may not work with Emacs 21.1 and 21.2.
;;   The version of `utf-8.el' shipped with 21.1 or 21.2 is _not_ sufficient.
;;   Moreover (because the code of `utf-8.el' is dumped into the emacs binary
;;   at build time), it's _not_ enough to replace `utf-8.el*' in the directory
;;   share/emacs/21.?/lisp/international by the new ones.
;;
;;   If you want to byte-compile the files (not necessary), you should use:
;;
;;   $ emacs -q -batch --no-site-file --multibyte -f batch-byte-compile \
;;       utf-8.el ucs-tables.el
;;
;; Required files for Emacs 21.3 or later:
;;
;; - Emacs 21.3 or later already contains suitable versions of `utf-8.el' and
;; `ucs-tables.el', so in that case shouldn't download them separately.
;; Additionally, unify-8859-on-encoding-mode is already enabled by default in
;; those versions.  unify-8859-on-decoding-mode is optional, so that
;; `rs-gnus-unify.el' isn't needed in this case.

;;; Installation:

;; Put `rs-gnus-unify.el' (together with `utf-8.el' and `ucs-tables.el' in
;; case of Emacs 21.1 or 21.2) in a directory that's at the beginning of your
;; `load-path', e.g. ~/lisp:
;;
;; ;; Make sure this path comes before system paths:
;; (setq load-path (nconc (list "~/lisp") load-path))
;;
;; To setup the unification, you'll need to put the following in your startup
;; file (usually ~/.emacs):
;;
;; (require 'rs-gnus-unify)
;;
;; That's all.
;;
;; To check wether the unification work, you can use the the preview function
;; in Gnus: `M-m P' "MML/Preview" (Gnus 5.9) or `C-c RET P'
;; "Attachment/Preview" (Gnus 5.10).  Using `C-u M-m P' (5.9) or `C-u C-c RET
;; P' (Gnus 5.10) you'll also see what charset Gnus will use to send the
;; message.
;;
;; Another very useful command is `C-u C-x =' which shows you the charset and
;; other information about the character at point.  Similar functions are
;; `describe-char-after' (Emacs 21.[1-3]) or `describe-char' (Emacs
;; 21.4).

;;; Known problems:

;; - Make sure it's done before any other language-, terminal- or
;;   coding-related setup (e.g. set-language-environment,
;;   set-terminal-coding-system or set-keyboard-coding-system).
;;
;; - It seems that with Gnus 5.9 from Emacs 21.[1-2] and a Latin-9 setup,
;;   unification doesn't work as expected, when answering to Latin-1 messages:
;;   Gnus is sending UTF-8 messages even if Latin-1 or Latin-9 would be
;;   possible.  But IMHO this is preferable over sending multipart/mixed.

;;; Thanks:

;; Special thanks to Kai Großjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE>.
;; This file is more or less a collection of his countless tips, tricks and
;; explanations concerning unification in de.comm.software.gnus and other
;; Gnus-related newsgroups.


;;; History:

;; revision 1.16/1.17/1.18:
;; Try to handle Emacs 21.3 and current CVS (21.3.50) correctly.
;; revision 1.27:
;; New function `rs-gnus-unify-use-dummy-translation'.
;; revision 1.29:
;; Update for Gnus 5.10.

;;; Code:

;; FIXME: Can somebody provide a setup for XEmacs?  Is it enough to say
;; `(latin-unity-install)'?  Any/which requirements (MULE, ...)?
(when (featurep 'xemacs)
  (error (concat "This file cannot be used with XEmacs.  "
		 "For XEmacs, use the `latin-unity' package instead")))

;; make dummy translation for iso-2022-7bit
;; http://article.gmane.org/gmane.emacs.devel/12754
(defun rs-gnus-unify-use-dummy-translation ()
  "Use dummy translation table for some coding systems.
Useful for Emacs ChangeLog files and the like."
  (coding-system-put 'iso-2022-7bit
		     'translation-table-for-decode
		     (make-translation-table)))

(cond
 ((<= emacs-major-version 20)
  (message "Sorry, Emacs version %s is not supported." emacs-major-version))
 ((< (string-to-number
      (progn
	(string-match "^[0-9.]+" mule-version)
	(match-string 0 mule-version)))
     ;; Emacs 23 (unicode) doesn't need unify-8859-on-decoding-mode.  The
     ;; MULE version of Emacs unicode is 6.0, cf
     ;; <http://article.gmane.org/gmane.emacs.devel/55704>: Emacs 22 and
     ;; multi-tty: "5.0 (SAKAKI)", emacs-unicode "6.0 (HANACHIRUSATO)".
     6.0)
  (let (mess)
    (setq mess "Requiring `ucs-tables'...")
    (message mess)
    ;; preloaded in 21.3, but require won't hurt.
    (if (require 'ucs-tables)
	(message "%sdone" mess)
      (message "%sfailed" mess))
    ;; utf-8 is dumped into the Emacs binary, so we need to load it
    ;; explicitly for Emacs 21.[12], but not for 21.3 or CVS versions >=
    ;; 21.3.50.  Couldn't find a feasable feature test, so use this:
    (unless (>= (+ (* emacs-major-version 10) emacs-minor-version) 213)
      (setq mess "Reloading `utf-8'...")
      (message mess)
      (if (load-library "utf-8")
	  (message "%sdone" mess)
	(message "%sfailed" mess)))
    (message "Switching on unify-8859-on-encoding-mode...")
    (unify-8859-on-encoding-mode 1)
    (message "Switching on unify-8859-on-decoding-mode...")
    (unify-8859-on-decoding-mode 1))
  (message "Unification set up."))
 (t ;; Unicode Emacs
  (message "Unification not necessary for this Emacs version")))

;;; provide ourself

(provide 'rs-gnus-unify)

;;; rs-gnus-unify.el ends here

;; Local Variables:
;; coding: iso-latin-1
;; sentence-end-double-space: t
;; colon-double-space: nil
;; End: