[AUCTeX-devel] Re: Accessing TeX-related documentation

[Ralf Angeli]

* Reiner Steib (2005-11-19) writes:

> Beside the wrong matches in the completing list, my suggestion blocks
> the Emacs session while reading the documentation.  It should probably
> be run in the background, but I'm not sure if we can catch "not found"
> then.

We could use `start-process' if texdoc did not go into background (at
least on Debian systems).  If called with `start-process' Emacs will
kill both texdoc and the spawned viewer as soon as this happens.  So
we are left with `call-process' and a 0 value for the buffer argument.
Like this we cannot provide feedback if texdoc failed.  Pity.

> $ complete|grep texdoc
> complete -C _texdoc texdoc
> $ type _texdoc
> _texdoc is a function
> _texdoc () 
> { 
>     kpsewhich -expand-path='$TEXDOCS' | tr : ' ' | xargs ls -U1 | \
>       sed -ne "s;^\($2.*\)\.\(dvi\|pdf\|html\|ps\)$;\1;p"
> }

I am now using something similar with `(TeX-search-files nil '("dvi"
"pdf" "ps" "txt" "html") t t)' and the following additional entry for
`TeX-kpathsea-format-alist':

    ("dvi" "${TEXDOCS}" '("dvi" "pdf" "ps" "txt" "html"
                          "dvi.gz" "pdf.gz" "ps.gz" "txt.gz" "html.gz"
                          "dvi.bz2" "pdf.bz2" "ps.bz2" "txt.bz2" "html.bz2"))

> | Maybe this could be expanded later to include command references like
> | <URL:http://www.miwie.org/tex-refs/>
>
> [I didn't look at this page yet.]  Maybe an index search in
> `latex.info'[1] from AUCTeX would be useful.  `ltx-help.el'[2] from
> Peter Galbraith and others is/was supposed to do this.  It seemed to
> have been part of AUCTeX previously[3].  [`latex.info' and
> `ltx-help.el' are both included in SuSE 9.2.]

Hm, I haven't looked at ltx-help.el yet.  Support for latex.info is
provided in the suggestion below.

> Maybe two separate commands are in order for packages (-> texdoc) and
> macros (-> info, references).

I think it would be nice to have a single entry point.  In case we
have to deal with duplicate matches we could provide some way to
choose one or the other.  I also thought about an interface like `M-x
apropos ...' which would provide a way for choosing stuff.  But for
now I implemented only the simple prompt-with-completion interface
which I prefer anyway because it involves only one step for accessing
documentation.

Okay, the proposal below is not fully tested yet and in need of some
autoloads or require calls but should show how the backend mechanism
work.  This should allow to plug other backends into the `TeX-doc'
function quite easily.  The requirements are explained in the doc
string of `TeX-doc-backend-alist'.

The provided backend specificiations cover texdoc and the info manuals
for Texinfo and LaTeX.  I am not sure about ConTeXt yet.
Theoretically we could simply call `texshow', but I don't see a way to
get any information about documented commands for completion.  And
with this information missing `TeX-doc' is not able to determine the
appropriate backend for displaying documentation.  This is a drawback
of the function where I am not sure yet if I can fix this.  If I
can't, maybe the user could be asked to pick a backend.

Another design issue is the specification of the modes the respective
backends should be used in.  They are currently specified in
`TeX-doc-backend-alist'.  I'd prefer to have the modes taking care of
their documentation themselves, so instead of configuring everything
centrally in `TeX-doc-backend-alist' the variable would default to nil
and the modes would add their stuff themselves.  The drawback is that
this will lead to code duplication in case of backends which are used
by more than one mode.

Okay, enough babbling, here is the code (don't forget the adaption of
`TeX-kpathsea-format-alist' if you want to check it out):

(defvar TeX-doc-backend-alist
  '((texdoc (plain-tex-mode latex-mode doctex-mode)
            (lambda ()
              (TeX-search-files nil '("dvi" "pdf" "ps" "txt" "html") t t))
            (lambda (doc)
              (call-process "texdoc" nil 0 nil doc)))
    (latex-info (latex-mode)
                (lambda ()
                  (mapcar (lambda (x)
                            (let ((x (car x)))
                              (if (string-match "\\`\\\\" x)
                                  (substring x 1) x)))
                          (info-lookup->completions 'symbol 'latex-mode)))
                (lambda (doc)
                  (info-lookup-symbol (concat "\\" doc) 'latex-mode)))
    (texinfo-info (texinfo-mode)
                  (lambda ()
                    (mapcar (lambda (x)
                              (let ((x (car x)))
                                (if (string-match "\\`@" x)
                                    (substring x 1) x)))
                            (info-lookup->completions 'symbol 'texinfo-mode)))
                  (lambda (doc)
                    (info-lookup-symbol (concat "@" doc) 'texinfo-mode))))
  "Alist of backends used for looking up documentation.
Each item consists of four elements.  The first is a symbol
describing the backend's name.  The second is a list of modes the
backend should be activated in.  The third is a function
returning a list of available documents.  The fourth is a
function for displaying the documentation.  The function should
accept a single argument, the chosen package, command, or
document name.")

(defun TeX-doc (&optional name)
  "Display documentation for NAME."
  (interactive)
  (let (docs)
    (dolist (elt TeX-doc-backend-alist)
      (when (memq major-mode (nth 1 elt))
        (add-to-list 'docs (cons (funcall (nth 2 elt)) (nth 0 elt)))))
    (when (and (called-interactively-p)
               (or (not name) (string= name "")))
      (let ((symbol (thing-at-point 'symbol))
            contained completions doc)
        (setq contained (catch 'found
                          (dolist (elt docs)
                            (when (member symbol (car elt))
                              (throw 'found t)))))
        (dolist (elt docs)
          (setq completions (nconc (mapcar 'list (car elt)) completions)))
        (setq doc (completing-read
                   (if contained
                       (format "Package, command, or document (default %s): "
                               symbol)
                     "Package, command, or document: ")
                   completions))
        (setq name (if (string= doc "") symbol doc))))
    (if (not name)
        (message "No documentation specified")
      ;; XXX: Provide way to choose in case a symbol can be found in
      ;; more than one backend.
      (let* ((backend (catch 'found
                        (dolist (elt docs)
                          (when (member name (car elt))
                            (throw 'found (cdr elt)))))))
        (if backend
            (funcall (nth 3 (assoc backend TeX-doc-backend-alist)) name)
          (message "Documentation not found"))))))

-- 
Ralf