Styling of types

[uzluisf]

The problem

While proofreading some documentation pages (e.g., types), I've noticed that when a particular type is mentioned, the type is either linked to (e.g., L<Hash/type/Hash>), formatted as code (e.g., C<Hash>) or just plain text (e.g., Hash). In some instances, the same type is linked to multiple times over the length of the page. Other times, it's never linked to but just formatted as code. In other, it's just plain text w/o any formatting that blends with the surrounding text.

Suggestions

Most type pages have two top-level sections: the introduction to the type (e.g., class Hash) which follows the class's title and subtitle and the Methods (and Type Graph) sections. In the following paragraphs, I'll focus only on the introduction section which itself might have sections. The case for routines documentation under the Methods section seems to be already covered here. Thus depending on how these pages are meant to be read, we could've some sort of convention when styling the types in the introduction:

• Top-to-bottom. If each type page is meant to be read from top-to-bottom, then:

  • The first time a type is mentioned, we should link to it (L<>). Subsequent mentions (regardless if it's in the same section, same section's subsection, new section, etc.) should be formatted as C<> accordingly.
  • References to types and other constructs in a specific code example should be formatted with C<>. However, some exceptions may apply.

• Granular. If each type page is meant to be read granular-ly, then:

  • In a single h1-level section, the first time a type is mentioned we should link to it (L<>) and subsequent mentions of it within the same section (and its subsections) should be formatted as C<>. New mentions of the same type in other h1-level sections follow the same procedure.
  • References to types and other constructs in a specific code example still should be formatted with C<>. However, some exceptions may apply.

[JJ]

I see merit in your argument. The problem is to actually enforce it. Either we get expert proofreaders, or we have somehow to develop an xt test to check that. If that's the case, I'd happily adopt that policy (if everyone else is happy with it)

[coke]

Adding onto the new [xt/rakudoc-c.rakutest] in origin/type-links.

Lots of e.g.C<Hash> - the WIP test is recommending these appear as L<C<Hash|/type/Hash>>.

[coke]

Given how secondary doc pages are generated, we should use the same formatting on each element on the page, not just the first - we can't guarantee ordering is the same on primary sources vs. generated pages.

[coke]

Moved test to its own file on that branch: xt/rakudoc-types.rakutest

Should get all cases where a string that is also in /Type/$string.rakudoc is not formatted correctly - doesn't touch those strings that appear in plain text.

Currently 4598 failures for the new test file on the type-links branch.