%tag-file(5)

NAME

%tag-file - Tags file name
%tag-template - Tag file search string
%tag-option - Tag file search option

SYNOPSIS

%tag-file "fileName"
%tag-template "string"
%tag-option "string"

DESCRIPTION

The %tag-file and %tag-template variables must be defined for find-tag(2) to work, they define the information required to locate tag references.

%tag-file is the name of the tag file to be used, usually set to "tags". %tag-template is a regular expression search string used to identify tags in a tag file. For example, a tag usually consists of a name "%[^\t]" followed by a tab "\t" followed by the file name that contains the function "%[^\t]" followed by another tab, followed by the search string and end of line "%[^\n]\n", i.e.

set-variable %tag-template  "%[^\t]\t%[^\t]\t%[^\n]\n" 

This would match a vi(1) tag string definition, as created by the UNIX utility ctags(1). The tags file typically contains entries such as:

$auto-time    m5var000.5 /^.XI $auto-time - "Automatic buffer"$/ 
$buffer-bhook m5var002.5 /^.XI $buffer-bhook - "Buffer macro"$/ 
$buffer-ehook m5var002.5 /^.XI $buffer-ehook - "Buffer macro"$/ 

The tag-template definition is modified to match the output of the ctags(1) utility. The format of the tags file may differ from platform to platform, typically the differences are encountered in the line contents field which is usually defined as /  .... / for a forward search tag and ?  .... ? for a reverse search tag. Note that a tag's search string typically starts with the character '^' and ends with '$' which indicate the start and end of the line. The variable fields are expected to be in conventional order of label, filename and lineText.

%tag-option is a user defined variable that modifies the behavior of find-tag(2). This is defined as a string, where each character identifies an option, the options are defined as:

m - Enable multiple tags support


Allows a single tag to be present multiple times in the tag file, typically used when a function is defined multiple times. When enabled find-tag can be used to loop through all definitions of a given tag.

r - recursive tags file


By default, the tags file is assumed to reside in the current directory location. The r option enables an ascending search up the directory hierarchy from the current directory position in search of a recursively generated tags file.

c - Continue recursive tag search


Used in conjunction with flag r; when not specified, the recursive searching of a tag stops at the first tag file found, regardless of whether the given tag was located in the found tag file. If this flag is given and the tag was not found in the first tag file, the recursive search continues. This allows local tag files to be created and regularly maintained, yet still being able to access a higher level tag file when required.

When not defined the default value is "mrc". Modifications to this variable should be made in the user.emf file, e.g. To enable multi recursive ascent tag searching define:

set-variable %tag-option  "mrc" 

NOTES

Note that GNU Emacs uses it's own tag file format generated by etags(1) which does not contain the appropriate information to drive the MicroEmacs find-tag command.

The above settings should support the extended version 2 tag file format which has an extra tag type field at the end of each line.

SEE ALSO

ctags(1), ctags(3f), find-tag(2), vi(1).

Ref: %tag-file(5) File: m5var044.5 Date: 2025/10/18

(c) Copyright JASSPA 2026