|
2225
|
1 -*- indented-text -*-
|
|
|
2
|
|
3876
|
3 See the end of this file for copyright information.
|
|
|
4
|
|
2225
|
5 This file contains two sections:
|
|
|
6
|
|
2554
|
7 1) An EBNF (Extended Backus-Naur Form) description of the format of
|
|
2225
|
8 the tags file created by etags.c and interpreted by etags.el;
|
|
|
9 2) A discussion of tag names and implicit tag names.
|
|
|
10
|
|
|
11 ====================== 1) EBNF tag file description =====================
|
|
|
12
|
|
|
13 Productions created from current behaviour to aid extensions
|
|
|
14 Francesco Potorti` <pot@gnu.org> 2002
|
|
|
15 ----------------
|
|
|
16
|
|
|
17 FF ::= #x0c /* tag section starter */
|
|
|
18
|
|
|
19 LF ::= #x0a /* line terminator */
|
|
|
20
|
|
|
21 DEL ::= #x7f /* pattern terminator */
|
|
|
22
|
|
|
23 SOH ::= #x01 /* name terminator */
|
|
|
24
|
|
|
25 regchar ::= [^#x0a#x0c#x7f] /* regular character */
|
|
|
26
|
|
|
27 regstring ::= { regchar } /* regular string */
|
|
|
28
|
|
|
29 unsint ::= [0-9] { [0-9] } /* non-negative integer */
|
|
|
30
|
|
|
31
|
|
|
32
|
|
|
33 tagfile ::= { tagsection } /* a tags file */
|
|
|
34
|
|
|
35 tagsection ::= FF LF ( includesec | regularsec ) LF
|
|
|
36
|
|
|
37 includesec ::= filename ",include" [ LF fileprop ]
|
|
|
38
|
|
|
39 regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag }
|
|
|
40
|
|
|
41 filename ::= regchar regstring /* a file name */
|
|
|
42
|
|
|
43 fileprop ::= "(" regstring ")" /* an elisp alist */
|
|
|
44
|
|
|
45 tag ::= directtag | patterntag
|
|
|
46
|
|
|
47 directtag ::= DEL realposition /* no pattern */
|
|
|
48
|
|
|
49 patterntag ::= pattern DEL [ tagname SOH ] position
|
|
|
50
|
|
|
51 pattern ::= regstring /* a tag pattern */
|
|
|
52
|
|
|
53 tagname ::= regchar regstring /* a tag name */
|
|
|
54
|
|
|
55 position ::= realposition | "," /* charpos,linepos */
|
|
|
56
|
|
|
57 realposition ::= "," unsint | unsint "," | unsint "," unsint
|
|
|
58
|
|
|
59 ==================== end of EBNF tag file description ====================
|
|
|
60
|
|
|
61
|
|
|
62
|
|
|
63 ======================= 2) discussion of tag names =======================
|
|
|
64
|
|
|
65 - WHAT ARE TAG NAMES
|
|
|
66 Tag lines in a tags file are usually made from the above defined pattern
|
|
|
67 and by an optional tag name. The pattern is a string that is searched
|
|
|
68 in the source file to find the tagged line.
|
|
|
69
|
|
|
70 - WHY TAG NAMES ARE GOOD
|
|
|
71 When a user looks for a tag, Emacs first compares the tag with the tag
|
|
|
72 names contained in the tags file. If no match is found, Emacs compares
|
|
|
73 the tag with the patterns. The tag name is then the preferred way to
|
|
|
74 look for tags in the tags file, because when the tag name is present
|
|
|
75 Emacs can find a tag faster and more accurately. These tag names are
|
|
|
76 part of tag lines in the tags file, so we call them "explicit".
|
|
|
77
|
|
|
78 - WHY IMPLICIT TAG NAMES ARE EVEN BETTER
|
|
|
79 When a tag line has no name, but a name can be deduced from the pattern,
|
|
|
80 we say that the tag line has an implicit tag name. Often tag names are
|
|
|
81 redundant; this happens when the name of a tag is an easily guessable
|
|
|
82 substring of the tag pattern. We define a set of rules to decide
|
|
|
83 whether it is possible to deduce the tag name from the pattern, and make
|
|
|
84 an unnamed tag in those cases. The name deduced from the pattern of an
|
|
|
85 unnamed tag is the implicit name of that tag.
|
|
2325
|
86 When the user looks for a tag, and Emacs finds no explicit tag names
|
|
2225
|
87 that match it, Emacs then looks for an tag whose implicit tag name
|
|
|
88 matches the request. etags.c uses implicit tag names when possible, in
|
|
|
89 order to reduce the size of the tags file.
|
|
|
90 An implicit tag name is deduced from the pattern by discarding the
|
|
|
91 last character if it is one of ` \f\t\n\r()=,;', then taking all the
|
|
|
92 rightmost consecutive characters in the pattern which are not one of
|
|
|
93 those.
|
|
|
94
|
|
|
95 ===================== end of discussion of tag names =====================
|
|
3876
|
96
|
|
|
97 Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007
|
|
|
98 Free Software Foundation, Inc.
|
|
|
99
|
|
|
100 COPYING PERMISSIONS:
|
|
|
101
|
|
|
102 This document is free software; you can redistribute it and/or modify
|
|
|
103 it under the terms of the GNU General Public License as published by
|
|
|
104 the Free Software Foundation; either version 2 of the License, or
|
|
|
105 (at your option) any later version.
|
|
|
106
|
|
|
107 This program is distributed in the hope that it will be useful,
|
|
|
108 but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
109 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
110 GNU General Public License for more details.
|
|
|
111
|
|
|
112 You should have received a copy of the GNU General Public License
|
|
|
113 along with this program; if not, write to the Free Software
|
|
|
114 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
