Commit | Line | Data |
---|---|---|
1038941d FP |
1 | -*- indented-text -*- |
2 | ||
eb39785f FP |
3 | This file contains two sections: |
4 | ||
5 | 1) An EBNF (Extended Backus Normal Form) description of the format of | |
d62c4c32 FP |
6 | the tags file created by etags.c and interpreted by etags.el; |
7 | 2) A discussion of tag names and implicit tag names. | |
eb39785f | 8 | |
d62c4c32 | 9 | ====================== 1) EBNF tag file description ===================== |
292c80bc | 10 | |
d06b424c | 11 | Productions created from current behaviour to aid extensions |
717a0a0d | 12 | Francesco Potorti` <pot@gnu.org> 2002 |
eb39785f | 13 | ---------------- |
717a0a0d | 14 | |
292c80bc | 15 | FF ::= #x0c /* tag section starter */ |
717a0a0d | 16 | |
292c80bc | 17 | LF ::= #x0a /* line terminator */ |
717a0a0d | 18 | |
a13d6523 | 19 | DEL ::= #x7f /* pattern terminator */ |
717a0a0d | 20 | |
a13d6523 | 21 | SOH ::= #x01 /* name terminator */ |
717a0a0d | 22 | |
a13d6523 | 23 | regchar ::= [^#x0a#x0c#x7f] /* regular character */ |
717a0a0d FP |
24 | |
25 | regstring ::= { regchar } /* regular string */ | |
26 | ||
27 | unsint ::= [0-9] { [0-9] } /* non-negative integer */ | |
28 | ||
29 | ||
30 | ||
31 | tagfile ::= { tagsection } /* a tags file */ | |
32 | ||
33 | tagsection ::= FF LF ( includesec | regularsec ) LF | |
34 | ||
35 | includesec ::= filename ",include" [ LF fileprop ] | |
36 | ||
37 | regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag } | |
38 | ||
39 | filename ::= regchar regstring /* a file name */ | |
40 | ||
292c80bc | 41 | fileprop ::= "(" regstring ")" /* an elisp alist */ |
717a0a0d FP |
42 | |
43 | tag ::= directtag | patterntag | |
44 | ||
292c80bc | 45 | directtag ::= DEL realposition /* no pattern */ |
717a0a0d | 46 | |
a13d6523 | 47 | patterntag ::= pattern DEL [ tagname SOH ] position |
717a0a0d FP |
48 | |
49 | pattern ::= regstring /* a tag pattern */ | |
50 | ||
51 | tagname ::= regchar regstring /* a tag name */ | |
52 | ||
292c80bc | 53 | position ::= realposition | "," /* charpos,linepos */ |
717a0a0d FP |
54 | |
55 | realposition ::= "," unsint | unsint "," | unsint "," unsint | |
eb39785f FP |
56 | |
57 | ==================== end of EBNF tag file description ==================== | |
58 | ||
59 | ||
60 | ||
d62c4c32 | 61 | ======================= 2) discussion of tag names ======================= |
eb39785f | 62 | |
d62c4c32 | 63 | - WHAT ARE TAG NAMES |
eb39785f FP |
64 | Tag lines in a tags file are usually made from the above defined pattern |
65 | and by an optional tag name. The pattern is a string that is searched | |
66 | in the source file to find the tagged line. | |
67 | ||
d62c4c32 | 68 | - WHY TAG NAMES ARE GOOD |
eb39785f FP |
69 | When a user looks for a tag, Emacs first compares the tag with the tag |
70 | names contained in the tags file. If no match is found, Emacs compares | |
71 | the tag with the patterns. The tag name is then the preferred way to | |
72 | look for tags in the tags file, because when the tag name is present | |
73 | Emacs can find a tag faster and more accurately. These tag names are | |
74 | part of tag lines in the tags file, so we call them "explicit". | |
75 | ||
d62c4c32 | 76 | - WHY IMPLICIT TAG NAMES ARE EVEN BETTER |
1038941d | 77 | When a tag line has no name, but a name can be deduced from the pattern, |
d62c4c32 FP |
78 | we say that the tag line has an implicit tag name. Often tag names are |
79 | redundant; this happens when the name of a tag is an easily guessable | |
80 | substring of the tag pattern. We define a set of rules to decide | |
81 | whether it is possible to deduce the tag name from the pattern, and make | |
82 | an unnamed tag in those cases. The name deduced from the pattern of an | |
d06b424c FP |
83 | unnamed tag is the implicit name of that tag. |
84 | When the user looks for a tag, and Emacs founds no explicit tag names | |
85 | that match it, Emacs then looks for an tag whose implicit tag name | |
86 | matches the request. etags.c uses implicit tag names when possible, in | |
87 | order to reduce the size of the tags file. | |
d62c4c32 FP |
88 | An implicit tag name is deduced from the pattern by discarding the |
89 | last character if it is one of ` \f\t\n\r()=,;', then taking all the | |
90 | rightmost consecutive characters in the pattern which are not one of | |
91 | those. | |
92 | ||
93 | ===================== end of discussion of tag names ===================== |