set an exit code in `make_doc`

[ThomasBreuer]

With this change, the CI tests detect whether errors like broken references occur when the manuals get built.

For that,

• redirect the Info output generated by GAPDoc functions to a string,
• extract the messages that describe warnings; according to https://github.com/frankluebeck/GAPDoc/commit/826c091491438c1f6ba1f330d17914f45b4bd3af, these are the lines starting with "#W ",
• omit the LaTeX warnings about overfull boxes (I think we do not want to force ourselves to create manuals without these warning),
• report failure if the set of remaining warnings is nonempty.

[fingolfin]

So it reports a failure now. So what is wrong?

[fingolfin]

It shows a lot of warnings about unresolved references. But those all come from run 1, were they are to be expected (we need to build the manual twice precisely to deal with those).

Perhaps run 1 ought to be excluded from this?

[ThomasBreuer]

This is more subtle than I had thought. Note that doc/make_doc is not self-contained. It assumes that the documentation for all those packages has been build for which there are cross-references from the main GAP manuals (for example the Forms package).

[ThomasBreuer]

After some experiments, I think that this pull request can be merged, as it improves the behaviour for the main GAP manuals.

Concerning more general support for package manuals, i.e., how to detect problems when building a package's documentation (in CI tests), the situation is not obvious:

There is the release-gap-package script which could be extended, see gap-system/ReleaseTools/issues/106.

Besides that, changing return values or printed output of MakeGAPDocDoc or AutoDoc would perhaps yield an improvement for an individual GAP package (assuming that the makedoc.g file of the package is read by a CI test), but would also confuse release-gap-package. Setting an exit code for the current GAP session if AutoDoc detects failure seems to be useful, and will not cause unwanted changes in the behaviour of scripts involving AutoDoc calls, see gap-packages/AutoDoc/pull/280.