bug#44744: 12.2.4; Incomplete documentation for TeX-view-program-list

[James Cook]

On Fri, Nov 20, 2020 at 02:20:35PM +0100, Arash Esbati wrote:
> Hi James,
> 
> James Cook <falsifian@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