Inconsistent capitalization for doc headers

[Kaiepi]

I've seen doc headers capitalized like this:

• Foo bar baz
• Foo Bar Baz

Which way of capitalizing them would be more appropriate?

[JJ]

The most consistent one. And I would say that would be the second, since we're capitalizing parts of generated headers.

[coke]

Can you provide some concrete examples here? In general, we shouldn't overcapitalize just because something is in a header; initial cap should be fine.

[Kaiepi]

The NativeCall documentation sometimes only capitalizes the first word and sometimes uses title case:

• Changing names
• Passing and Returning Values
• Basic use of Pointers

Ditto the Community page:

• The Perl 6 community
• Perl 6 Weekly

[JJ]

Yep, that's right. Not nice. We should try and design a test for that... We can admit All Caps in =head1, but that's it...

[Kaiepi]

Would using something like :ignore-case to skip testing a header for title case be reasonable? That could possibly allow all headers to be testable

[JJ]

@Kaiepi reasonable, yes; feasible, I don't know. Problem with new tests is that they're bound to fail a lot, so they would have to be introduced first as author tests, then insert that into the guidelines, then move them to t/ And I don't see a big consensus here with that.

[coke]

We’ve dealt with this with many new xt/ tests. Skip all the failing files; force any new changes to conform. Slowly remove skips as updates are made to the files. Ticket stays open until skips are gone.

[MorayJ]

Should this be closed, or is there more to be done?

[JJ]

I'm not sure all the hash links have been fixed, although @uzluisf has made a pretty good job out of it. Anyway, that's kind of tangential, so feel free to close it if you think it's OK. We can always open it back at a later date or simply reference it if we make some change.