<relcolspec>
A column specification in a relationship table column that provides default attribute values for the references in that column of a relationship table.
Usage information
You can use the <relcolspec>
element to set default values for the
attributes of the topics that are referenced in the column. For example, when you set the
@type
attribute to concept, all <topicref>
elements
in the column that do not have a @type
attribute specified are treated as
concepts.
Adding a <topicref>
element to the
<relcolspec>
element defines a
relationship between the topics that are
contained within the <relcolspec>
element
and the topics that are referenced in the column of the
relationship table. Note that this does not
define a relationship between two cells in the same
column.
Rendering expectations
<title>
element exists inside of the
<relcolspec>
element, the content of the
<title>
element is intended to be used as the label for the related
links that are defined and generated by the column. If the <title>
element is not present, the labels for the related links are generated in the following
ways:- If the
<relcolspec>
element contains a<topicref>
element that specifies a navigation title, that navigation title is used for the label. - If the
<relcolspec>
element contains a<topicref>
element that does not specify a navigation title but does reference a DITA topic, the label is derived from the navigation title of the referenced topic or, lacking that, the title of the topic. - If no title is specified and no
<topicref>
is present in the<relcolspec>
, a rendering tool might choose to generate a title for the links generated from that column.
Processing expectations
When values are specified for attributes of
<relcell>
or
<relrow>
elements, those values override
those defined for <relcolspec>
attributes.
Values specified for attributes of
<relcolspec>
elements override those
defined for the <reltable>
element.
Content model
<title>
?,
<topicmeta>
?, (
<topicref>
|
<ditavalref>
|
<keydef>
|
<mapref>
|
<mapresources>
|
<topicgroup>
|
<topichead>
)*
- Optional
<title>
- Optional
<topicmeta>
- Zero or more
Attributes
The following attributes are available on this element: universal
attributes and common map attributes (without
@keyscope
or @collection-type
),
@type
, @scope
, and
@format
.
The following attributes are available on this element: universal attributes and the attributes defined below.
@cascade
(common map attributes)-
Specifies how metadata attributes cascade within a map. The specification defines the following values:
- merge
- Indicates
that the metadata attributes cascade, and that the
values of the metadata attributes are additive. This is the
processing default for the
@cascade
attribute. - nomerge
- Indicates
that the metadata attributes cascade, but that they are
not additive for
<topicref>
elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered. That is, settingcascade="nomerge"
does not undo merging that took place on ancestor elements.
Processors can also define custom, implementation-specific tokens for this attribute.
See Cascading of metadata attributes in a DITA map for more information about how this attribute interacts with metadata attributes.
@chunk
(common map attributes)- Specifies how a processor should render a map or branch of a
map. For example, it can be used to
specify that individual topic documents should be rendered as
a single document, or that a single document with multiple
topics should be rendered as multiple documents.The following values are valid:
- combine
- Instructs a processor to combine the referenced source documents for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document.
- split
- Instructs a processor to split each topic from the referenced source document into its own document for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document, regardless of how many DITA topics exist within each source document.
Processors can also define custom, implementation-specific tokens for this attribute.
For a detailed description of the
@chunk
attribute and its usage, see Chunking. @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.
@format
(link-relationship attributes)- Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
@keyscope
(common map attributes)- Specifies that the element marks the boundaries of a key
scope.
See The keyscope attribute for information on using this attribute.
@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.
@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.
@scope
(link-relationship attributes)- Specifies the closeness of the relationship between the
current document and the referenced resource. The following values are valid:
local, peer,
external, and
-dita-use-conref-target.
See The scope attribute for detailed information on supported values and processing implications.
@search
(common map attributes)- Specifies whether the target is available for searching. 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, no, and -dita-use-conref-target.
@subjectrefs
(common map attributes)- Specifies one or more keys that are each defined by a subject definition in a subject scheme map. Multiple values are separated by white space.
@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.
@type
(link-relationship attributes)- Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.
Examples
This section is non-normative.
The following section contains examples of how the
<relcolspec>
element can be used.
<relcolspec>
The following code sample shows how a
<relcolspec>
element can be used to
define the types of topics that are referenced in a column. Three
cells are defined within one row. The first cell contains one
concept topic: puffins.dita. The second cell
contains two task topics: puffinFeeding.dita
and puffinCleaning.dita. The third cell
contains a reference topic:
puffinHistory.dita. Setting the
@type
on each column allows (but does not
require) processors to validate that the topics in each column
are of the expected type.
<map>
<reltable>
<relheader>
<relcolspec type="concept"/>
<relcolspec type="task"/>
<relcolspec type="reference"/>
</relheader>
<relrow>
<relcell><topicref href="puffins.dita"/></relcell>
<relcell>
<topicref href="puffinFeeding.dita"/>
<topicref href="puffinCleaning.dita"/>
</relcell>
<relcell>
<topicref href="puffinHistory.dita"/>
</relcell>
</relrow>
</reltable>
</map>
The following code sample shows how topics and titles can be specified in a column header for relationship table column header:
<reltable>
<relheader>
<relcolspec type="task">
<topicref href="tbs.dita">
<topicmeta><navtitle>Troubleshooting</navtitle></topicmeta>
</topicref>
</relcolspec>
<relcolspec type="reference">
<topicref href="msg.dita">
<topicmeta><navtitle>Messages</navtitle></topicmeta>
</topicref>
</relcolspec>
</relheader>
<relrow>
<relcell>
<topicref href="debug_login.dita"/>
<topicmeta><linktitle>Debugging login errors</linktitle></topicmeta>
</topicref>
</relcell>
<relcell>
<topicref href="login_error_1.dita">
<topicmeta><linktitle>Login not found</linktitle></topicmeta>
</topicref>
</relcell>
</relrow>
<relrow>
<relcell>
<topicref href="checking_access.dita">
<topicmeta><linktitle>Checking access controls</linktitle></topicmeta>
</topicref>
</relcell>
<relcell>
<topicref href="login_error_2.dita">
<topicmeta><linktitle>Login not allowed</linktitle></topicmeta>
</topicref>
</relcell>
</relrow>
</reltable>
- tbs.dita <–> debug_login.dita
- tbs.dita <–> checking_access.dita
- msg.dita <–> login_error_1.dita
- msg.dita <–> login_error_2.dita
Ignoring the headers for a moment, the
<reltable>
here would ordinarily define
a two-way relationship between
debug_login.dita and
login_error1.dita. This typically will be
expressed as a link from each to the other. An application might
render the link with a language-appropriate heading such as
"Related reference", indicating that the target of the link is a
reference topic.
The headers change this by specifying a new title. In the second column, the
<topicref>
specifies a title of "Messages", which should now be
used together with the link to anything in that column. So, a generated link from
debug_login.dita to login_error1.dita should
be rendered together with the title of "Messages". How this is rendered together with the
link is up to the application.