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 | |
1038941d | 6 | the tags file created by etags.c and interpreted by etags.el |
eb39785f FP |
7 | 2) A discussion of tag names and implicit tag names |
8 | ||
9 | ======================= EBNF tag file description ======================= | |
292c80bc | 10 | |
dfd67a62 | 11 | Productions created from current behavior 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 | ||
1038941d | 61 | ======================== discussion of tag names ========================= |
eb39785f FP |
62 | |
63 | - What are tag names | |
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 | ||
68 | - Why tag names are good | |
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 | ||
76 | - Why implicit tag names are even better | |
1038941d FP |
77 | When a tag line has no name, but a name can be deduced from the pattern, |
78 | we say that the tag line has an implicit tag name. etags.c uses | |
79 | implicit tag names when possible, in order to reduce the number of | |
80 | explicit tag names in a tags file, thus reducing the size of the tags | |
81 | file. When the user looks for a tag, and Emacs founds no explicit tag | |
82 | names that match it, Emacs then tries to match the tag with an implicit | |
83 | tag name. Such a match occurs when the tag matches a pattern, subject | |
84 | to the satisfaction of all the following four rules: | |
eb39785f FP |
85 | |
86 | NONAM=" \f\t\n\r()=,;"; | |
87 | 1. the tag does not contain any of the characters in NONAM; | |
88 | 2. the pattern contains the tag as either a rightmost, or rightmost | |
89 | but one character, substring; | |
90 | 3. the character, if any, immediately before the tag in the pattern | |
91 | must be a character in NONAM; | |
92 | 4. the character, if any, immediately after the tag in the pattern | |
93 | must also be a character in NONAM. | |
94 | ||
95 | ===================== end of discussion on tag names ===================== |