branch: externals/auctex
commit f9e6e4b8528df03a7810910e7dc2c28b5806c506
Author: Mosè Giordano <m...@gnu.org>
Commit: Mosè Giordano <m...@gnu.org>
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
-@deffn Command TeX-doc
+@deffn 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
-@samp{texdoc} 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.
-@c Copyright (C) 1994-2002, 2004-2010, 2012-2015 Free Software
+@c 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
+@heading News since 11.89
+
+@itemize @bullet
+@item
+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
+@code{TeX-documentation-texdoc}.
+@end 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: auctex-de...@gnu.org
;; 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 "\r" '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)
