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

Previous Next

To reply to this bug, email your comments to 44744 AT debbugs.gnu.org.

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

Previous Next

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