Type links

[coke]

The problem

Inconsistent formatting when referring to types in the docs that have their own primary page. (#2954)

Solution provided

xt/rakudoc-types.rakutest

[coke]

need to allow #tags on the links, probably.

[cfa]

This is also erroneously treating links like the following as bad,

L<C<Proc/Async|/type/Proc::Async>> should be L<C<Proc/Async>|/type/Proc/Async>

[coke]

We should standardize one way or the other, let's pick.

[cfa]

A few more false positive cases:

• Index entries
  • e.g. Failed test 'X<Scalar> should be L<C<Scalar>|/type/Scalar>'
    • This is from the heading =head2 X<Scalar|Tutorial,scalar (Basics)> in Language/101-basics.rakudoc.
  • Suggestion: exclude these from consideration altogether.
• Explicitly formatted terms
  • e.g.
    • 'I<method> should be L<C<method>|/type/method>',
    • 'I<block> should be L<C<block>|/type/block>'
  • Two subissues here:
    1. "method" (like "block", "map", "match", "raku" etc.) should probably be excluded from consideration as FPs are very likely. (More on this below.)
    2. I'm not sure that we should assume that explicitly formatted terms are missing additional formatting codes. It's probably reasonable to omit I<...>, B<...> etc. from consideration altogether (or to have the test check specific codes). This could cover the X<...> case too.
• Case insensitivity
  • e.g. 'L<exception|/type/Exception> should be L<C<exception>|/type/exception>'
  • Two issues here:
    1. /type/exception was derived from "exception" and located on disk (a byproduct of running this on a case insensitive filesystem?)… but the casing is incorrect (this should be /type/Exception, as it was originally).
    2. When word and type case don't match, perhaps skip? "exception" here—like "method" above—is likely to be a false positive. Nevertheless, requiring consistent case between word and type name might omit a few more FPs?

[coke]

• I only have case insensitive filesystems for easy access testing, agree we have to address that.
• Will definitely exclude X<>
• my thought about B<> and I<> was that they were likely intended to be type refs but were non standard, so wanted to call them out. if we want B<stuff>, we could have B<L<C>|..>>?

[cfa]

Sounds good.

(The false positives for B<> and I<> might be addressed by a combination of word exclusion and case sensitivity.)

[patrickbkr]

Ee

[coke]

Rebased accidentally against master and then (hopefully correctly) against main.

[coke]

Rebased accidentally against master and then (hopefully correctly) against main.

Just did the same thing again!

[coke]

Most of the issues from cfa's review are covered. One doc file is now passing in the branch - will merge back to main and start addressing the formatting everywhere.