Every few years, as elections for government offices come around, voters come out to the election centers and line up to cast ballots for their favorite candidates out of a pool of names. The tally of votes represents a form of ranking and selection for that pool of candidates. Links are like candidates; readers select them based on their properties, and each reader may have a quite different sense from yours of what is important. Whenever the choice is up to the reader of where to go next in their reading journey, then the democratic thing to do for two or more managed links is to put them into a pool–the linkpool.
The DITA Specification describes how this works:
The <linkpool> element defines a group of links that have common characteristics, such as type or audience or source. When links are in <related-links> or <linkpool> elements, the organization of links on final output is determined by the output process, not by the order that the links actually occur in the DITA topic.
Let’s come back to the election analogy. The slate of candidates was not just a single arbitrary list. Rather, the candidates for school boards, for city offices, and for state or provincial offices were each in separate pools on the ballot to help categorize the choices. Those pools represented additional, group-level criteria about the respective candidates.
Likewise, the linkpool element is a way to imbue additional properties or metadata on the links it contains, primarily through the role attribute and the various selection attributes of this grouping element. With appropriate property values and descriptive text, a pool of links can be processed to generate useful finder widgets or to improve the chances of discovery and high ranking by search engines.
Whether you have just voted for a favorite candidate, ordered a meal at a restaurant, or picked a link out of a categorized pool of candidates, if you were able to make an informed choice, then truly “You’ve made an excellent choice!”
Did you know?
Although the so-called selection attributes are universal for most elements in a basic DITA topic type, some specializations might constrain the available values to better represent the desired model. In the step element of a DITA Task, for example, the importance attribute’s normal list of options have been limited to just “optional” or “required” reflecting the two values that apply specifically to a procedural step.
Deep Dive
- DITA 1.2 Specification: The linkpool element
- In Episode 32 of the popular comedy show “I Love Lucy,” Lucy and Ricky managed to be invited to compete in a TV quiz show. Lucy managed to obtain and memorize the answers to the planned questions, but the questions were changed at the last minute. Lucy of course gave her pat responses to the wrong questions, one of which was: “What is a senator’s term of office?” “The sap runs every two years.”
Choice words on more than one level!
“…the importance attribute’s normal list of options have been limited to just “optional” or “important” reflecting the two values…”
Clarification: for step element, isn’t the second acceptable value @importance=”required” not @importance=”important”?
Thanks for the close reading, Lief. I’ve updated; if you only knew how many times I’ve mentally carried the attribute name into the value!
Thanks for explaining that one, Don. I understand that much better than I had originally. Thanks for the great example.