Mercurial > hg > xemacs-beta
annotate etc/ETAGS.EBNF @ 5872:f9e59cd39a9a
Clean up #'read-quoted-char, support help-event-list there.
lisp/changeLog addition:
2015-03-14 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (quoted-insert):
Update the docstring here, syncing GNU's, especially mentioning
read-quoted-char-radix.
* cmdloop.el:
* cmdloop.el (read-quoted-char-radix): Move this up here, outside
the functions.
* cmdloop.el (read-function-key-map): New label, reading and
replacing characters from function-key-map if appropriate.
* cmdloop.el (read-quoted-char): Multiple changes:
-- Take advantage of help-event-list, but be careful not to have
any keystrokes with character equivalents in it, so the user can
type C-q C-h and have the expected result.
-- Use function-key-map, as does #'read-char and
#'read-exclusive-char, helpful for character composition under
X11.
-- Pop up the help window ourselves if, e.g. F1 arrives on a TTY
via function-key-map, event-stream won't have done it.
-- Error if no keystroke that can be converted into a character is
specified, don't just insert ?\x00 as we used to and as does GNU
-- Use #'digit-char-p instead of reimplementing it.
-- Fix a bug of mine where I wasn't consistent about treating
character codes as Unicode.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Tue, 17 Mar 2015 12:22:50 +0000 |
| parents | 308d34e9f07d |
| children |
| rev | line source |
|---|---|
| 2225 | 1 -*- indented-text -*- |
| 2 | |
| 3876 | 3 See the end of this file for copyright information. |
| 4 | |
| 2225 | 5 This file contains two sections: |
| 6 | |
| 2554 | 7 1) An EBNF (Extended Backus-Naur Form) description of the format of |
| 2225 | 8 the tags file created by etags.c and interpreted by etags.el; |
| 9 2) A discussion of tag names and implicit tag names. | |
| 10 | |
| 11 ====================== 1) EBNF tag file description ===================== | |
| 12 | |
| 13 Productions created from current behaviour to aid extensions | |
| 14 Francesco Potorti` <pot@gnu.org> 2002 | |
| 15 ---------------- | |
| 16 | |
| 17 FF ::= #x0c /* tag section starter */ | |
| 18 | |
| 19 LF ::= #x0a /* line terminator */ | |
| 20 | |
| 21 DEL ::= #x7f /* pattern terminator */ | |
| 22 | |
| 23 SOH ::= #x01 /* name terminator */ | |
| 24 | |
| 25 regchar ::= [^#x0a#x0c#x7f] /* regular character */ | |
| 26 | |
| 27 regstring ::= { regchar } /* regular string */ | |
| 28 | |
| 29 unsint ::= [0-9] { [0-9] } /* non-negative integer */ | |
| 30 | |
| 31 | |
| 32 | |
| 33 tagfile ::= { tagsection } /* a tags file */ | |
| 34 | |
| 35 tagsection ::= FF LF ( includesec | regularsec ) LF | |
| 36 | |
| 37 includesec ::= filename ",include" [ LF fileprop ] | |
| 38 | |
| 39 regularsec ::= filename "," [ unsint ] [ LF fileprop ] { LF tag } | |
| 40 | |
| 41 filename ::= regchar regstring /* a file name */ | |
| 42 | |
| 43 fileprop ::= "(" regstring ")" /* an elisp alist */ | |
| 44 | |
| 45 tag ::= directtag | patterntag | |
| 46 | |
| 47 directtag ::= DEL realposition /* no pattern */ | |
| 48 | |
| 49 patterntag ::= pattern DEL [ tagname SOH ] position | |
| 50 | |
| 51 pattern ::= regstring /* a tag pattern */ | |
| 52 | |
| 53 tagname ::= regchar regstring /* a tag name */ | |
| 54 | |
| 55 position ::= realposition | "," /* charpos,linepos */ | |
| 56 | |
| 57 realposition ::= "," unsint | unsint "," | unsint "," unsint | |
| 58 | |
| 59 ==================== end of EBNF tag file description ==================== | |
| 60 | |
| 61 | |
| 62 | |
| 63 ======================= 2) discussion of tag names ======================= | |
| 64 | |
| 65 - WHAT ARE TAG NAMES | |
| 66 Tag lines in a tags file are usually made from the above defined pattern | |
| 67 and by an optional tag name. The pattern is a string that is searched | |
| 68 in the source file to find the tagged line. | |
| 69 | |
| 70 - WHY TAG NAMES ARE GOOD | |
| 71 When a user looks for a tag, Emacs first compares the tag with the tag | |
| 72 names contained in the tags file. If no match is found, Emacs compares | |
| 73 the tag with the patterns. The tag name is then the preferred way to | |
| 74 look for tags in the tags file, because when the tag name is present | |
| 75 Emacs can find a tag faster and more accurately. These tag names are | |
| 76 part of tag lines in the tags file, so we call them "explicit". | |
| 77 | |
| 78 - WHY IMPLICIT TAG NAMES ARE EVEN BETTER | |
| 79 When a tag line has no name, but a name can be deduced from the pattern, | |
| 80 we say that the tag line has an implicit tag name. Often tag names are | |
| 81 redundant; this happens when the name of a tag is an easily guessable | |
| 82 substring of the tag pattern. We define a set of rules to decide | |
| 83 whether it is possible to deduce the tag name from the pattern, and make | |
| 84 an unnamed tag in those cases. The name deduced from the pattern of an | |
| 85 unnamed tag is the implicit name of that tag. | |
| 2325 | 86 When the user looks for a tag, and Emacs finds no explicit tag names |
| 2225 | 87 that match it, Emacs then looks for an tag whose implicit tag name |
| 88 matches the request. etags.c uses implicit tag names when possible, in | |
| 89 order to reduce the size of the tags file. | |
| 90 An implicit tag name is deduced from the pattern by discarding the | |
| 91 last character if it is one of ` \f\t\n\r()=,;', then taking all the | |
| 92 rightmost consecutive characters in the pattern which are not one of | |
| 93 those. | |
| 94 | |
| 95 ===================== end of discussion of tag names ===================== | |
| 3876 | 96 |
| 97 Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007 | |
| 98 Free Software Foundation, Inc. | |
| 99 | |
| 100 COPYING PERMISSIONS: | |
| 101 | |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
102 This file is part of XEmacs. |
| 3876 | 103 |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
104 XEmacs is free software: you can redistribute it and/or modify it |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
105 under the terms of the GNU General Public License as published by the |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
106 Free Software Foundation, either version 3 of the License, or (at your |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
107 option) any later version. |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
108 |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
109 XEmacs is distributed in the hope that it will be useful, but WITHOUT |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
110 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
111 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
112 for more details. |
| 3876 | 113 |
| 114 You should have received a copy of the GNU General Public License | |
|
5402
308d34e9f07d
Changed bulk of GPLv2 or later files identified by script
Mats Lidell <matsl@xemacs.org>
parents:
3876
diff
changeset
|
115 along with XEmacs. If not, see <http://www.gnu.org/licenses/>. |