Document __gawk_ver symbol.

In the future, some cppawk headers will react to this symbol's
value, if it is defined.

1 files changed, 34 insertions, 0 deletions

diff --git a/cppawk.1 b/cppawk.1
index e994e07..963f152 100644
--- a/cppawk.1
+++ b/cppawk.1
@@ -153,6 +153,40 @@ Its value is a is an eight digit decimal integer the form
 .IR YYYYMMDD ,
 such as 20220321.
 
+.SH NOT PREDEFINED, SIGNIFICANT SYMBOLS
+.IP \fB__gawk_ver\fR
+Certain
+.B cppawk
+header files may have functionality that depends on GNU Awk.
+
+By default, those
+.B cppawk
+headers which require GNU Awk may assume the latest version released by the GNU
+Awk project, with all of its features and bugfixes.
+
+Consequently, the generate code may not work on older versions of GNU Awk.
+
+The user application, prior to including any
+.B cppawk
+header, may define the macro
+.BI __gawk_ver
+to indicate which version of GNU Awk the generated code is required to work with.
+
+In reaction to this variable, those header files may be able to generate
+alternative code suitable for the indicated version of GNU Awk.
+
+The variable should be a decimal integer, whose last four digits encode the minor
+and build numbers. For instance 4.1.3 is encoded as 40103:
+
+  #define __gawk_ver 40103 // Please support GNU Awk 4.1.3
+  #include <...>           // inclusion of headers follows
+
+Naturally,
+.BI __gawk_ver
+may be specified on the command line with the
+.BI -D
+option.
+
 .SH STANDARD HEADERS
 .B cppawk
 points the preprocessor to look for