Re: TeX-documentation-texdoc

[Arash Esbati]

Hi Keita,

Ikumi Keita <ikumi@ikumi.que.jp> writes:

> Thanks for confirmation. I'll commit the attached patch #1,
> incorporating Arash's suggestion.

Thanks for working on this.  Reg.
0001-Make-TeX-documentation-texdoc-work-for-okular, I have some minor
comments:

diff --git a/tex.el b/tex.el
index 456c0310..c905ce29 100644
--- a/tex.el
+++ b/tex.el
@@ -6390,81 +6390,55 @@ If called with a prefix argument ARG, after selecting 
the
 package, prompt for selection of the manual of that package to
 show."
[...]
+  (if (not (executable-find "texdoc"))
+      (message "texdoc not found")
+    (let ((pkg (thing-at-point 'symbol))
+          buffer list doc)
+      ;; Strip off properties.
+      (set-text-properties 0 (length pkg) nil pkg)

I think we can shorten this by calling `thing-at-point' with the
optional second argument NO-PROPERTIES

  (thing-at-point THING &optional NO-PROPERTIES)

  Return the THING at point.
  THING should be a symbol specifying a type of syntactic entity.
  Possibilities include ‘symbol’, ‘list’, ‘sexp’, ‘defun’,
  ‘filename’, ‘existing-filename’, ‘url’, ‘email’, ‘uuid’, ‘word’,
  ‘sentence’, ‘whitespace’, ‘line’, ‘number’, ‘face’ and ‘page’.

  When the optional argument NO-PROPERTIES is non-nil,
  strip text properties from the return value.

=> (let ((pkg (thing-at-point 'symbol t))

+      (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

Is this `save-excursion' really necessary?  Or am I missing something?

+                  (while (re-search-forward
+                          ;; XXX: XEmacs doesn't support character classes in
+                          ;; regexps, like "[:alnum:]".

I think we can delete this comment.

> I think I should go further to settle out the discrepancy between
> `shell-command-*' and `call-process' by the patch #2.

+1

> It also turns INITIAL-INPUT argument for `TeX-read-string' into
> DEFAULT, taking your effort into accout. What do you think about it?

Thanks for thinking about it :-)  I have an idea here:

diff --git a/tex.el b/tex.el
index c905ce29..4ab5d170 100644
--- a/tex.el
+++ b/tex.el
-      (setq pkg (TeX-read-string "View documentation for: " pkg))
+      (if pkg
+          (set-text-properties 0 (length pkg) nil pkg))
+      (setq pkg (TeX-read-string (concat
+                                  "View documentation for"
+                                  (if pkg
+                                      (format " (default %s)" pkg))
+                                  ": ")
+                                 nil nil pkg))

I think we should borrow some code from the compat-package[1] and
introduce our `TeX-format-prompt' and once we're at Emacs 28, we just
alias it to `format-prompt' or use `format-prompt' directly.  Suppose we
have this in tex.el:

--8<---------------cut here---------------start------------->8---
(defun TeX-format-prompt (prompt default &rest format-args)
  "Format PROMPT with DEFAULT.
If FORMAT-ARGS is nil, PROMPT is used as a plain string.  If
FORMAT-ARGS is non-nil, PROMPT is used as a format control
string, and FORMAT-ARGS are the arguments to be substituted into
it.  See `format' for details.
If DEFAULT is a list, the first element is used as the default.
If not, the element is used as is.
If DEFAULT is nil or an empty string, no \"default value\" string
is included in the return value."
  (concat
   (if (null format-args)
       prompt
     (apply #'format prompt format-args))
   (and default
        (or (not (stringp default))
            (> (length default) 0))
        (format " (default %s)"
                (if (consp default)
                    (car default)
                  default)))
   ": "))
--8<---------------cut here---------------end--------------->8---

Then we could write:

--8<---------------cut here---------------start------------->8---
(setq pkg (TeX-read-string (TeX-format-prompt
                            "View documentation for" pkg)
                           nil nil pkg))
--8<---------------cut here---------------end--------------->8---

Adjusting the other 30 occurrences in the repo should be easy.  WDYT?

Best, Arash

Footnotes:
[1]  
https://github.com/emacs-compat/compat/blob/f6c5ffc6485ea2d2b0c65e7189895ec06124792e/compat-28.el#L610