Automatic Extraction of New Things

The automatic TeX information extractor works by searching for regular expression in the TeX files, and storing the matched information. You can add support for new constructs to the parser, something that is needed when you add new commands to define symbols.

For example, in the file `macro.tex' I define the following macro.

\newcommand{\newmacro}[5]{%
\def#1{#3\index{#4@#5~cite{#4}}\nocite{#4}}%
\def#2{#5\index{#4@#5~cite{#4}}\nocite{#4}}%
}

AUC TeX will automatically figure out that `newmacro' is a macro that takes five arguments. However, it is not smart enough to automatically see that each time we use the macro, two new macros are defined. We can specify this information in a style hook file.

;;; macro.el - Special code for my own macro file.

;;; New Macro Definition Command

(require 'tex-auto)

(defvar TeX-newmacro-regexp
  "\\\\newmacro{\\\\\\([a-zA-Z]+\\)}{\\\\\\([a-zA-Z]+\\)}"
  "Matches \newmacro definitions.")

(or (assoc TeX-newmacro-regexp TeX-auto-regexp-list)
    (setq TeX-auto-regexp-list 
          (cons  (list TeX-newmacro-regexp '(1 2) 'TeX-auto-multi)
                 TeX-auto-regexp-list)))

(defvar TeX-auto-multi nil
  "Temporary for parsing \newmacro definitions.")

(defun TeX-macro-cleanup ()
  "Support for \\newmacro macro."
  
  (mapcar (function (lambda (list)
                      (mapcar (function (lambda (symbol)
                                          (setq TeX-auto-symbol
                                                (cons symbol
                                                      TeX-auto-symbol))))
                              list)))
          TeX-auto-multi))

(setq TeX-auto-prepare-hooks (cons (function (lambda ()
                                                 (setq TeX-auto-multi nil)))
                                   TeX-auto-prepare-hooks))

(setq TeX-auto-cleanup-hooks (cons 'TeX-macro-cleanup TeX-auto-cleanup-hooks))

;;; HOOK

(TeX-add-style-hook "macro"
 (function
  (lambda ()
    (TeX-add-symbols '("newmacro"
                       TeX-argument-macro-hook
                       (TeX-argument-macro-hook "Capitalized macro: \\")
                       t
                       "BibTeX entry: "
                       nil)))))

When this file is first loaded, it adds a new entry to TeX-newmacro-regexp, and defines a function to be called before the parsing starts, and one to be called after the parsing is done. It also declares a variable to contain the data collected during parsing. Finally, it adds a style hook which describes the `newmacro' macro, as we have seen it before.

So the general strategy is: Add new entry to TeX-newmacro-regexp. Declare variable to contain intermediate data during parsing. Add hook to be called before and after parsing. In this case, the hook before parsing just initialize the variable, and the hook after parsing collect the data from the variable, and add them to the list of symbols found.

Variable: TeX-auto-regexp-list

List of regular expression matching TeX macro definitions.

The list has the following format ((REGEXP MATCH TABLE) ...), that is, each entry is a list with three elements.

REGEXP. Regular expression matching the macro we want to parse.

MATCH. A number or list of numbers, each representing one parenthesized subexpression matched by REGEXP.

TABLE. The symbol table to store the data. This can be function, in which case the function is called with the argument MATCH. Use TeX-match-buffer to get match data. If it is not a function, it is presumed to be the name of a variable containing a list of match data. The matched data (a string if MATCH is a number, a list of strings if MATCH is a list of numbers) is put in front of the table.

Variable: TeX-auto-prepare-hooks nil

List of hooks to be called before parsing a TeX file.

Variable: TeX-auto-cleanup-hooks nil

List of hooks to be called after parsing a TeX file.