[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Kaz Kylheku
Subject: [PATCH]: Suggested documentation about working with Bison versions.
Date: Tue, 13 Oct 2020 17:11:04 -0700
User-agent: Roundcube Webmail/0.9.2

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 <>
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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]