Subject: Re: bug#49719: 27.2; make-manuals fails

From: Eli Zaretskii <[email-masked]>
Date: Mon, 04 Apr 2022 20:44:54 +0300

> Date: Sat, 24 Jul 2021 19:46:27 +0300
> From: Eli Zaretskii <[email-masked]>
> Cc: [email-masked]
> 
> > From: Lars Ingebrigtsen <[email-masked]>
> > Cc: [email-masked]
> > Date: Sat, 24 Jul 2021 18:37:00 +0200
> > 
> > [larsi@stories ~/src/emacs/emacs-27]$ ./admin/make-manuals 
> > Making manuals (slow)...
> > Adding compressed html files...
> > Making manual tarfiles...
> > Doing emacs...
> > ...created emacs-manual-27.2.50.tar
> > Doing lispref...
> > ...created emacs-lispref-27.2.50.tar
> > Doing lispintro...
> > ...created emacs-lispintro-27.2.50.tar
> > Doing misc...
> > ...created emacs-misc-27.2.50.tar
> > Making refcards...
> > 
> > But this is with an older makeinfo:
> > 
> > [larsi@stories ~/src/emacs/emacs-27]$ makeinfo --version
> > texi2any (GNU texinfo) 6.7
> 
> Yes, with that version it worked for me as well, back when I updated
> the manuals for the v27.2 release.

Nine months later, the script (admin/make-manuals) still doesn't work
with the latest Texinfo.  The end result is that right now, I'm unable
to update the Emacs on-line docs to the version that was released with
Emacs 28.1.  (And no, I don't want to downgrade my Texinfo just to do
that.)

I looked at the code in admin.el, and it seems to be trying to make
the produced HTML more pretty than what Texinfo produces.  While I'm
not objected to having prettier HTML manuals, this is not really our
job, and playing catch-up with the ever-changing HTML that comes from
Texinfo is a maintenance burden.  Moreover, the documentation of the
various "fixes" is minimal at best, and in many places nonexistent (in
the sense that there's no description of the original HTML, the
"improved" one, and the rationale for each "fix"); reverse-engineering
that from code which runs in batch mode is a non-trivial job,
especially since some "fixes" need old versions of Texinfo to be used
to even understand what they are doing.

So I don't think we should continue making these "fixes", unless
Someone™ steps forward and volunteers to keep maintaining this script,
keeping it up-to-date with the latest Texinfo developments, and
generally making sure the script is usable at all times.

I will wait for a day or two for someone to volunteer; failing that I
will remove most or all of the "fixes" from the script, so that it
works with the latest Texinfo, and so I could again refresh our
on-line documentation when needed.

TIA