PACKAGE_VERSION should not be renamed

[Gavin Smith]

On Sun, Nov 05, 2023 at 12:13:00PM +0100, Arsen Arsenović wrote:
> Oh, interesting.  On my system, I'm using texinfo built from master, and
> it completely lacks PACKAGE_VERSION!  (if I rebuild from releases/7.1,
> it's present).  It looks like it got removed in
> 6a1a78b941a832033b8939ab4cdce1646dd56904.

It's still stated as PACKAGE_VERSION in doc/texinfo.texi, even though it's
mentioned in NEWS now.  If the customization variable is changing name,
then the manual should be updated as well.

However, I doubt that it is justified to rename it.  We know it is an
option, so what is the point of putting _OPTION on the end to get
PACKAGE_VERSION_OPTION?

Especially since it is used as part of the cutomization API, it
seems that this should be a stable option.  Here is a link to a patch
to fix building ffmpeg docs:

http://ffmpeg.org/pipermail/ffmpeg-devel/2023-November/316605.html

Including version checks using PACKAGE_VERSION:

   # determine if texinfo is at least version 6.8
  -my $program_version_num = 
version->declare(get_conf('PACKAGE_VERSION'))->numify;
  +my $program_version_num = 
version->declare(ff_get_conf('PACKAGE_VERSION'))->numify;
   my $program_version_6_8 = $program_version_num >= 6.008000;
   
   # print the TOC where @contents is used
   if ($program_version_6_8) {
  -    set_from_init_file('CONTENTS_OUTPUT_LOCATION', 'inline');
  +    ff_set_from_init_file('CONTENTS_OUTPUT_LOCATION', 'inline');
   } else {
  -    set_from_init_file('INLINE_CONTENTS', 1);
  +    ff_set_from_init_file('INLINE_CONTENTS', 1);
   }

If the customization API is likely to break easily (and speaking generally,
it seems to me that any API like this is likely to, and the more it is
integrated into the "guts" of the program, the more likely it is to, although
I am not very familiar with the texi2any customization API), then at
least PACKAGE_VERSION gives packages a chance to adapt, so should be stable
if nothing else is.

In commit 6a1a78b941a832033b (2023-09-13) (*), it is said to avoid
clashing with macros defined in config.h.  This is the details of the
implementation and something we could work around, rather than changing
the user-visible interface.  It's currently used in the definition of
the OPTIONS type in tp/Texinfo/XS/main/options_types.h.

This could be dealt with in a variety of ways.  The most straightforward
would be to "#undef PACKAGE_VERSION" at the beginning of option_types.h.
That way, any source code file using the OPTIONS type and including
this file will not have that preprocessor definition active throughout
the file.

We do not use the PACKAGE_VERSION from the build system for the XS code
and it simply has the value "0".  (In the top-level build system, it is
the version of the package, currently "7.1dev".)

It's also not necessary that we use the symbol PACKAGE_VERSION in the XS/C
code to refer to this option, so could be renamed to o_PACKAGE_VERSION
as a special case if the #undef option does not work or is not appropriate
for some reason.

(*) My preference is to always state at least the date as well as the
git commit ID -- that way, if we ever move to a version control system
other than git, then somebody reading the mailing list archives will
find it easier to find which commit it is.  It's useful information to
have, in any case.