Re: clearly deprecate %name-prefix

[Akim Demaille]

Hi Hans,

> Le 2 janv. 2019 à 20:44, Hans Åberg <address@hidden> a écrit :
> 
> 
>> On 2 Jan 2019, at 19:25, Akim Demaille <address@hidden> wrote:
>> 
>>   * doc/bison.texi: Document that %name-prefix is replaced by %define
>>   api.prefix.
> 
> The formulation in the manual, sec. 3.8, is a bit confusing, a casual reading 
> might be read as though the extra %define being a part of a syntax 
> description.
> 
> Maybe something like:
> 
> The easy way to do this is to define the variable api.prefix using the syntax 
> ‘%define api.prefix {prefix}’.

I see what you mean, but "a %define variable" is the style used through out the 
documentation.  And I believe that the casual reader can wait a few sentences 
more to have all the details:

>    The easy way to do this is to define the ‘%define’ variable
> ‘api.prefix’.  With different ‘api.prefix’s it is guaranteed that
> headers do not conflict when included together, and that compiled
> objects can be linked together too.  Specifying ‘%define api.prefix
> {PREFIX}’ (or passing the option ‘-Dapi.prefix={PREFIX}’, see *note
> Invoking Bison: Invocation.) renames the interface functions and
> variables of the Bison parser to start with PREFIX instead of ‘yy’, and
> all the macros to start by PREFIX (i.e., PREFIX upper-cased) instead of
> ‘YY’.

Do you think that by the end of the complete paragraph the user is still 
confused?