X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/b931235eb9e55277e0147443f916c0f73ad697c4..8ec0a172bcae50565b68288a32c0dd9368eee8ad:/NEWS

diff --git a/NEWS b/NEWS
index a1bf9ae1..dd36e633 100644
--- a/NEWS
+++ b/NEWS
@@ -9,6 +9,70 @@ Changes in version 2.3+:
   helps to sanitize the global namespace during preprocessing, but POSIX Yacc
   requires them.  Bison still generates an enum for token names in all cases.
 
+* Handling of traditional Yacc prologue blocks is now more consistent but
+  potentially incompatible with previous releases of Bison.
+
+  As before, you declare prologue blocks in your grammar file with the
+  `%{ ... %}' syntax.  To generate the pre-prologue, Bison concatenates all
+  prologue blocks that you've declared before the first %union.  To generate
+  the post-prologue, Bison concatenates all prologue blocks that you've
+  declared after the first %union.  
+
+  Previous releases of Bison inserted the pre-prologue into both the header
+  file and the code file in all cases except for LALR(1) parsers in C.  In the
+  latter case, Bison inserted it only into the code file.  For parsers in C++,
+  the point of insertion was before any token definitions (which associate
+  token numbers with names).  For parsers in C, the point of insertion was
+  after the token definitions.
+
+  Now, Bison never inserts the pre-prologue into the header file.  In the code
+  file, it always inserts it before the token definitions.
+
+* Bison now provides a more flexible alternative to the traditional Yacc
+  prologue blocks: %before-header, %start-header, %end-header, and
+  %after-header.
+
+  For example, the following declaration order in the grammar file reflects the
+  order in which Bison will output these code blocks.  However, you are free to
+  declare these code blocks in your grammar file in whatever order is most
+  convenient for you:
+
+    %before-header {
+      /* Bison treats this block like a pre-prologue block: it inserts it into
+       * the code file before the contents of the header file.  It does *not*
+       * insert it into the header file.  This is a good place to put
+       * #include's that you want at the top of your code file.  A common
+       * example is `#include "system.h"'.  */
+    }
+    %start-header {
+      /* Bison inserts this block into both the header file and the code file.
+       * In both files, the point of insertion is before any Bison-generated
+       * token, semantic type, location type, and class definitions.  This is a
+       * good place to define %union dependencies, for example.  */
+    }
+    %union {
+      /* Unlike the traditional Yacc prologue blocks, the output order for the
+       * new %*-header blocks is not affected by their declaration position
+       * relative to any %union in the grammar file.  */
+    }
+    %end-header {
+      /* Bison inserts this block into both the header file and the code file.
+       * In both files, the point of insertion is after the Bison-generated
+       * definitions.  This is a good place to declare or define public
+       * functions or data structures that depend on the Bison-generated
+       * definitions.  */
+    }
+    %after-header {
+      /* Bison treats this block like a post-prologue block: it inserts it into
+       * the code file after the contents of the header file.  It does *not*
+       * insert it into the header file.  This is a good place to declare or
+       * define internal functions or data structures that depend on the
+       * Bison-generated definitions.  */
+    }
+
+  If you have multiple occurrences of any one of the above declarations, Bison
+  will concatenate the contents in declaration order.
+
 * The option `--report=look-ahead' has been changed to `--report=lookahead'.
   The old spelling still works, but is not documented and may be removed
   in a future release.