GNU bug report logs - #44744
12.2.4; Incomplete documentation for TeX-view-program-list

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 44744 in the body.
You can then email your comments to 44744 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: James Cook <falsifian <at> falsifian.org>
To: bug-auctex <at> gnu.org
Subject: 12.2.4; Incomplete documentation for TeX-view-program-list
Date: Thu, 19 Nov 2020 19:52:44 +0000

I wanted to add mupdf TeX-view-program-list, but the documentation
(appearing in customize-variable for example) was missing one crucial
piece of information: how I should actually format the command. I
eventually figured out it needs to be "mupdf %o". Either %o should be
documented right there, or there should be a link to a place where
it and other substitutions are documented. (I'm sure they are somewhere;
I just have no idea where to start looking.)


Emacs  : GNU Emacs 27.1 (build 1, x86_64-unknown-openbsd, GTK+ Version 3.24.23)
 of 2020-10-31
Package: 12.2.4

current state:
==============
(setq
 AUCTeX-date "2020-06-29"
 window-system 'x
 LaTeX-version "2e"
 TeX-style-path '("~/.emacs.d/auctex" "/home/falsifian/.emacs.d/elpa/auctex-12.2.4/style" "/home/falsifian/.emacs.d/auctex/auto" "/home/falsifian/.emacs.d/auctex/style" "auto" "style")
 TeX-auto-save nil
 TeX-parse-self nil
 TeX-master 'shared
 TeX-command-list '(("TeX" "%(PDF)%(tex) %(file-line-error) %`%(extraopts) %S%(PDFout)%(mode)%' %t" TeX-run-TeX nil (plain-tex-mode ams-tex-mode texinfo-mode) :help "Run plain TeX") ("LaTeX" "%`%l%(mode)%' %T" TeX-run-TeX nil (latex-mode doctex-mode) :help "Run LaTeX")
                    ("Makeinfo" "makeinfo %(extraopts) %t" TeX-run-compile nil (texinfo-mode) :help "Run Makeinfo with Info output") ("Makeinfo HTML" "makeinfo %(extraopts) --html %t" TeX-run-compile nil (texinfo-mode) :help "Run Makeinfo with HTML output")
                    ("AmSTeX" "amstex %(PDFout) %`%(extraopts) %S%(mode)%' %t" TeX-run-TeX nil (ams-tex-mode) :help "Run AMSTeX") ("ConTeXt" "%(cntxcom) --once --texutil %(extraopts) %(execopts)%t" TeX-run-TeX nil (context-mode) :help "Run ConTeXt once")
                    ("ConTeXt Full" "%(cntxcom) %(extraopts) %(execopts)%t" TeX-run-TeX nil (context-mode) :help "Run ConTeXt until completion") ("BibTeX" "bibtex %s" TeX-run-BibTeX nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode context-mode) :help "Run BibTeX")
                    ("Biber" "biber %s" TeX-run-Biber nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Run Biber") ("View" "%V" TeX-run-discard-or-function t t :help "Run Viewer") ("Print" "%p" TeX-run-command t t :help "Print the file")
                    ("Queue" "%q" TeX-run-background nil t :help "View the printer queue" :visible TeX-queue-command) ("File" "%(o?)dvips %d -o %f " TeX-run-dvips t (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Generate PostScript file")
                    ("Dvips" "%(o?)dvips %d -o %f " TeX-run-dvips nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Convert DVI file to PostScript")
                    ("Dvipdfmx" "dvipdfmx %d" TeX-run-dvipdfmx nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Convert DVI file to PDF with dvipdfmx")
                    ("Ps2pdf" "ps2pdf %f" TeX-run-ps2pdf nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Convert PostScript file to PDF")
                    ("Glossaries" "makeglossaries %s" TeX-run-command nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Run makeglossaries to create glossary\n     file")
                    ("Index" "makeindex %s" TeX-run-index nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Run makeindex to create index file")
                    ("upMendex" "upmendex %s" TeX-run-index t (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Run upmendex to create index file")
                    ("Xindy" "texindy %s" TeX-run-command nil (plain-tex-mode latex-mode doctex-mode ams-tex-mode texinfo-mode) :help "Run xindy to create index file") ("Check" "lacheck %s" TeX-run-compile nil (latex-mode) :help "Check LaTeX file for correctness")
                    ("ChkTeX" "chktex -v6 %s" TeX-run-compile nil (latex-mode) :help "Check LaTeX file for common mistakes") ("Spell" "(TeX-ispell-document \"\")" TeX-run-function nil t :help "Spell-check the document") ("Clean" "TeX-clean" TeX-run-function nil t :help "Delete generated intermediate files")
                    ("Clean All" "(TeX-clean t)" TeX-run-function nil t :help "Delete generated intermediate and output files") ("Other" "" TeX-run-command t t :help "Run an arbitrary command"))
 )

Message #8 received at 44744 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: James Cook <falsifian <at> falsifian.org>
Cc: 44744 <at> debbugs.gnu.org
Subject: Re: bug#44744: 12.2.4; Incomplete documentation for
 TeX-view-program-list
Date: Fri, 20 Nov 2020 14:20:35 +0100

Hi James,

James Cook <falsifian <at> falsifian.org> writes:

> I wanted to add mupdf TeX-view-program-list, but the documentation
> (appearing in customize-variable for example) was missing one crucial
> piece of information: how I should actually format the command.

Admittedly, there are no examples in the docstring, but ...

,----[ C-h v TeX-view-program-list RET ]
| TeX-view-program-list is a variable defined in ‘tex.el’.
| Its value is nil
| 
|   You can customize this variable.
| 
| Documentation:
| List of viewer specifications.
| This variable can be used to specify how a viewer is to be
| invoked and thereby add new viewers on top of the built-in list
| of viewers defined in ‘TeX-view-program-list-builtin’ or override
| entries in the latter.

This is a link where you can find examples for built-in viewers.

> I eventually figured out it needs to be "mupdf %o". Either %o should
> be documented right there, or there should be a link to a place where
> it and other substitutions are documented. (I'm sure they are
> somewhere; I just have no idea where to start looking.)

| Note that the command line can contain placeholders as defined in
| ‘TeX-expand-list’ which are expanded before the viewer is called.

The placeholders (%o and such) are again linked to `TeX-expand-list'
which then redirects you to `TeX-expand-list-builtin'.

What would you suggest in order to make the docstring more clear?

Best, Arash

Message #11 received at 44744 <at> debbugs.gnu.org (full text, mbox):

From: James Cook <falsifian <at> falsifian.org>
To: Arash Esbati <arash <at> gnu.org>
Cc: 44744 <at> debbugs.gnu.org
Subject: Re: bug#44744: 12.2.4; Incomplete documentation for
 TeX-view-program-list
Date: Sun, 22 Nov 2020 03:46:10 +0000

On Fri, Nov 20, 2020 at 02:20:35PM +0100, Arash Esbati wrote:
> Hi James,
> 
> James Cook <falsifian <at> falsifian.org> writes:
> 
> > I wanted to add mupdf TeX-view-program-list, but the documentation
> > (appearing in customize-variable for example) was missing one crucial
> > piece of information: how I should actually format the command.
> 
> Admittedly, there are no examples in the docstring, but ...
> 
> ,----[ C-h v TeX-view-program-list RET ]
> | TeX-view-program-list is a variable defined in ‘tex.el’.
> | Its value is nil
> | 
> |   You can customize this variable.
> | 
> | Documentation:
> | List of viewer specifications.
> | This variable can be used to specify how a viewer is to be
> | invoked and thereby add new viewers on top of the built-in list
> | of viewers defined in ‘TeX-view-program-list-builtin’ or override
> | entries in the latter.
> 
> This is a link where you can find examples for built-in viewers.

I did find the examples, but was looking for an explicit description.

> > I eventually figured out it needs to be "mupdf %o". Either %o should
> > be documented right there, or there should be a link to a place where
> > it and other substitutions are documented. (I'm sure they are
> > somewhere; I just have no idea where to start looking.)
> 
> | Note that the command line can contain placeholders as defined in
> | ‘TeX-expand-list’ which are expanded before the viewer is called.
> 
> The placeholders (%o and such) are again linked to `TeX-expand-list'
> which then redirects you to `TeX-expand-list-builtin'.
> 
> What would you suggest in order to make the docstring more clear?
> 
> Best, Arash

Oops, I missed the reference to TeX-expand-list. Thanks for your
response.

It might help to mention the existence of placeholders more
prominently. E.g. by inserting this sentence:

  Placeholders in the strings are expanded as defined in
  `TeX-expand-list`.

immediately after the sentence

  The command line can either be specified as a single string or a list
  of strings and two-part lists.

Adding an example would also help.

Below is a more radical attempt to rewrite it to (a) include some
structure to help the reader jump to the information they're looking
for and (b) include an example. I'm sure it has deficiencies compared
to the current documentation but maybe you can use part of it.

---

(First paragraph same as before.)

Each item is a list with two or three elements:
  (NAME RUN REQUIRED_EXECUTABLE)
or
  (NAME RUN)
The elements are explained in more detail below. For example,
  ("MuPDF" "mupdf %o" "mupdf")
adds an entry "MuPDF" assuming 'TeX-expand-list' expands %o to the name
of the file to be opened.

NAME is a user-readable name.

RUN specifies how to run the viewer, and can be a command line to be
run as a process or a Lisp function to be executed. The command line
can either be specified as a single string or a list of strings and
two-part lists. The first element of the two-part lists is a symbol or
a list of symbols referring to one or more of the predicates in
‘TeX-view-predicate-list’ or ‘TeX-view-predicate-list-builtin’. The
second part of the two-part lists is a command line part. The command
line for the viewer is constructed by concatenating the command line
parts. Parts with a predicate are only considered if the predicate was
evaluated with a positive result. The command line can contain
placeholders as defined in ‘TeX-expand-list’ which are expanded before
the viewer is called.

REQUIRED_EXECUTABLE is optional and specifies the name of the
executable, or executables, needed to open the file in the viewer. It
should be a string or list of strings. Placeholders defined in
‘TeX-expand-list’ can be used here. This element is used to check
whether the viewer is actually available on the system.

-- 
James

Message #14 received at 44744 <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: James Cook <falsifian <at> falsifian.org>
Cc: 44744 <at> debbugs.gnu.org
Subject: Re: bug#44744: 12.2.4; Incomplete documentation for
 TeX-view-program-list
Date: Sat, 24 Aug 2024 08:15:08 +0200

Hi James,

James Cook <falsifian <at> falsifian.org> writes:

> Oops, I missed the reference to TeX-expand-list. Thanks for your
> response.
>
> It might help to mention the existence of placeholders more
> prominently. E.g. by inserting this sentence:
>
>   Placeholders in the strings are expanded as defined in
>   `TeX-expand-list`.
>
> immediately after the sentence
>
>   The command line can either be specified as a single string or a list
>   of strings and two-part lists.
>
> Adding an example would also help.

this report went lost in action, sorry for that.  I'd like to propose
this change in order to fix and close this issue; the patch is more
complicated to read because of the re-filling, but I hope you get the
point.  As a note, I'm not sure if an example in the docstring makes
things more clear, therefore I add a reference to
`TeX-view-program-list-builtin' for examples:

--8<---------------cut here---------------start------------->8---
diff --git a/tex.el b/tex.el
index ea688f17..503072a5 100644
--- a/tex.el
+++ b/tex.el
@@ -1376,38 +1376,37 @@ description of the data format.")

 (defcustom TeX-view-program-list nil
   "List of viewer specifications.
-This variable can be used to specify how a viewer is to be
-invoked and thereby add new viewers on top of the built-in list
-of viewers defined in `TeX-view-program-list-builtin' or override
-entries in the latter.
-
-The car of each item is a string with a user-readable name.  The
-second element can be a command line to be run as a process or a
-Lisp function to be executed.  The command line can either be
-specified as a single string or a list of strings and two-part
-lists.  The first element of the two-part lists is a symbol or a
-list of symbols referring to one or more of the predicates in
-`TeX-view-predicate-list' or `TeX-view-predicate-list-builtin'.
-The second part of the two-part lists is a command line part.
-The command line for the viewer is constructed by concatenating
-the command line parts.  Parts with a predicate are only
-considered if the predicate was evaluated with a positive result.
-Note that the command line can contain placeholders as defined in
-`TeX-expand-list' which are expanded before the viewer is called.
-The third element of the item is optional and is a string, or a
-list of strings, with the name of the executable, or executables,
-needed to open the output file in the viewer.  Placeholders
-defined in `TeX-expand-list' can be used here.  This element is
-used to check whether the viewer is actually available on the
-system.
-
-The use of a function as the second element only works if the
-View command in `TeX-command-list' makes use of the hook
+This variable can be used to specify how a viewer is to be invoked and
+thereby add new viewers on top of the built-in list of viewers defined
+in `TeX-view-program-list-builtin' or override entries in the latter
+which also serves as an example for usage.
+
+The car of each item is a string with a user-readable name.  The second
+element can be a command line to be run as a process or a Lisp function
+to be executed.  The command line can either be specified as a single
+string or a list of strings and two-part lists.  The first element of
+the two-part lists is a symbol or a list of symbols referring to one or
+more of the predicates in `TeX-view-predicate-list' or
+`TeX-view-predicate-list-builtin'.  The second part of the two-part
+lists is a command line part.  The command line for the viewer is
+constructed by concatenating the command line parts.  Parts with a
+predicate are only considered if the predicate was evaluated with a
+positive result.  Note that the command line can contain placeholders as
+defined in the variable `TeX-expand-list' or in
+`TeX-expand-list-builtin' which are expanded before the viewer is
+called.  The third element of the item is optional and is a string, or a
+list of strings, with the name of the executable, or executables, needed
+to open the output file in the viewer.  Placeholders defined in the
+variable `TeX-expand-list' or in `TeX-expand-list-builtin' can be used
+here.  This element is used to check whether the viewer is actually
+available on the system.
+
+The use of a function as the second element only works if the View
+command in `TeX-command-list' makes use of the hook
 `TeX-run-discard-or-function'.

-Note: Predicates defined in the current Emacs session will only
-show up in the customization interface for this variable after
-restarting Emacs."
+Note: Predicates defined in the current Emacs session will only show up
+in the customization interface for this variable after restarting Emacs."
   :group 'TeX-view
   :type
   `(repeat
--8<---------------cut here---------------end--------------->8---

Any comments welcome.

Best, Arash

Message #19 received at 44744-done <at> debbugs.gnu.org (full text, mbox):

From: Arash Esbati <arash <at> gnu.org>
To: James Cook <falsifian <at> falsifian.org>
Cc: 44744-done <at> debbugs.gnu.org
Subject: Re: bug#44744: 12.2.4; Incomplete documentation for
 TeX-view-program-list
Date: Fri, 30 Aug 2024 10:48:24 +0200

Arash Esbati <arash <at> gnu.org> writes:

> I'd like to propose this change in order to fix and close this issue;

I installed that change, and therefore closing this report.

Best, Arash

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.