`<subjectHead>`

The <subjectHead> element provides a heading for a group of subjects, for use if the subject scheme is rendered and displayed.

Usage information

The heading provided by the <subjectHead> element might be displayed when a subject scheme is rendered to let users select subjects as part of a faceted browsing experience.

The <subjectHead> element does not reference a resource. It also cannot specify either the @keys or @keyref attribute, so it does not define any controlled values.

Specialization hierarchy

The <subjectHead> element is specialized from <topicref>. It is defined in the subject scheme module.

Content model

<subjectHeadMeta> ?, ( <data> | <subjectdef> | <subjectHead> | <topicref> )*

In order

Optional <subjectHeadMeta>
Zero or more

Attributes

The following attributes are available on this element: universal attributes, @collection-type, @linking, @processing-role, and @toc,.

For this element, the following considerations apply:

The @collection-type attribute has an expected processing default value of unordered, although this value is not defaulted in the grammar files. This element limits the available values for @collection-type to unordered, sequence, and -dita-use-conref-target.
The @linking attribute has a default value of normal, and no other values are valid.

The following attributes are available on this element: universal attributes and the attributes defined below.

@collection-type (common map attributes)

Specifies how topics or links relate to each other. The processing default is unordered, although no default is specified in the OASIS-provided grammar files. The following values are valid:

unordered: Indicates that the order of the child topics is not significant.
sequence: Indicates that the order of the child topics is significant. Output processors will typically link between them in order.
choice: Indicates that one of the children should be selected.
family: Indicates a tight grouping in which each of the referenced topics not only relates to the current topic but also relate to each other.

The @collection-type attribute has an expected processing default value of unordered, although this value is not defaulted in the grammar files. This element limits the available values for @collection-type to unordered, sequence, and -dita-use-conref-target.

@linking (common map attributes)

Specifies linking characteristics of a topic specific to the location of this reference in a map. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

targetonly: A topic can only be linked to and cannot link to other topics.
sourceonly: A topic cannot be linked to but can link to other topics.
normal: A topic can be linked to and can link to other topics. Use this to override the linking value of a parent topic.
none: A topic cannot be linked to or link to other topics.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

The @linking attribute has a default value of normal, and no other values are valid.

@processing-role (common map attributes)

Specifies whether the referenced resource is processed normally or treated as a resource that is only included in order to resolve references, such as key or content references. The following values are valid:

normal: Indicates that the resource is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
resource-only: Indicates that the resource should be used only for processing purposes. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

If no value is specified but the attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.

@toc (common map attributes)

Specifies whether a topic appears in the table of contents (TOC) based on the current map context. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

yes: The topic appears in a generated TOC.
no: The topic does not appear in a generated TOC.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

Example

This section is non-normative.

In the following code sample, the <subjectHead> elements define two groupings of subjects and associate labels.

<subjectScheme toc="yes" search="no">
  <subjectdef keys="hobbies">
    <subjectdef keys="fiber-arts">
      <subjectHead>
        <subjectHeadMeta>
          <navtitle>Fiber arts</navtitle>
        </subjectHeadMeta>
        <subjectdef keys="knitting" href="knitting.dita"/>
        <subjectdef keys="quilting" href="quilting.dita"/>
        <subjectdef keys="sewing" href="sewing.dita/>
      </subjectHead>
    </subjectdef>
    <subjectdef keys="woodworking">
      <subjectHead>
        <subjectHeadMeta>
          <navtitle>Woodworking</navtitle>
        </subjectHeadMeta>
        <subjectdef keys="scroll-sawing" href="scroll-sawing.dita"/>
        <subjectdef keys="whittling" href="whittling.dita"/>
        <subjectdef keys="wood-turning" href="woodturning.dita"/>
      </subjectHead>
    </subjectdef>
  </subjectdef>
</subjectScheme>