[AUCTeX-devel] [elpa] externals/auctex f9e6e4b 32/69: New function for reading documentation with texdoc

[Tassilo Horn]

branch: externals/auctex
commit f9e6e4b8528df03a7810910e7dc2c28b5806c506
Author: Mosè Giordano <address@hidden>
Commit: Mosè Giordano <address@hidden>

    New function for reading documentation with texdoc
    
    * tex.el (TeX-documentation-texdoc): New function.
    (TeX-common-menu-entries): Replace `TeX-doc' with
    `TeX-documentation-texdoc'.
    (TeX-mode-map): Ditto.
    * doc/auctex.texi (Documentation): Document `TeX-documentation-texdoc'
    in place of `TeX-doc'.
    * doc/changes.texi: Mention `TeX-documentation-texdoc'.
---
 doc/auctex.texi  |   15 +++++------
 doc/changes.texi |   12 ++++++++-
 tex.el           |   71 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 86 insertions(+), 12 deletions(-)

diff --git a/doc/auctex.texi b/doc/auctex.texi
index 39125c9..c8e35a3 100644
--- a/doc/auctex.texi
+++ b/doc/auctex.texi
@@ -12,7 +12,7 @@ This manual is for @AUCTeX{}
 (version @value{VERSION} from @value{UPDATED}),
 a sophisticated TeX environment for Emacs.
 
-Copyright @copyright{} 1992-1995, 2001, 2002, 2004-2015
+Copyright @copyright{} 1992-1995, 2001, 2002, 2004-2016
 Free Software Foundation, Inc.
 
 @quotation
@@ -3523,16 +3523,15 @@ before it is actually done.  If non-nil, ask before 
deleting files.
 @section Documentation about macros and packages
 @cindex Documentation
 
address@hidden Command TeX-doc
address@hidden Command TeX-documentation-texdoc
 @kindex C-c ?
-(@kbd{C-c ?})  Get documentation about macros, packages or @TeX{} &
-Co. in general.  The function will prompt for the name of a command or
-manual, providing a list of available keywords for completion.  If point
-is on a command or word with available documentation, this will be
+(@kbd{C-c ?})  Get documentation about the packages installed on your
+system, using @samp{texdoc} to find the manuals.  The function will
+prompt for the name of packages.  If point is on a word, this will be
 suggested as default.
 
-In case no documentation could be found, a prompt for querying the
address@hidden program is shown, should the latter be available.
+If the command is called with a prefix argument, you will be shown a
+list of manuals of the given package among to choose.
 
 The command can be invoked by the key binding mentioned above as well as
 the @samp{Find Documentation...} entry in the mode menu.
diff --git a/doc/changes.texi b/doc/changes.texi
index a48e7ab..2905400 100644
--- a/doc/changes.texi
+++ b/doc/changes.texi
@@ -1,5 +1,5 @@
 @c This is part of the AUCTeX manual.
address@hidden Copyright (C) 1994-2002, 2004-2010, 2012-2015 Free Software
address@hidden Copyright (C) 1994-2002, 2004-2010, 2012-2016 Free Software
 @c Foundation, Inc.
 @c See file auctex.texi for copying conditions.
 @include macros.texi
@@ -8,6 +8,16 @@
 
 @end ifset
 
address@hidden News since 11.89
+
address@hidden @bullet
address@hidden
+A new function, @code{TeX-documentation-texdoc}, for reading
+documentation with @samp{texdoc} has been added.  @code{TeX-doc} is
+still available but now @kbd{C-c ?} runs
address@hidden
address@hidden itemize
+
 @heading News in 11.89
 
 @itemize @bullet
diff --git a/tex.el b/tex.el
index 7f464b3..244fa54 100644
--- a/tex.el
+++ b/tex.el
@@ -1,6 +1,6 @@
 ;;; tex.el --- Support for TeX documents.
 
-;; Copyright (C) 1985-1987, 1991, 1993-2015 Free Software Foundation, Inc.
+;; Copyright (C) 1985-1987, 1991, 1993-2016 Free Software Foundation, Inc.
 
 ;; Maintainer: address@hidden
 ;; Keywords: tex
@@ -4736,7 +4736,7 @@ Brace insertion is only done if point is in a math 
construct and
     (define-key map "\C-c}"    'up-list)
     (define-key map "\C-c#"    'TeX-normal-mode)
     (define-key map "\C-c\C-n" 'TeX-normal-mode)
-    (define-key map "\C-c?"    'TeX-doc)
+    (define-key map "\C-c?"    'TeX-documentation-texdoc)
     (define-key map "\C-c\C-i" 'TeX-goto-info-page)
     (define-key map "
"       'TeX-newline)
 
@@ -4959,7 +4959,7 @@ Brace insertion is only done if point is in a math 
construct and
        :help "Save and reparse the current buffer for style information"]
       ["Reset AUCTeX" (TeX-normal-mode t) :keys "C-u C-c C-n"
        :help "Reset buffer and reload AUCTeX style files"])
-     ["Find Documentation..." TeX-doc
+     ["Find Documentation..." TeX-documentation-texdoc
       :help "Get help on commands, packages, or TeX-related topics in general"]
      ["Read the AUCTeX Manual" TeX-goto-info-page
       :help "Everything worth reading"]
@@ -6094,6 +6094,71 @@ to browse existing AUCTeX bugs.
 
 ;;; Documentation
 
+(defun TeX-documentation-texdoc (&optional arg)
+  "Run texdoc to read documentation.
+
+Prompt for selection of the package of which to show the documentation.
+
+If called with a prefix argument ARG, after selecting the
+package, prompt for selection of the manual of that package to
+show."
+  (interactive "*P")
+  (let ((pkg (thing-at-point 'symbol))
+       buffer list doc)
+    ;; Strip off properties.  XXX: XEmacs doesn't have
+    ;; `substring-no-properties'.
+    (set-text-properties 0 (length pkg) nil pkg)
+    (setq pkg (TeX-read-string "View documentation for: " pkg))
+    (unless (zerop (length pkg))
+      (if arg
+         ;; Called with prefix argument: run "texdoc --list --nointeract <pkg>"
+         (progn
+           ;; Create the buffer, insert the result of the command, and
+           ;; accumulate the list of manuals.
+           (with-current-buffer (get-buffer-create
+                                 (setq buffer (format "*texdoc: %s*" pkg)))
+             (erase-buffer)
+             (insert (shell-command-to-string
+                      (concat "texdoc --list --nointeract " pkg)))
+             (goto-char 1)             ; No need to use `point-min' here.
+             (save-excursion
+               (while (re-search-forward
+                       ;; XXX: XEmacs doesn't support character classes in
+                       ;; regexps, like "[:alnum:]".
+                       "^ *\([0-9]+\) +\([-~/a-zA-Z0-9_.${}#%,:]+\)" nil t)
+                 (push (cons (match-string 1) (match-string 2)) list))))
+           (unwind-protect
+               (cond
+                ((null (executable-find "texdoc"))
+                 ;; Note: `shell-command-to-string' uses shell, only
+                 ;; `call-process' looks at `exec-path', thus only here makes
+                 ;; sense to use `executable-find' to test whether texdoc is
+                 ;; available.
+                 (message "texdoc not found"))
+                (list
+                 ;; Go on if there are manuals listed: show the buffer, prompt
+                 ;; for the number of the manual, then run
+                 ;;     texdoc --just-view <doc>
+                 (TeX-pop-to-buffer (get-buffer buffer))
+                 (condition-case nil
+                     (when (setq doc
+                                 (cdr (assoc (TeX-read-string "Please enter \
+the number of the file to view, anything else to skip: ") list)))
+                       (call-process "texdoc" nil 0 nil "--just-view" doc))
+                   ;; Exit gently if a `quit' signal is thrown.
+                   (quit nil)))
+                (t (message "No documentation found for %s" pkg)))
+             ;; In any case quit-and-kill the window.  XXX: XEmacs doesn't have
+             ;; `quit-window', just kill the buffer in that case.
+             (when (get-buffer-window buffer)
+               (if (fboundp 'quit-window)
+                   (quit-window t (get-buffer-window buffer))
+                 (kill-buffer buffer)))))
+       ;; Called without prefix argument: just run "texdoc --view <pkg>" and
+       ;; show the output, so that the user is warned in case it doesn't find
+       ;; the documentation or "texdoc" is not available.
+       (message (shell-command-to-string (concat "texdoc --view " pkg)))))))
+
 (defun TeX-goto-info-page ()
   "Read documentation for AUCTeX in the info system."
   (interactive)