Mercurial > emacs
annotate etc/ETAGS.EBNF @ 69787:b594b04b71fb
*** empty log message ***
author | Kenichi Handa <handa@m17n.org> |
---|---|
date | Tue, 04 Apr 2006 01:32:11 +0000 |
parents | 27d26db0f6b1 |
children | 3681678d3d86 |
rev | line source |
---|---|
46127
6225d6b17d2e
Back to the old explanation, which was more concise, with just the first
Francesco Potortì <pot@gnu.org>
parents:
46126
diff
changeset
|
1 -*- indented-text -*- |
6225d6b17d2e
Back to the old explanation, which was more concise, with just the first
Francesco Potortì <pot@gnu.org>
parents:
46126
diff
changeset
|
2 |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
3 This file contains two sections: |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
4 |
57104
27d26db0f6b1
Correct EBNF explanation (Backus-Naur Form rather than Backus Normal Form).
Kim F. Storm <storm@cua.dk>
parents:
57103
diff
changeset
|
5 1) An EBNF (Extended Backus-Naur Form) description of the format of |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
6 the tags file created by etags.c and interpreted by etags.el; |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
7 2) A discussion of tag names and implicit tag names. |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
8 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
9 ====================== 1) EBNF tag file description ===================== |
45799 | 10 |
47054
d0c1bb6d79a0
Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents:
47053
diff
changeset
|
11 Productions created from current behaviour to aid extensions |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
12 Francesco Potorti` <pot@gnu.org> 2002 |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
13 ---------------- |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
14 |
45799 | 15 FF ::= #x0c /* tag section starter */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
16 |
45799 | 17 LF ::= #x0a /* line terminator */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
18 |
43857
1e419a707ae1
*** empty log message ***
Francesco Potortì <pot@gnu.org>
parents:
43850
diff
changeset
|
19 DEL ::= #x7f /* pattern terminator */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
20 |
43857
1e419a707ae1
*** empty log message ***
Francesco Potortì <pot@gnu.org>
parents:
43850
diff
changeset
|
21 SOH ::= #x01 /* name terminator */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
22 |
43858
8d0430162d52
*** empty log message ***
Francesco Potortì <pot@gnu.org>
parents:
43857
diff
changeset
|
23 regchar ::= [^#x0a#x0c#x7f] /* regular character */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
24 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
25 regstring ::= { regchar } /* regular string */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
26 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
27 unsint ::= [0-9] { [0-9] } /* non-negative integer */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
28 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
29 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
30 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
31 tagfile ::= { tagsection } /* a tags file */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
32 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
33 tagsection ::= FF LF ( includesec | regularsec ) LF |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
34 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
35 includesec ::= filename ",include" [ LF fileprop ] |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
36 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
37 regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag } |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
38 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
39 filename ::= regchar regstring /* a file name */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
40 |
45799 | 41 fileprop ::= "(" regstring ")" /* an elisp alist */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
42 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
43 tag ::= directtag | patterntag |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
44 |
45799 | 45 directtag ::= DEL realposition /* no pattern */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
46 |
43857
1e419a707ae1
*** empty log message ***
Francesco Potortì <pot@gnu.org>
parents:
43850
diff
changeset
|
47 patterntag ::= pattern DEL [ tagname SOH ] position |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
48 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
49 pattern ::= regstring /* a tag pattern */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
50 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
51 tagname ::= regchar regstring /* a tag name */ |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
52 |
45799 | 53 position ::= realposition | "," /* charpos,linepos */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
54 |
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
55 realposition ::= "," unsint | unsint "," | unsint "," unsint |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
56 |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
57 ==================== end of EBNF tag file description ==================== |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
58 |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
59 |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
60 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
61 ======================= 2) discussion of tag names ======================= |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
62 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
63 - WHAT ARE TAG NAMES |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
64 Tag lines in a tags file are usually made from the above defined pattern |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
65 and by an optional tag name. The pattern is a string that is searched |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
66 in the source file to find the tagged line. |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
67 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
68 - WHY TAG NAMES ARE GOOD |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
69 When a user looks for a tag, Emacs first compares the tag with the tag |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
70 names contained in the tags file. If no match is found, Emacs compares |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
71 the tag with the patterns. The tag name is then the preferred way to |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
72 look for tags in the tags file, because when the tag name is present |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
73 Emacs can find a tag faster and more accurately. These tag names are |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
74 part of tag lines in the tags file, so we call them "explicit". |
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
75 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
76 - WHY IMPLICIT TAG NAMES ARE EVEN BETTER |
46127
6225d6b17d2e
Back to the old explanation, which was more concise, with just the first
Francesco Potortì <pot@gnu.org>
parents:
46126
diff
changeset
|
77 When a tag line has no name, but a name can be deduced from the pattern, |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
78 we say that the tag line has an implicit tag name. Often tag names are |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
79 redundant; this happens when the name of a tag is an easily guessable |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
80 substring of the tag pattern. We define a set of rules to decide |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
81 whether it is possible to deduce the tag name from the pattern, and make |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
82 an unnamed tag in those cases. The name deduced from the pattern of an |
47054
d0c1bb6d79a0
Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents:
47053
diff
changeset
|
83 unnamed tag is the implicit name of that tag. |
57103 | 84 When the user looks for a tag, and Emacs finds no explicit tag names |
47054
d0c1bb6d79a0
Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents:
47053
diff
changeset
|
85 that match it, Emacs then looks for an tag whose implicit tag name |
d0c1bb6d79a0
Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents:
47053
diff
changeset
|
86 matches the request. etags.c uses implicit tag names when possible, in |
d0c1bb6d79a0
Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents:
47053
diff
changeset
|
87 order to reduce the size of the tags file. |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
88 An implicit tag name is deduced from the pattern by discarding the |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
89 last character if it is one of ` \f\t\n\r()=,;', then taking all the |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
90 rightmost consecutive characters in the pattern which are not one of |
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
91 those. |
45946
c5474d1cf831
Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents:
45799
diff
changeset
|
92 |
47053
b87525d8fbd7
Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents:
46989
diff
changeset
|
93 ===================== end of discussion of tag names ===================== |