Re: [PATCH 4/4] doc: document carets

[Akim Demaille]

Le 4 déc. 2012 à 15:26, Theophile Ranquet <address@hidden> a écrit :

> * NEWS: Announce it.
> * doc/bison.texi (Bison Options):  Here.
> ---
> NEWS           | 13 +++++++++++++
> doc/bison.texi | 44 ++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 57 insertions(+)
> 
> diff --git a/NEWS b/NEWS
> index 2cd57c2..10dc93a 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -2,6 +2,19 @@ GNU Bison NEWS
> 
> * Noteworthy changes in release ?.? (????-??-??) [?]
> 
> +** New option for invoking Bison: -fcaret

Use a better pitch, it won't sell this way :)

> +
> +  Caret errors have been added to Bison, for example (taken from the
> +  documentation):
> +
> +    err.y:4.5-8: error: invalid reference: '$foo'
> +     C: {$foo{bar} };
> +         ^^^^

Poor example.

> +
> +  The default behaviour for now is still not to display these unless 
> explictly
> +  asked with -fall of -fcaret.

Use quotes: '-fcaret'.  s/of/or/, but I wouldn't mention fall (no
pun intended).

> However, in a later release, it will be made the
> +  default behavior (but may still be deactivated with -fno-caret).
> +
> ** New value for %define variable: api.pure full
> 
>   The %define variable api.pure requests a pure (reentrant) parser. However,
> diff --git a/doc/bison.texi b/doc/bison.texi
> index 5952225..ffc8ac8 100644
> --- a/doc/bison.texi
> +++ b/doc/bison.texi
> @@ -9239,6 +9239,50 @@ Treat warnings as errors.
> A category can be turned off by prefixing its name with @samp{no-}.  For
> instance, @option{-Wno-yacc} will hide the warnings about
> POSIX Yacc incompatibilities.
> +
> address@hidden -f address@hidden
> address@hidden address@hidden
> +Activate miscellaneous @var{feature},

{feature}s, or make it valid for singular.

> which can be one of:
> address@hidden @code
> address@hidden caret
> address@hidden diagnostics-show-caret
> +Show caret errors, in a manner similar to GCC's
> address@hidden, or Clang's @option{-fcaret-diagnotics}. The
> +location provided with the message is used to quote the corresponding line of
> +the source file, underlining the important part of it with carets (^). Here 
> is
> +an example, using the following file @file{input.y}:
> +
> address@hidden
> +%%
> +exp : A BBBBB CC;
> +B: 'char';
> +C: @address@hidden@} @};

Third time you burn my eyes, I'm running low on eye balls.

> address@hidden example
> +
> +When invoked with @option{-fcaret}, Bison will output:

s/output/report/

> +
> address@hidden
> +err.y:3.4-9: warning: extra characters in character literal
> + B: 'char';
> +    ^^^^^^

Use @group where appropriate.

> +err.y:2.7: error: symbol A is used, but is not defined as a token and has no 
> rules
> + exp : A BBBBB CC;
> +       ^
> +err.y:2.9-13: error: symbol BBBBB is used, but is not defined as a token and 
> has no rules
> + exp : A BBBBB CC;
> +         ^^^^^
> +err.y:2.15-16: error: symbol CC is used, but is not defined as a token and 
> has no rules
> + exp : A BBBBB CC;
> +               ^^
> +err.y:4.5-8: error: invalid reference: '$foo'
> + C: @address@hidden@} @};
> +     ^^^^
> +err.y:4.4-15:    symbol not found in production: foo
> + C: @address@hidden@} @};
> +    ^^^^^^^^^^^^
> address@hidden example

I would really prefer a more sensible example.