annotate etc/ETAGS.EBNF @ 73113:14833ad68ac0

(Fsingle_key_description): Fix the last change.
author Kenichi Handa <handa@m17n.org>
date Mon, 25 Sep 2006 04:38:18 +0000
parents 3681678d3d86
children 0259a1711394
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
71189
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
3 See the end of this file for copyright information.
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
4
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
5 This file contains two sections:
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
6
57104
27d26db0f6b1 Correct EBNF explanation (Backus-Naur Form rather than Backus Normal Form).
Kim F. Storm <storm@cua.dk>
parents: 57103
diff changeset
7 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
8 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
9 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
10
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
11 ====================== 1) EBNF tag file description =====================
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
12
47054
d0c1bb6d79a0 Forgot a piece, put back in.
Francesco Potortì <pot@gnu.org>
parents: 47053
diff changeset
13 Productions created from current behaviour to aid extensions
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
14 Francesco Potorti` <pot@gnu.org> 2002
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
15 ----------------
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
16
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
17 FF ::= #x0c /* tag section starter */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
18
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
19 LF ::= #x0a /* line 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 DEL ::= #x7f /* pattern terminator */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
22
43857
1e419a707ae1 *** empty log message ***
Francesco Potortì <pot@gnu.org>
parents: 43850
diff changeset
23 SOH ::= #x01 /* name terminator */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
24
43858
8d0430162d52 *** empty log message ***
Francesco Potortì <pot@gnu.org>
parents: 43857
diff changeset
25 regchar ::= [^#x0a#x0c#x7f] /* regular character */
43850
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 regstring ::= { regchar } /* regular string */
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 unsint ::= [0-9] { [0-9] } /* non-negative integer */
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
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 tagfile ::= { tagsection } /* a tags file */
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 tagsection ::= FF LF ( includesec | regularsec ) LF
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 includesec ::= filename ",include" [ LF fileprop ]
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 regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag }
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
40
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
41 filename ::= regchar regstring /* a file name */
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
42
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
43 fileprop ::= "(" regstring ")" /* an elisp alist */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
44
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
45 tag ::= directtag | patterntag
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
46
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
47 directtag ::= DEL realposition /* no pattern */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
48
43857
1e419a707ae1 *** empty log message ***
Francesco Potortì <pot@gnu.org>
parents: 43850
diff changeset
49 patterntag ::= pattern DEL [ tagname SOH ] position
43850
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 pattern ::= regstring /* a tag pattern */
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
52
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
53 tagname ::= regchar regstring /* a tag name */
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
54
45799
147a637372eb Comments added.
Francesco Potortì <pot@gnu.org>
parents: 43858
diff changeset
55 position ::= realposition | "," /* charpos,linepos */
43850
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
56
4c55c058ad72 Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff changeset
57 realposition ::= "," unsint | unsint "," | unsint "," unsint
45946
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 ==================== end of EBNF tag file description ====================
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
60
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
61
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 ======================= 2) discussion of tag names =======================
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
64
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
65 - WHAT ARE TAG NAMES
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
66 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
67 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
68 in the source file to find the tagged line.
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
69
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
70 - WHY TAG NAMES ARE GOOD
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
71 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
72 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
73 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
74 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
75 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
76 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
77
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
78 - 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
79 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
80 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
81 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
82 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
83 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
84 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
85 unnamed tag is the implicit name of that tag.
57103
ed7a08ddfaf8 typo corrected
Francesco Potortì <pot@gnu.org>
parents: 47054
diff changeset
86 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
87 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
88 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
89 order to reduce the size of the tags file.
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
90 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
91 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
92 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
93 those.
45946
c5474d1cf831 Added discussion on tag names.
Francesco Potortì <pot@gnu.org>
parents: 45799
diff changeset
94
47053
b87525d8fbd7 Clarified per rms request.
Francesco Potortì <pot@gnu.org>
parents: 46989
diff changeset
95 ===================== end of discussion of tag names =====================
71189
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
96
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
97 Copyright (c) 2002, 2004, 2006
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
98 Free software Foundation, Inc.
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
99
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
100 COPYING PERMISSIONS:
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
101
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
102 This document is free software; you can redistribute it and/or modify
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
103 it under the terms of the GNU General Public License as published by
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
104 the Free Software Foundation; either version 2 of the License, or
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
105 (at your option) any later version.
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
106
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
107 This program is distributed in the hope that it will be useful,
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
108 but WITHOUT ANY WARRANTY; without even the implied warranty of
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
109 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
110 GNU General Public License for more details.
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
111
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
112 You should have received a copy of the GNU General Public License
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
113 along with this program; if not, write to the Free Software
3681678d3d86 Add copyright notice and copying permissions.
Eli Zaretskii <eliz@gnu.org>
parents: 57104
diff changeset
114 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA