When Swift-DocC generates text, such as default topic group names for curation and header and link titles in tutorial assessments, it uses title case (also known as headline case) and capitalizes all non-minor words. For example, the familiar Default Implementations topic group and its child API collections.
A new @AutomaticTextCasing option directive for indicating which casing style Swift-DocC should apply to a page’s, or tutorial's, auto-generated text. For example, default topic group names and API collections.
@AutomaticTextCasing accepts an unnamed parameter containing one of the following:
title: Swift-DocC uses title casing. This is the default behavior (and matches what Swift-DocC currently does) and is the same as omitting this option entirely.
sentence: Swift-DocC uses sentence-style casing, where only the first letter of the first word is capitalized, along with any proper nouns.
Examples
@GlobalOptions {
@AutomaticTextCasing(sentence)
}
For the example in the opening paragraph, this would render Default implementations rather than Default Implementations.
This new option directive would apply to all auto-generated text, in all content that Swift-DocC renders (documentation pages, tutorials etc.); manually authored content is unaffected.
This seems like a useful tool to have if you're writing docs in a context where the style guidance is to use sentence case.
As a potential alternative to consider, could DocC vend some sort of strings file for all of the automatic text it generates? That way you could override both the text and capitalization as your project's needs might require. For example, I might want the automatic name to be "Default implementations from the \(protocolName) protocol" or similar.
I'm assuming that this is intended to apply to all generated headings but it'd be good for this pitch to specify that explicitly (or not).
Other auto-generated headings that I can think of are the "See Also" sections and the headings for the automatic curation based on symbol kinds (for example: "Classes" and "Protocols" but also "Enumeration Cases", "Instance Variables", "Instance Methods", "Type Aliases", and more).
It would also be good to clarify how this configuration impacts tutorials. I can think of a few pieces of auto-generated text in tutorials but they're not headings. For example:
"Estimated Time" in a tutorial's intro section and in the table of content page.
"Check Your Understanding" and "Next Question" in a tutorial's assessment.
"Sample Code" in a table of content's resources section.
Depending on the scope of content that this directive is meant to control the name of the directive and its potentials arguments may need to change.
@krilnon That's a great suggestion, but it's also something that would firmly step foot into localization territory, which is beyond the scope of this change; adding localization support to Swift-DocC requires a much wider discussion.
How do you envision allowing writers to override sentence casing for proper nouns and/or product names? For example, could a writer have a hypothetical excludes-casing.json file that lists words that should be excluded from casing rules, like Metal and ARKit, or iPhone and iPad?
However, that's a bit beyond the scope of this proposal. Effectively, all I'm proposing we change here is the static text that's injected by Swift-DocC at doc build time. For example, "Default Implementations" is used by the automatic curation process. This text is hard-coded in the source, so the alternatives would be added alongside them in the corresponding pull-request. Only the casing-style option is evaluated at doc build time, not the text itself.
