Mercurial > emacs
annotate etc/ETAGS.EBNF @ 99875:3658bfd115cd
* textmodes/artist.el (artist-charlist-to-string): Simplify.
(artist-mode-name, artist-mt, artist-vaporize-fuzziness)
(artist-prev-next-op-alist, artist-mode-line-show-curr-operation)
(artist-replace-string, artist-draw-rect, artist-draw-line)
(artist-undraw-line, artist-draw-sline, artist-undraw-rect)
(artist-rect-corners-squarify, artist-undraw-square, artist-fill-square)
(artist-pen, artist-pen-line, artist-text-insert-common)
(artist-text-overwrite, artist-spray-get-interval)
(artist-spray-clear-circle, artist-erase-char)
(artist-ellipse-generate-quadrant, artist-copy-square, artist-paste)
(artist-flood-fill, artist-key-draw-continously, artist-key-draw-poly)
(artist-key-draw-1point, artist-key-draw-2points)
(artist-mouse-draw-continously): Fix typos in docstrings.
(artist-aspect-ratio, artist-mode, artist-go-get-symbol-shift)
(artist-go-get-symbol-shift-sub, artist-previous-line, artist-next-line)
(artist-backward-char, artist-forward-char): Doc fixes.
(artist-vaporize-line, artist-spray-chars, artist-spray-new-char):
Reflow docstrings.
author | Juanma Barranquero <lekktu@gmail.com> |
---|---|
date | Mon, 24 Nov 2008 16:30:14 +0000 |
parents | c3309dba6542 |
children | c90853557b90 |
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 | 12 |
96376
c3309dba6542
American English spelling fix.
Glenn Morris <rgm@gnu.org>
parents:
95004
diff
changeset
|
13 Productions created from current behavior 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 | 17 FF ::= #x0c /* tag section starter */ |
43850
4c55c058ad72
Description of the tags file format.
Francesco Potortì <pot@gnu.org>
parents:
diff
changeset
|
18 |
45799 | 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 | 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 | 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 | 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 | 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 |
79776 | 97 Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 |
75343
0259a1711394
Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents:
71189
diff
changeset
|
98 Free Software Foundation, Inc. |
71189
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 |
95004
cbf5528cf447
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
79776
diff
changeset
|
102 This document is free software: you can redistribute it and/or modify |
71189
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 |
95004
cbf5528cf447
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
79776
diff
changeset
|
104 the Free Software Foundation, either version 3 of the License, or |
cbf5528cf447
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
79776
diff
changeset
|
105 (at your option) any later version. |
71189
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 |
95004
cbf5528cf447
Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents:
79776
diff
changeset
|
113 along with this program. If not, see <http://www.gnu.org/licenses/>. |