Make fails at the doc transformation stage

[Etua]

Running make for this program at both Fedora 39 and Ubuntu 20.04 fails with the following message: xsltproc -o doc/gpscorrelate.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl doc/gpscorrelate-manpage.xml error : Unknown IO error warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl" cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl Said IO error is so unknown, that I wasn't able to determine its cause even with xsltproc --debug, which doesn't provide any additional info.

[Etua]

For the record, that's the simple make. Issuing make -j2 CFLAGS="-g -O0 -DENABLE_NLS=1" gpscorrelate gpscorrelate-gui && make check borrowed from the CI works, further confirming that the problem lies in the doc/gpscorrelate.1 and doc/gpscorrelate.html targets.

[dfandrich]

You need to install the Docbook DTD, which on Fedora should be in the docbook-dtds package, or try adding --nonet to the xsltproc command-line, which can be done through the makefile with the XSLTFLAGS variable.

[Etua]

Thank you. I've tried both solutions, but to no avail. Have you tried running make from scratch on your end recently? Maybe that's some error with the upstream.

Just not to waste your time, in case I made an obvious mistake: the modified command should look like that, correct? xsltproc --nonet -o doc/gpscorrelate.1 https://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl doc/gpscorrelate-manpage.xml

[dfandrich]

You have an extra character in that command-line. It should be http: not https:

[Etua]

I changed that during debugging, because I observed that http redirects now to https either way. Just to be on the safe side, I executed git reset --hard (and put back the --nonet), so now it should be identical to the repo with the exception of this flag. Unfortunately, it still doesn't work. xsltproc --nonet -o doc/gpscorrelate.1 http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl doc/gpscorrelate-manpage.xml I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl" cannot parse http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl Thank you for your continued attention. I just wanted to prepare a patch for this software, and fixing this part is not crucial to that cause, but I just wanted to pinpoint the source of the error, instead of just ignoring it with building only a specific target.

[dfandrich]

A URL in this XML context is an external identifier, and is not intended to be downloaded. It's merely an index into the XML definition that's being used. By changing the URL you are changing the identifier, marking the file as no longer a Docbook file but some other, unidentifiable type. Using a URL for these identifiers is merely a convenient way to choose a globally-unique yet meaningful one. It happens that some of these identifiers are also valid, downloadable URLs, but that's not their intended use.

The error you're seeing likely means that the file doc/gpscorrelate-manpage.xml doesn't exist. Try make doc/gpscorrelate-manpage.xml first.

[dfandrich]

Whoops, I got confused. The external identifier for Docbook version used by gpscorrelate is http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd but that's not the URL passed in to xsltproc. That is the identifier for the XSL needed to convert Docbook into a man page, but it is, for the same reason, also a URL, and it's used by xsltproc to find the right local XSL file. That XSL file is usually in a package called docbook-xsl or docbook-style-xsl.

[Etua]

You are completely right! Before filing this request, I read the INSTALL file, including this part:

• xsltproc (only for building the man page): http://xmlsoft.org/XSLT/ with manpages/docbook.xsl properly installed from https://docbook.sourceforge.net/ or an OS package (often named something like docbook-xsl or docbook-style-xsl)

I confirmed that xsltproc responds, so I have not installed any of the listed packages. It wouldn't occur to me that this default installation is not "proper", but indeed only installing docbook-style-xsl fixed the error. I have not dealt with this toolchain before, so you'd better know: was it obvious enough that such problem could occur, or is this caveat something worth mentioning in the install instructions? Once again, thank you for your time.

[Etua]

Oh wait, what I quoted wasn't the wording I originally saw. Still, the same comment applies, as someone could reasonably think that if some program with the help menu presents itself after calling xsltproc, then this tool is, indeed, already installed.

[dfandrich]

I just added that part about docbook-style-xsl yesterday, after we had this conversation. I'm glad it was an easy fix in the end!