api.token.constructor not described accurately,

[Arthur Schwarz]

Section 3.7.13 page 88
Section 10.1.5.2 page 163

The issues are:
1: The term "a complete symbol" has no referent and needs explanation. Might I 
suggest that this be described as a 3-tuple consisting of <token type, token 
value, token position> rather than as it is described. 

2: The class location and position are different in C++. yylex() returns an 
instance of the position not the location, so as it stands, the prototype 
description is incorrect. Further, non-terminals, aka, groupings use locations 
not positions.
3: Is the 3-tuple used by the parser in propagating values between 
non-terminals.
4: What does the parser do to propagate values in non-terminals. The document 
has previously mention, e.g., $$ = $1 as a default and further has explained 
that @$ = @1, and further described code sections and the use of $n and @n. How 
does this change?
5: "and possibly its location (yylloc)" and "If location tracking is enabled, 
also pass the location"has no tangible meaning. Exactly what happens. If  
%locations is not specified then is the argument optional, not used, defaulted, 
the interface generated differently? What? This is a manual after all.
6:Issue 5: occurs for make_token(), suppose %locations is not present.
7: [Make on symbol_type]? Do you mean that symbol_type is a C++ class and that 
the methods symbol_type(...), make_(...) are methods in this class? If so it 
should be so stated. Else, what is it.
8: The descriptions of make_token are negligent. You probably mean to say 
something like the %token TOKEN names are used to generate the make_TOKEN() 
construtors, and that these constructors are static factories for the 
symbol_type class which call symbol_type(...) with the correct parameters et 
alia.
9: You should stress the reason why ':' can not be used and that COLON must be 
used, and your explanation should include some reasoning.
10: You should also mention that "<=", multi-character tokens, can not be used 
and also provide a rationale.
11: The function "text_to_int" is not part of standard C++. However, atoi() is. 
Provide a referent for the "text_to_int function" or use atoi().
12: You should relate yy::parser::... to the interface file x.tab.hh and the 
samespace "yy" and the class "yy::parse" somewhere in this manual. I don't 
believe it has ever been mentioned.
13: I am a tad confused about "%define api.token.prefix {TOK_}" and the 
make_TOKEN() methods. Shouldn't these be make_TOK_IDENTIFIER() and 
make_TOK_INTEGER() and make_TOK_COLON()? for use in yylex()?

Sorry about the abruptness of the comments.
art