Package: emacs;
Reported by: "Drew Adams" <drew.adams <at> oracle.com>
Date: Mon, 20 Jun 2011 15:25:02 UTC
Severity: minor
Tags: fixed
Found in version 24.0.50
Done: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Bug is archived. No further changes may be made.
View this message in rfc822 format
From: "Drew Adams" <drew.adams <at> oracle.com> To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org> Cc: 8900 <at> debbugs.gnu.org Subject: bug#8900: 24.0.50; please index mentioned coding systems in Emacs manual Date: Fri, 1 Jul 2011 08:54:44 -0700
> > Maybe you were thinking of the `undecided, coding system'
> > entry in the Concept Index? That's close, but it is not
> > any of those I mentioned.
>
> Yes, that's the one I meant. And instead of adding all the
> `iso-latin-1-*' variations, I just added "`iso-latin-1',
> coding system".
>
> I think that should be sufficient for people who want to find these
> things in the index.
I disagree. These are real, implementation, user-visible, runtime names. This
is just like indexing command names or variable names or package names. The
exact name should appear in the index.
Consider, for instance, the use case that brought this to my attention:
I have updated various Emacs `describe-...' commands so that a link to their
coverage in the manuals is added to the *Help* buffer. This is based on finding
the term in question in the manual's index. The match naturally should be an
exact match against index entries.
See http://lists.gnu.org/archive/html/emacs-devel/2011-06/msg00368.html.
With a proper fix to this bug as I requested, these particular, literal names
would appear in the index, and I could then add `describe-coding-system' to my
updates. A user looking at the output of `describe-coding-system' for one of
these coding systems could click the link to get to its doc in the manual.
This is what I have in my TODO list:
;; ADD THIS ONE to help-fns+.el ONLY IF BUG #8900 is fixed.
;; REPLACE ORIGINAL in `mule-diag.el'
;;
;; Call `Info-make-manuals-xref' to create a cross-ref link to manuals.
;;
;;;###autoload
(when (> emacs-major-version 23); Before Emacs 24 no coding systems are indexed.
(defun describe-coding-system (coding-system)
"Display information about CODING-SYSTEM."
(interactive "zDescribe coding system (default current choices): ")
(require 'mule-diag)
(if (null coding-system)
(describe-current-coding-system)
(help-setup-xref (list #'describe-coding-system coding-system)
(called-interactively-p 'interactive))
(with-output-to-temp-buffer (help-buffer)
(print-coding-system-briefly coding-system 'doc-string)
(let ((type (coding-system-type coding-system))
;; Fixme: use this
(extra-spec (coding-system-plist coding-system)))
(princ "Type: ")
(princ type)
(cond ((eq type 'undecided)
(princ " (do automatic conversion)"))
((eq type 'utf-8)
(princ " (UTF-8: Emacs internal multibyte form)"))
((eq type 'utf-16)
;; (princ " (UTF-16)")
)
((eq type 'shift-jis)
(princ " (Shift-JIS, MS-KANJI)"))
((eq type 'iso-2022)
(princ " (variant of ISO-2022)\n")
(princ "Initial designations:\n")
(print-designation (coding-system-get coding-system
:designation))
(when (coding-system-get coding-system :flags)
(princ "Other specifications: \n ")
(apply #'print-list
(coding-system-get coding-system :flags))))
((eq type 'charset)
(princ " (charset)"))
((eq type 'ccl)
(princ " (do conversion by CCL program)"))
((eq type 'raw-text)
(princ " (text with random binary characters)"))
((eq type 'emacs-mule)
(princ " (Emacs 21 internal encoding)"))
((eq type 'big5))
(t (princ ": invalid coding-system.")))
(princ "\nEOL type: ")
(let ((eol-type (coding-system-eol-type coding-system)))
(cond ((vectorp eol-type)
(princ "Automatic selection from:\n\t")
(princ eol-type)
(princ "\n"))
((or (null eol-type) (eq eol-type 0)) (princ "LF\n"))
((eq eol-type 1) (princ "CRLF\n"))
((eq eol-type 2) (princ "CR\n"))
(t (princ "invalid\n")))))
(let ((postread (coding-system-get coding-system
:post-read-conversion)))
(when postread
(princ "After decoding text normally,")
(princ " perform post-conversion using the function: ")
(princ "\n ")
(princ postread)
(princ "\n")))
(let ((prewrite (coding-system-get coding-system
:pre-write-conversion)))
(when prewrite
(princ "Before encoding text normally,")
(princ " perform pre-conversion using the function: ")
(princ "\n ")
(princ prewrite)
(princ "\n")))
(with-current-buffer standard-output
(let ((charsets (coding-system-charset-list coding-system)))
(when (and (not (eq (coding-system-base coding-system) 'raw-text))
charsets)
(cond
((eq charsets 'iso-2022)
(insert "This coding system can encode all ISO 2022
charsets."))
((eq charsets 'emacs-mule)
(insert "This coding system can encode all emacs-mule
charsets."""))
(t
(insert "This coding system encodes the following charsets:\n
")
(while charsets
(insert " " (symbol-name (car charsets)))
(search-backward (symbol-name (car charsets)))
(help-xref-button 0 'help-character-set (car charsets))
(goto-char (point-max))
(setq charsets (cdr charsets)))))))
(when (boundp 'Info-virtual-files) ; Emacs 23.2+
(Info-make-manuals-xref coding-system)))))))
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.