From a83202a43698c2ba3990180ad85d6547ea2e9f17 Mon Sep 17 00:00:00 2001
From: Akim Demaille <akim.demaille@gmail.com>
Date: Sat, 7 Aug 2021 07:53:50 +0200
Subject: [PATCH] doc: avoid #define YYDEBUG in C++

* doc/bison.texi (Enabling Traces): here.
---
 TODO           |  3 ---
 doc/bison.texi | 14 ++++++++++----
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/TODO b/TODO
index 2eab7097..0ae9ef89 100644
--- a/TODO
+++ b/TODO
@@ -35,9 +35,6 @@ Clarify that rule numbers in the skeletons are 1-based.
 There are many macros that should obey api.prefix: YY_CPLUSPLUS, YY_MOVE,
 etc.
 
-** YYDEBUG etc. in C++
-Discourage the use of YYDEBUG in C++ (see thread with Jot).
-
 ** yyerrok in Java
 And add tests in calc.at, to prepare work for D.
 
diff --git a/doc/bison.texi b/doc/bison.texi
index beee6f92..b3b69843 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -7000,8 +7000,8 @@ syntax error handling.  @xref{LAC}.
 
 In C/C++, define the macro @code{YYDEBUG} (or @code{@var{prefix}DEBUG} with
 @samp{%define api.prefix @{@var{prefix}@}}), see @ref{Multiple Parsers}) to
-1 in the parser implementation file if it is not already defined, so that
-the debugging facilities are compiled.
+1 (if it is not already defined) so that the debugging facilities are
+compiled.
 
 @item Accepted Values: Boolean
 
@@ -11010,8 +11010,8 @@ defines @code{YYDEBUG} to 1.
 @item the directive @samp{%debug} (deprecated)
 @findex %debug
 Add the @code{%debug} directive (@pxref{Decl Summary}).  This Bison
-extension is maintained for backward compatibility with previous versions of
-Bison; use @code{%define parse.trace} instead.
+extension is maintained for backward compatibility; use @code{%define
+parse.trace} instead.
 
 @item the macro @code{YYDEBUG} (C/C++ only)
 @findex YYDEBUG
@@ -11025,6 +11025,12 @@ Parsers}), for instance @samp{%define
 api.prefix @{c@}}, then if @code{CDEBUG} is defined, its value controls the
 tracing feature (enabled if and only if nonzero); otherwise tracing is
 enabled if and only if @code{YYDEBUG} is nonzero.
+
+In C++, where POSIX compliance makes no sense, avoid this option, and prefer
+@samp{%define parse.trace}.  If you @code{#define} the @code{YYDEBUG} macro
+at the wrong place (e.g., in @samp{%code top} instead of @samp{%code
+require}), the parser class will have two different definitions, thus
+leading to ODR violations and happy debugging times.
 @end table
 
 We suggest that you always enable the trace option so that debugging is