[PATCH]: Suggested documentation about working with Bison versions.

I think this information is critically missing from the documentation.

Most of the development tools we use in the freeware world are obsessive 
about backward compatibility, which makes it very easy for people to 
have the wrong idea going into Bison. People who start with portable 
Yacc code but introduce Bison features may also have the wrong 
expectations.

The documentation should manage or re-adjust these wrong expectations, 
and
explain how things actually are.

Maybe some better wording can be found for the headings and content.


Author: Kaz Kylheku <[email protected]>
Date:   Tue Oct 13 15:39:41 2020 -0700

     doc: document best deployment practices.

     * doc/bison.texi (Versioning): New node about practices
     regarding dealing with multiple versions of Bison.

diff --git a/doc/bison.texi b/doc/bison.texi
index 67494d35..3f41b077 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -244,6 +244,7 @@ Cover art by Etienne Suvasa.
  * Invocation::          How to run Bison (to produce the parser 
implementation).
  * Other Languages::     Creating C++, D and Java parsers.
  * History::             How Bison came to be
+* Versioning::          Dealing with Bison versioning
  * FAQ::                 Frequently Asked Questions
  * Table of Symbols::    All the keywords of the Bison language are 
explained.
  * Glossary::            Basic concepts are explained.
@@ -550,6 +551,10 @@ A Brief History of the Greater Ungulates
  * Bison::                       This program
  * Other Ungulates::             Similar programs

+Bison Version Compatibility
+
+* Versioning::                  Dealing with Bison versioning
+
  Frequently Asked Questions

  * Memory Exhausted::            Breaking the Stack Limits
@@ -14918,6 +14923,62 @@ still in use is David Beazley's ``PLY'' (Python 
Lex-Yacc) for
  Python. Another is goyacc, supporting the Go language. An ``ocamlyacc''
  is shipped as part of the Ocaml compiler suite.

+@c ================================================= Version 
Compatibility
+
+@node Versioning
+
+@chapter Bison Version Compatibility: Best Practices
+@cindex version
+@cindex compatibility
+
+Bison provides a Yacc compatibility mode in which it strives to conform 
with
+the POSIX standard. Grammar files which are written to the POSIX 
standard, and
+do not take advantage of any of the special capabilities of Bison, are 
very
+likely to work with many version of Bison without modification.
+
+All other features of Bison are particular to Bison, and are changing. 
Bison is
+actively maintained and continuously evolving.  It should come as no 
surprise
+that an older version of Bison will not accept Bison source code which 
uses
+newer features that do no not exist at all in the older Bison.  
Regrettably, in
+spite of reasonable effort to maintain compatibility, the reverse 
situation may
+also occur: it may happen that code developed using an older version of 
Bison
+does not build with a newer version of Bison without modifications.
+
+Because Bison is a code generation tool, it is possible to retain its 
output
+and distribute that to the users of the program. The users are then not 
required
+to have Bison installed at all, only an implementation of the 
programming
+language, such as C, which is required for processing the generated 
output.
+
+It is the output of Bison that is intended to be of the utmost 
portability.
+So, that is to say, whereas the Bison grammar source code may have a 
dependency
+on specific versions of Bison, the generated parser from any version of 
Bison
+should work with with a large number of implementations of C, or 
whatever
+language is applicable.
+
+The recommended best practice for using Bison (in the context of 
software that
+is distributed in source code form) is to ship the generated parser to 
the
+downstream users. Only those downstream users who engage in active 
development
+of the program who need to make changes to the grammar file need to 
have Bison
+installed at all, and those users can install the specific version of 
Bison
+which is required.
+
+Following this recommended practice also makes it possible to use a 
more recent
+Bison than what is available to users through operating system 
distributions,
+thereby taking advantage of the latest techniques that Bison allows.
+
+Some features of Bison have been, or are being adopted into other 
Yacc-like
+programs. Therefore it might seem that is a good idea to write grammar 
code
+which targets multiple implementations, similarly to the way C programs 
are
+often written to target multiple compilers and language versions. This 
practice
+is not highly recommended, however. Other than the Yacc subset 
described by
+POSIX, the Bison language is not rigorously standardized. When a Bison 
feature
+is adopted by another parser generator, it may be initially compatible 
with
+that version of Bison on which it was based, but the compatibility may 
degrade
+going forward.  Developers who strive to make their Bison code 
simultaneously
+compatible with other parser generators are encouraged to nevertheless 
use
+specific versions of all generators, and still follow the recommended 
practice
+of shipping generated output.
+
  @c ================================================= FAQ

  @node FAQ