Re: TeX-documentation-texdoc

[Greg Bognar]

Great, it works now!  It opens the requested file in the viewer and gives an
error message if it does not exist.  (Well, it often opens a file even if I give
it a nonsensical string, like "ddddd", which opens the documentation for
baskervaldadf -- but I assume that's a texdoc thing.)

All the best,
Greg

-------------------------------------------------------------------------------
On Tue 24 Jan 2023 at 06:27 Ikumi Keita wrote:
> >>>>> Greg Bognar <greg.bognar@startmail.com> writes:
> > 1. Unfortunately, the new function definition below does not work with
> > okular. Same problem as before.
> 
> Too bad. :-)
> 
> > 2. All of the environment variables PDFVIEWER, PDFVIEWER_texdoc,
> > TEXDOCVIEW_pdf, and TEXDOC_VIEWER_PDF have an empty value.
> 
> Thank you. It seems that the reported behavior originates from okular's
> own nature.
> 
> Then can you test the code at the last of this message?
> 
> [Rationale] The reason that `TeX-documentation-texdoc' tries hard to
> collect and show the output from Texdoc is that the exit code wasn't
> meaningful once[1]. However, recent Texdoc is improved to return
> non-zero exit code when it can't find documentation for the given
> keyword[2].
> 
> Thus I think that AUCTeX need not collect the output now; it just has to
> look at the exit code. We can use `call-process' (with `executable-find'
> test in case that Texdoc isn't available) to run Texdoc.
> 
> This has a drawback that the user who sticks to older TeX Live
> distribution isn't notified at all when the given keyword didn't match
> any documentation, but I expect it's permissible. Mosè, what do you
> think about it?
> 
> Regards,
> Ikumi Keita
> #StandWithUkraine #StopWarInUkraine
> 
> [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=28905#17
> [2] https://tug.org/texdoc/doc/texdoc.man1.pdf
> 
> ----------------------------------------------------------------------
> (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.
>               (when (get-buffer-window buffer)
>                 (quit-window t (get-buffer-window buffer)))))
>         ;; Called without prefix argument: just run "texdoc --view <pkg>".
>         ;; The folowing code to the end of `defun' used to be just
>         ;; (message "%s" (shell-command-to-string (concat "texdoc --view " 
> pkg)))
>         ;; , but in some cases it blocks emacs until the user
>         ;; quits the viewer (bug#28905).
>         ;; (2023-01-24) Now we use `call-process' instead of
>         ;; `start-process-shell-command'.  This can introduce
>         ;; discrepancy in the process environment, especially PATH.
>         ;; But we need to do so to support both okular and evince.  We
>         ;; hope that it doesn't cause major problem.
>         (if (executable-find "texdoc")
>             ;; Recent Texdoc returns exit code 3 when it can't find the
>             ;; specified document, according to
>             ;; <URL:https://tug.org/texdoc/doc/texdoc.man1.pdf>
>             (if (= (call-process "texdoc" nil nil nil "--view" pkg) 3)
>                 (message "No documentation found for %s" pkg))
>           (message "texdoc not found"))))))