Minor refinements to the semantic correctness for the static HTML

[d-ronnqvist]

Bug/issue #, if applicable:

Summary

This makes a few semantic correctness changes for the static HTML output. Specifically;

• It uses an <aside> element instead of a <blockquote> element for DocC asides because according to the HTML spec the semantics of a block quote "[...] must be quoted from another source".

  The semantics of an <aside> element are more suitable for DocC asides:

  a section of a page that consists of content that is tangentially related to the content around the aside element, and which could be considered separate from that content. Such sections are often represented as sidebars in printed typography.

  The element can be used for typographical effects like pull quotes or sidebars, for advertising, for groups of nav elements, and for other content that is considered separate from the main content of the page.

• It uses an <hgroup> element to group the "eyebrow" subheading with the page title.

  A hgroup element "may be used to group an h1-h6 element with one or more p elements containing content representing a subheading, alternative title, or tagline." which seemed appropriate for the "eyebrow" subheading and the page title.

  Note that the subheading is allowed to appear either before or after the heading in the group.

• It removes the semantically incorrect "text" role from the availability list items. According to the W3C validator, a li element "must not have any role value other than listitem."

• It wraps the main content in a <main> element to semantically "[...] represent the dominant contents of the document."

It also removes a no-longer-needed "id" attribute for the page' abstract and improves the "aria-label" for availability list items.

Dependencies

None

Testing

• Build documentation for any project—with some page that specifies some amount of availability and some page that has an aside in its content—and pass the --output-format experimental-html-for-development option to DocC.

• In the output; open the HTML file for the page with availability in a text editor.

  • The availability <li> items should not specify role="text" as an attribute.

  • The page's eyebrow subheading and title should be group inside a <hgroup> element.

  • The page's content should (an <article> element) should be wrapped inside a <main> element.

  • Open the same HTML file in a browser.

    • The availability should render the same as before.
    • The page's eyebrow subheading and title should render the same as before.
    • The page's abstract (if it has one) should render the same as before.

• In the output; open the HTML file for the page with the aside.

  • The aside should be represented using an <aside> element with a class attribute that specifies what type of aside (for example class="note")

  • The page's eyebrow subheading and title should be group inside a <hgroup> element.

  • The page's content should (an <article> element) should be wrapped inside a <main> element.

  • Open the same HTML file in a browser.

    • The aside should render the same as before.
    • The page's eyebrow subheading and title should render the same as before.
    • The page's abstract (if it has one) should render the same as before.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Update Added tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test