Bug: Hyperlinks in generated documentation may point to the wrong architecture

[Maximilian Engelhardt <maxi@daemonizer.de>]

[-- Attachment #1: Type: text/plain, Size: 3342 bytes --]

Hello,

during working on packaging Xen in Debian I noticed the documentation becomes 
non-reproducible as hyperlinks may point to the wrong architecture.

Here an example as diff showing the problem:

/usr/share/doc/xen/html/hypercall/arm/include,public,arch-arm.h.html
@@ -313,15 +313,15 @@
     uint64_t sctlr;
     uint64_t ttbcr, ttbr0, ttbr1;
 };
 typedef <a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">struct vcpu_guest_context</a> <a  name="Typedef_vcpu_guest_context_t"><strong>vcpu_guest_context_t</strong></a>;
 DEFINE_XEN_GUEST_HANDLE(<a href="include,public,arch-arm.h.html#Struct_vcpu_guest_context">vcpu_guest_context_t</a>);
 
 /*
- * <a href="include,public,arch-arm.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
+ * <a href="include,public,arch-ppc.h.html#Struct_xen_arch_domainconfig">struct xen_arch_domainconfig</a>'s ABI is covered by
  * XEN_DOMCTL_INTERFACE_VERSION.
  */
 #define XEN_DOMCTL_CONFIG_GIC_NATIVE    0
 #define XEN_DOMCTL_CONFIG_GIC_V2        1
 #define XEN_DOMCTL_CONFIG_GIC_V3        2
 
 #define XEN_DOMCTL_CONFIG_TEE_NONE      0


As can be seen, the hyperlink in include,public,arch-arm.h.html points to 
include,public,arch-ppc.h.html while it should point to include,public,arch-
arm.h.html.
A similar problem can be found in many more places and files.

Corresponding to the problem described above, while building the documentation 
many messages similar to the last lines below can be seen in the build log:

/usr/bin/perl -w /build/reproducible-path/xen-4.19.1/docs/xen-headers -O html/hypercall/arm \
        -T 'arch-arm - Xen public headers' \
        -X arch-x86_32 -X arch-x86_64 \
        -X xen-x86_32 -X xen-x86_64 \
        -X arch-x86 \
        /build/reproducible-path/xen-4.19.1/docs/../xen include/public include/xen/errno.h
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-arm.h:300
include/public/arch-ppc.h:91: multiple definitions of Typedef vcpu_guest_core_regs_t: include/public/arch-ppc.h:85
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-ppc.h:90
include/public/arch-ppc.h:95: multiple definitions of Struct vcpu_guest_context: include/public/arch-arm.h:305
[...]


In Debian we worked around the problem for now by adding ppc and riscv to 
DOC_ARCHES in docs/Makefile as can be seen in [1]. This solves all the 
described problems and makes the build reproducible again. I assume another 
possible fix would be adding suitable ignore switches for ppc and riscv.

I did not send this as a patch as I'm not sure what the preferred upstream 
solution to this problem is, but can formally submit our fix as a patch if 
that's desired.

Thanks,
Maxi

[1] https://salsa.debian.org/xen-team/debian-xen/-/commit/d852c48d0df5c6ceba42d20652d1f9a05ad8989e 

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 833 bytes --]