Re: TeX-documentation-texdoc

[Greg Bognar]

Hi Ikumi,

Your code works!  So yes, your commit harmed okular in some way.  Where do we go
from here?

All the best,
Greg

-------------------------------------------------------------------------------
On Sun 22 Jan 2023 at 10:37 Ikumi Keita wrote:
> 
> Hi Greg,
> 
> >>>>> Greg Bognar via General discussion about AUCTeX <auctex@gnu.org> writes:
> > It turns out that C-u C-c? works: it opens a buffer with a list of related 
> > files
> > and then opens the selected one in my PDF viewer (okular).  It's only when I
> > call `TeX-documentation-texdoc' without a prefix argument that okular seems 
> > to
> > be started (a startup notification appears in the panel), but then 
> > disappears
> > and nothing happens.
> 
> > texdoc itself has no problem starting the PDF viewer, and it seems all
> > `TeX-documentation-texdoc' does is calling it.  I don't understand why it 
> > works
> > with a prefix argument but not without one.
> 
> That's because `TeX-documentation-texdoc' is written to behave in such a
> way:
> ,----
> | (defun TeX-documentation-texdoc (&optional arg)
> |   "Run texdoc to read documentation.
> | [...]
> | If called with a prefix argument ARG, after selecting the
> | package, prompt for selection of the manual of that package to
> | show."
> | [...]
> |       (if arg
> |           ;; Called with prefix argument: run "texdoc --list --nointeract 
> <pkg>"
> | [...]
> |                         (call-process "texdoc" nil 0 nil "--just-view" doc))
> | [...]
> |         ;; 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.
> | [...]
> |                           (process (start-process-shell-command
> |                                     "Doc view" standard-output
> |                                     (concat "texdoc --view " pkg))))
> | [...]
> `----
> 
> The difference is that it calls texdoc by `call-process' if prefix
> arugment is given while by `start-process-shell-command' without prefix
> argument.
> 
> By the way, I remember there was a similar bug report[1] before. In that
> report, the PDF viewer was okular, too. So I suspect that AUCTeX has
> something potentially inconsistent with okular.
> 
> [1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=40577
> 
> Can you test whether the following code works for you? This was used
> before my commit mentioned in [1]. I'd like to know whether my commit
> harmed okular or not.
> 
> Regards,
> Ikumi Keita
> #StandWithUkraine #StopWarInUkraine
> 
> ----------------------------------------------------------------------
> (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)))))))