cryptic diagnostics and incorrect reference in manual

[Alexandre Duret-Lutz]

Hi,

ere are some diagnostics from Bison 3.0 that I could not immediately understand,
and some suggestions about parts of the documentation that I think
could be improved.

---

eltlparse.yy:70.1-12: error: %define variable 'api.pure' is not used
 %pure-parser
 ^^^^^^^^^^^^

My first though after reading this is that I should use api.pure in
addition to %pure-parser.
I'd suggest to say "%pure-parser is not supported anymore, use %define
api.pure instead"

---

% bison parser.yy -o foo.$$
parser.yy: warning: conflicting outputs to file ‘foo.20770’ [-Wother]

This one got me puzzled for a while, until I realized it probably meant that
the names for the parser's implementation and header file were equal.
(parser.yy has %defines)

After you understand what is the conflict, you realize this is only a warning.
So you might like to know how that conflict was resolved.

Maybe it could be reformulated as:
  warning: header file not output as its derived filename 'foo.20770'
conflicts with implementation filename [-Wother]

---

I looked at the documentation for -o in an attempt to find the rules
for deriving filenames, but I found this instead:

: `-o FILE'
: `--output=FILE'
:      Specify the FILE for the parser implementation file.
:
:      The other output files' names are constructed from FILE as
:      described under the `-v' and `-d' options.

Maybe someone updated the documentation of -v and -d without
updating this paragraph, because the promised description is not there.

: `-v'
: `--verbose'
:      Pretend that `%verbose' was specified, i.e., write an extra output
:      file containing verbose descriptions of the grammar and parser.
:     *Note Decl Summary::.

: `-d'
:      This is the same as `--defines' except `-d' does not accept a FILE
:      argument since POSIX Yacc requires that `-d' can be bundled with
:     other short options.


Node "Invocation" has some explanations about how filenames are
computed: it gives the rules  .y -> .tab.{c,h}, .y++ -> .tab.{c,h}++, and
.ypp -> .tab.{c,h}pp.   (Shouldn't .yy -> .tab.{cc,hh} be documented as well?)

I find the sentence "This feature takes effect with all options that manipulate
file names like `-o' or `-d'." quite confusing.  It does not make it clear that
what filenames are inferred from which option.


-- 
Alexandre Duret-Lutz