From 37fe62a3bda82d21aa6fa30d28f1c51e4bd8e6b4 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Tue, 27 Sep 2022 16:01:50 +0300
Subject: [PATCH] ; Fix documentation of imenu access in DocView

* lisp/doc-view.el (doc-view-imenu-enabled)
(doc-view--pdf-outline, doc-view-imenu-index): Doc fixes.

* doc/emacs/misc.texi (DocView Navigation): Fix typo and wording.
---
 doc/emacs/misc.texi |  8 ++++----
 lisp/doc-view.el    | 15 ++++++++-------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index f3a6e6c33b7..04f7f2e9213 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -585,11 +585,11 @@ default size for DocView, customize the variable
 @code{doc-view-resolution}.
 
 @vindex doc-view-imenu-enabled
-  When the @command{mutool} executable is available, DocView will use
+  When the @command{mutool} program is available, DocView will use it
 to generate entries for an outline menu, making it accessible via the
-imenu facility (@pxref{Imenu}).  To disable this functionality even
-when @command{mutool} can be found in your @code{exec-path}, customize
-the variable @code{doc-view-imenu-enabled}.
+@code{imenu} facility (@pxref{Imenu}).  To disable this functionality
+even when @command{mutool} can be found on your system, customize
+the variable @code{doc-view-imenu-enabled} to the @code{nil} value.
 
 @node DocView Searching
 @subsection DocView Searching
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index fe772efcfcc..fa583df12bd 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -215,7 +215,7 @@ are available (see Info node `(emacs)Document View')."
   :version "29.1")
 
 (defcustom doc-view-imenu-enabled (and (executable-find "mutool") t)
-  "Whether to generate an imenu outline when mutool is available."
+  "Whether to generate an imenu outline when \"mutool\" is available."
   :type 'boolean
   :version "29.1")
 
@@ -1884,9 +1884,10 @@ If BACKWARD is non-nil, jump to the previous match."
   "[^\t]+\\(\t+\\)\"\\(.+\\)\"\t#\\(?:page=\\)?\\([0-9]+\\)")
 
 (defun doc-view--pdf-outline (&optional file-name)
-  "Return a describing the outline of FILE-NAME (or current if nil).
+  "Return a list describing the outline of FILE-NAME.
+Return a list describing the current file if FILE-NAME is nil.
 
-Each element in the list contains information about a section's
+Each element in the returned list contains information about a section's
 title, nesting level and page number.  The list is flat: its tree
 structure is extracted by `doc-view--imenu-subtree'."
   (let* ((outline nil)
@@ -1925,11 +1926,11 @@ entries at an upper level."
     (cons (nreverse index) outline)))
 
 (defun doc-view-imenu-index (&optional file-name goto-page-fn)
-  "Create an imenu index using mutool to extract its outline.
+  "Create an imenu index using \"mutool\" to extract its outline.
 
-For extensibility, a FILE-NAME other than the current buffer and
-a jumping function, GOTO-PAGE-FN other than `doc-view-goto-page'
-can be specified."
+For extensibility, callers can specify a FILE-NAME to indicate
+the buffer other than the current buffer, and a jumping function
+GOTO-PAGE-FN other than `doc-view-goto-page'."
   (let* ((goto (or goto-page-fn 'doc-view-goto-page))
          (act (lambda (_name _pos page) (funcall goto page))))
     (car (doc-view--imenu-subtree (doc-view--pdf-outline file-name) act))))
-- 
2.39.2