2225
+ − 1 -*- indented-text -*-
+ − 2
+ − 3 This file contains two sections:
+ − 4
+ − 5 1) An EBNF (Extended Backus Normal Form) description of the format of
+ − 6 the tags file created by etags.c and interpreted by etags.el;
+ − 7 2) A discussion of tag names and implicit tag names.
+ − 8
+ − 9 ====================== 1) EBNF tag file description =====================
+ − 10
+ − 11 Productions created from current behaviour to aid extensions
+ − 12 Francesco Potorti` <pot@gnu.org> 2002
+ − 13 ----------------
+ − 14
+ − 15 FF ::= #x0c /* tag section starter */
+ − 16
+ − 17 LF ::= #x0a /* line terminator */
+ − 18
+ − 19 DEL ::= #x7f /* pattern terminator */
+ − 20
+ − 21 SOH ::= #x01 /* name terminator */
+ − 22
+ − 23 regchar ::= [^#x0a#x0c#x7f] /* regular character */
+ − 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
+ − 41 fileprop ::= "(" regstring ")" /* an elisp alist */
+ − 42
+ − 43 tag ::= directtag | patterntag
+ − 44
+ − 45 directtag ::= DEL realposition /* no pattern */
+ − 46
+ − 47 patterntag ::= pattern DEL [ tagname SOH ] position
+ − 48
+ − 49 pattern ::= regstring /* a tag pattern */
+ − 50
+ − 51 tagname ::= regchar regstring /* a tag name */
+ − 52
+ − 53 position ::= realposition | "," /* charpos,linepos */
+ − 54
+ − 55 realposition ::= "," unsint | unsint "," | unsint "," unsint
+ − 56
+ − 57 ==================== end of EBNF tag file description ====================
+ − 58
+ − 59
+ − 60
+ − 61 ======================= 2) discussion of tag names =======================
+ − 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
+ − 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. Often tag names are
+ − 79 redundant; this happens when the name of a tag is an easily guessable
+ − 80 substring of the tag pattern. We define a set of rules to decide
+ − 81 whether it is possible to deduce the tag name from the pattern, and make
+ − 82 an unnamed tag in those cases. The name deduced from the pattern of an
+ − 83 unnamed tag is the implicit name of that tag.
2325
+ − 84 When the user looks for a tag, and Emacs finds no explicit tag names
2225
+ − 85 that match it, Emacs then looks for an tag whose implicit tag name
+ − 86 matches the request. etags.c uses implicit tag names when possible, in
+ − 87 order to reduce the size of the tags file.
+ − 88 An implicit tag name is deduced from the pattern by discarding the
+ − 89 last character if it is one of ` \f\t\n\r()=,;', then taking all the
+ − 90 rightmost consecutive characters in the pattern which are not one of
+ − 91 those.
+ − 92
+ − 93 ===================== end of discussion of tag names =====================
