Syntax #
p.title.concept(level)
p.title.glossary-group(level)
p.title.reference(level)
p.title.task(level)
p.title.task-general(level)
p.title.topic(level)
p.title.troubleshooting(level)
p.title.unknown-topic(level)
p.title.custom-topic(elementname(level))
p.no-title.custom-topic(elementname(level))
level
the nesting depth of the topic, any integer
elementname
the name of the custom topic type
Purpose #
Migrate will construct a DITA map which pulls together all created topics in the order in which they appear in your document. Topics may be nested, giving rise to a hierarchical DITA map. The annotation’s argument indicates the how deeply nested a topic should be in the map.
These annotations are used to identify topic boundaries and topic types. They should be placed on content elements of type paragraph which are titles in your document. Migrate will start a new DITA topic at these points, and will use the text of the annotated content element as the topic title. Larger nesting level topics will be created inside those of smaller nesting levels.
Typically, sequential depths such as 1, 2, and 3 are used with the title annotations that take arguments. However, Migrate really only looks at the relative numbering. So you could choose depths such as -14, -12, -10. These might simply be the negated font sizes of the heading styles in your document. Because -12 is larger than -14, Migrate will nest topics at depth -12 inside of those at depth -14.
The annotation p.title.unknown-topic is used to indicate the start of a new topic, but does not indicate the topic type. The annotation can be used in cases where the topic type is not easily determined based solely on the title itself. Migrate will use the existing DITA schema as well as the topic’s content to determine the best topic type for that topic. If the topic contains a numbered list that is marked up as steps, for example, that will give Migrate a strong indication that the topic is a task. If the topic contains a lot of tabular information, Migrate may decide that the topic is a reference topic.
The annotation p.title.custom-topic is used to set a title on a topic that is a specialized topic type to your document.
The annotation p.no-title.custom-topic is used to start a new topic of a type that is a specialized to your document without creating a title for that topic.
Example: Determining nesting level from font size.
p.title.topic(-\1)
when all of the following are true
style matches Heading[1-9]
and property font-size matches ([1-9][0-9]?)
