Re: clearly deprecate %name-prefix

[Hans Åberg]

> On 3 Jan 2019, at 08:48, Akim Demaille <address@hidden> wrote:
> 
>> 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?

I had to change it myself, that is why I noticed it. :-)