Duplicate labels in the manual

[stertooy]

CI tests for the manual currently fail due to multiply-defined labels. It seems there are a total of 329 duplicates.

The reason behind this, is that any GAPDoc declaration of a function/operation/method/attribute/... without a label, will be given an automatically generated label that equals its Name field. But if there are multiple declarations with the same name, each of them without a label assigned manually, then they all get the same auto-generated label, see e.g. below.

hap/doc/newRings.xml

Line 8 in a5e37b0

<ManSection> <Func Name="ModPCohomologyRing" Arg="G,n"/> <Func Name="ModPCohomologyRing" Arg="G,n,level"/> <Func Name="ModPCohomologyRing" Arg="R"/> <Func Name="ModPCohomologyRing" Arg="R,level"/> <Description> <P/> Inputs either a <M>p</M>-group <M>G</M> and positive integer <M>n</M>, or else <M>n</M> terms of a minimal <M>Z_pG</M>-resolution <M>R</M> of <M>Z_p</M>. It returns the cohomology ring <M>A=H^*(G,Z_p)</M> modulo all elements in degree greater than <M>n</M>. <P/> The ring is returned as a structure constant algebra <M>A</M>. <P/> The ring <M>A</M> is graded. It has a component <M>A!.degree(x)</M> which is a function returning the degree of each (homogeneous) element <M>x</M> in <M>GeneratorsOfAlgebra(A)</M>. <P/> An optional input variable "level" can be set to one of the strings "medium" or "high". These settings determine parameters in the algorithm. The default setting is "medium". <P/> When "level" is set to "high" the ring <M>A</M> is returned with a component <M>A!.niceBasis</M>. This component is a pair <M>[Coeff,Bas]</M>. Here <M>Bas</M> is a list of integer lists; a "nice" basis for the vector space <M>A</M> can be constructed using the command <M>List(Bas,x->Product(List(x,i->Basis(A)[i]))</M>. The coefficients of the canonical basis element <M>Basis(A)[i]</M> are stored as <M>Coeff[i]</M>. <P/> If the ring <M>A</M> is computed using the setting "level"="medium" then the component <M>A!.niceBasis</M> can be added to <M>A</M> using the command <M> A:=ModPCohomologyRing_part_2(A) </M>. <P/><B>Examples:</B> <URL><Link>../tutorial/chap8.html</Link><LinkText>1</LinkText></URL>&nbsp;, <URL><Link>../www/SideLinks/About/aboutModPRings.html</Link><LinkText>2</LinkText></URL>&nbsp;

Which causes

2025-10-18T11:34:36.4288263Z LaTeX Warning: Label `ModPCohomologyRing' multiply defined.
2025-10-18T11:34:36.4288614Z LaTeX Warning: Label `ModPCohomologyRing' multiply defined.
2025-10-18T11:34:36.4288953Z LaTeX Warning: Label `ModPCohomologyRing' multiply defined.

[grahamknockillaree]

Thanks! One solution could be

<Func Name="ModPCohomologyRing" Arg="G,n" Label="ModPCohomologyRing(G,n)" /> <Func Name="ModPCohomologyRing" Arg="G,n,level" Label="ModPCohomologyRing(G,n,level)"/> <Func Name="ModPCohomologyRing" Arg="R" Label="ModPCohomologyRing(R)"/> <Func Name="ModPCohomologyRing" Arg="R,level" Label="ModPCohomologyRing(R,level)"/>

On the other hand, that solution makes the index look very clumsy.

The multiply defined labels are intentional (one could discuss whether that is a good intention) and the warning messages produced by GAPDoc confirm the intentional multiply defined labels. So is this necessarily a bug?

[james-d-mitchell]

I'd usually make the label describe the arguments, e.g. "for a group and an integer" or something like that. This way if you want to write a reference to that version it's more or less straightforward to figure out what the label is.

[grahamknockillaree]

If multiply defined labels for ModPCohomologyRing are used then the index generates a nice single line reference for the function.

If a different label is used for each instance of the function then the index includes one line for each instance, which looks a touch clumsy.

My question is: Do the current multiply defined labels cause some GAP test to fail? If so then this is definitely a bug in HAP which needs to be fixed.

[james-d-mitchell]

The issue is that the duplicate labels cause latex errors when compiling the pdf version of the manual, which causes one of the CI jobs to fail. That could be remedied in another way (not failing when there are duplicate labels).

Personally, when I see the one line version you've copied above @grahamknockillaree it looks like an error in the docs, since each number is repeated 4 times. I guess "niceness" is in the eye of the beholder.

If you're happy with the way the doc is just now, it should be possible to fix the ci without fixing the duplicate labels.

[grahamknockillaree]

The HAP manual is not in the best shape, having evolved out of an html document into the current GAPDoc version. I could work towards the following style that avoids duplicate labels

if people find that better, or I could leave things unchanged.

I'm happy either way. Just let me know.

[stertooy]

Ideally, we would be able to suppress the automatic generation of labels to avoid unwanted "duplicates". But I don't think GAPDoc has such functionality, and we can only override an auto-generated label with another label. This can indeed cause the index to become quite cluttered...

If you prefer the way the manual is currently, we can instead change the CI job for the manual to no longer treat warnings as errors. That would cause the CI job to pass, but other problematic warnings could po tentially go unnoticed (e.g. unresolved references, missing bibliography entries, ...). But none of those errors happen right now, and the multiply defined labels aren't causing any other errors such as unresovable references either, so I think that's probably fine?

It might not be a bad idea to let package authors specify in the Docs CI task exactly which errors they wish to ignore. I'll open an issue on the build-pkg-docs action about that.