Subject: bug#8900: 24.0.50; please index mentioned coding systems in Emacs manual

From: "Drew Adams" <[email-masked]>
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)))))))