Commit | Line | Data |
---|---|---|
1038941d FP |
1 | -*- indented-text -*- |
2 | ||
b727702b EZ |
3 | See the end of this file for copyright information. |
4 | ||
eb39785f FP |
5 | This file contains two sections: |
6 | ||
be812246 | 7 | 1) An EBNF (Extended Backus-Naur Form) description of the format of |
d62c4c32 FP |
8 | the tags file created by etags.c and interpreted by etags.el; |
9 | 2) A discussion of tag names and implicit tag names. | |
eb39785f | 10 | |
d62c4c32 | 11 | ====================== 1) EBNF tag file description ===================== |
292c80bc | 12 | |
fffa137c | 13 | Productions created from current behavior to aid extensions |
717a0a0d | 14 | Francesco Potorti` <pot@gnu.org> 2002 |
eb39785f | 15 | ---------------- |
717a0a0d | 16 | |
292c80bc | 17 | FF ::= #x0c /* tag section starter */ |
717a0a0d | 18 | |
292c80bc | 19 | LF ::= #x0a /* line terminator */ |
717a0a0d | 20 | |
a13d6523 | 21 | DEL ::= #x7f /* pattern terminator */ |
717a0a0d | 22 | |
a13d6523 | 23 | SOH ::= #x01 /* name terminator */ |
717a0a0d | 24 | |
a13d6523 | 25 | regchar ::= [^#x0a#x0c#x7f] /* regular character */ |
717a0a0d FP |
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 | ||
292c80bc | 43 | fileprop ::= "(" regstring ")" /* an elisp alist */ |
717a0a0d FP |
44 | |
45 | tag ::= directtag | patterntag | |
46 | ||
292c80bc | 47 | directtag ::= DEL realposition /* no pattern */ |
717a0a0d | 48 | |
a13d6523 | 49 | patterntag ::= pattern DEL [ tagname SOH ] position |
717a0a0d FP |
50 | |
51 | pattern ::= regstring /* a tag pattern */ | |
52 | ||
53 | tagname ::= regchar regstring /* a tag name */ | |
54 | ||
292c80bc | 55 | position ::= realposition | "," /* charpos,linepos */ |
717a0a0d FP |
56 | |
57 | realposition ::= "," unsint | unsint "," | unsint "," unsint | |
eb39785f FP |
58 | |
59 | ==================== end of EBNF tag file description ==================== | |
60 | ||
61 | ||
62 | ||
d62c4c32 | 63 | ======================= 2) discussion of tag names ======================= |
eb39785f | 64 | |
d62c4c32 | 65 | - WHAT ARE TAG NAMES |
eb39785f FP |
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 | ||
d62c4c32 | 70 | - WHY TAG NAMES ARE GOOD |
eb39785f FP |
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 | ||
d62c4c32 | 78 | - WHY IMPLICIT TAG NAMES ARE EVEN BETTER |
1038941d | 79 | When a tag line has no name, but a name can be deduced from the pattern, |
d62c4c32 FP |
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 | |
d06b424c | 85 | unnamed tag is the implicit name of that tag. |
f3aa617f | 86 | When the user looks for a tag, and Emacs finds no explicit tag names |
d06b424c FP |
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. | |
d62c4c32 FP |
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 ===================== | |
b727702b | 96 | |
73b0cd50 | 97 | Copyright (C) 2002-2011 Free Software Foundation, Inc. |
b727702b EZ |
98 | |
99 | COPYING PERMISSIONS: | |
100 | ||
ab73e885 | 101 | This document is free software: you can redistribute it and/or modify |
b727702b | 102 | it under the terms of the GNU General Public License as published by |
ab73e885 GM |
103 | the Free Software Foundation, either version 3 of the License, or |
104 | (at your option) any later version. | |
b727702b EZ |
105 | |
106 | This program is distributed in the hope that it will be useful, | |
107 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
108 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
109 | GNU General Public License for more details. | |
110 | ||
111 | You should have received a copy of the GNU General Public License | |
ab73e885 | 112 | along with this program. If not, see <http://www.gnu.org/licenses/>. |