The "=head keyword convention" was misunderstood a bit, needs cleanup and a test

[Altai-man]

Problem or new feature

Data points:

• Each =head leads to creation of an anchor to use in TOC (and possibly search entry if has X or uses keyword convention*)

• =head keyword convention
  • When we have a header formed accordingly to the Grammar in Documentable (see https://github.com/Raku/Documentable/blob/master/lib/Documentable/Heading/Grammar.pm6), e.g. =headX infix foo or =headX method bar or =headX The bar infix the search anchor is created automatically with the category derived based on what keyword was parsed

As the rule is obscure and we had no tests to help authors, it led to creation a number of cases where this implicit anchor creation and explicit one is mixed:

➜  doc git:(master) rg '=head(.?) X<'
Type/Variable.pod6
18:=head2 X<trait is default|Traits,is default (Variable)>

Type/Signature.pod6
608:=head3 X<Coercion type|Language,Coercion type>
773:=head3 X<Unflattened slurpy|Syntax,**@>
1042:=head2 X<Long names|Language,Long names>
1051:=head2 X<Capture parameters|Syntax,|>

Programs/02-reading-docs.pod6
7:=head1 X<INTRODUCTION|Programs,rakudoc>

Type/Attribute.pod6
18:=head2 X<Trait is default|Traits,is default (Attribute)>
39:=head2 X<Trait is required|Traits,is required (Attribute)>
83:=head2 X<trait is DEPRECATED|Traits,is DEPRECATED (Attribute)>
104:=head2 X<trait is rw|Traits,is rw (Attribute)>
124:=head2 X<trait is built|Traits,is built (Attribute)>
...
1023:=head2 X<sub callsame|Subroutines,callsame>
1045:=head2 X<sub callwith|Subroutines,callwith>
1112:=head2 X<sub nextsame|Subroutines,nextsame>
1133:=head2 X<sub nextwith|Subroutines,nextwith>
1154:=head2 X<sub samewith|Subroutines,samewith>
1170:=head2 X<sub nextcallee|Subroutines,nextcallee>

Suggestions

Two steps are necessary to resolve this:

• Note e.g. =head2 X<sub samewith|Subroutines,samewith> which is a double indexing. For such cases, simple removing of the X<> code would suffice.
• However, where the anchor text is custom (say X<trait is rw|Traits,is rw (Attribute)>) the usage is correct. So one should write a test detecting double indexing, but smart enough to detect "custom" ones.

Speaking of which, the traits indexing also has no known convention about how to mark traits with the same name but different object, but developing it is an entirely different ticket.

[finanalyst]

This is mainly a problem with Pod::To::HTML, not with POD6 (Rakudoc). Also, inside Pod::To::HTML, titles are rendered into HTML using quite a complex set of HTML codes. The title contains a link to the top of the file.

[Altai-man]

This is mainly a problem with Pod::To::HTML, not with POD6 (Rakudoc).

I wouldn't call it a "problem", but yes, the consumer is Pod::To::HTML in this case.

And not a problem in the Rakudoc spec itself, but with the sources we have.

Personally, I found this "head keyword" (no idea how to call it, so calling it that) convention a neat shortcut, so would vote in flavor it being recognized - surfacing "implicit" conventions of the toolchain we have/had allows to 1)take and make explicit what is neat; 2)get rid/simplify what is less neat.