Re: building the manual fails with Texinfo 6

[Rik]

On 07/08/2015 08:13 AM, address@hidden wrote:

Subject:

building the manual fails with Texinfo 6

From:

Mike Miller <address@hidden>

Date:

07/08/2015 07:07 AM

To:

Octave Maintainers <address@hidden>

List-Post:

<mailto:address@hidden>

Precedence:

list

MIME-Version:

1.0

Message-ID:

<address@hidden>

Content-Type:

text/plain; charset=utf-8

Message:

5

Maintainers,

It's been found in Debian that Octave fails to build its Texinfo manual
with the latest GNU Texinfo version 6 [1]. I have updated to Texinfo 6
and can confirm building the default branch fails.

This is *not* related to the recent non-recursive make changes that have
broken some minor things in the doc and test directories, this applies
to both 3.8.2 and 4.0.0.

With some investigation and patches provided by Norbert Preining [2],
the following two changes are needed at a minimum to get it building
again:

 * delete (or update to latest) doc/texinfo.tex distributed with Octave
 * fix some unescaped backslashes in @qcode{} macros

Always a good thing to fix unescaped backslashes.  Once we are certain that there are no installations with Texinfo < 5.0 we can also upgrade the @xbackslashchar macro to just @backslashchar.

Questions:

Why do we distribute our own texinfo.tex file? Was this to ensure that a
new enough version of the macros were present even if users had an
ancient automake or texinfo distribution once upon a time? A newer
up-to-date version of texinfo.tex is already injected into our build-aux
directory by gnulib and we could easily use that file instead to fix the
first problem.

I believe this was the reason.  In general, we didn't want to force users to have a full Texinfo installation.  Of course, we also distribute the full documentation in the tarball just so that they can run configure; make; make install without hassle.  So the only people really affected are developers starting from source or packagers for a Linux distro.  I suppose these people could be deemed savvy enough to install all the required dependencies.

Norbert also recommended deleting our distributed texmf.cnf, which only
exists to set save_size to 10000. The current texmf.cnf on my Debian
system sets save_size to 50000, does anyone remember which distros still
suffer from a default save_size that is too small to build the manual,
is this still relevant? RHEL 5 has save_size = 5000 for example, I
haven't tested whether this is too low.

The trouble is that then we would have to check against all possible distributions, whereas if we just set it to a known good value then it will be portable regardless of which weird OS (RHEL, Solaris, etc.) we come across.  But again, this is a concern only for people building directly from source code rather than a tarball.

I'll do some more testing and follow up when I have some concrete
changes for review or testing. I think this is worth fixing on the
stable branch so the 4.0.1 release will work with Texinfo 6.

[1]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=790626
[2]: https://bugs.debian.org/cgi-bin/bugreport.cgi?att=1;msg=82;bug=790626;filename=octave-build-fix.debdiff

-- 
mike