Setting Up Wrapping Rules

Wrapping rules are used to wrap one or more elements in new elements to create hierarchies in the structured file.

For all but the simplest of conversions, and definitely for DITA, after creating the initial base elements with the mapping rules, you’ll need to define rules that wrap those elements in other elements to create nested structures. These rules can be created in the same table as the mapping rules, or you can create additional tables in the same file to contain the wrapping rules.

The format for a wrapping rule is similar to that of a mapping rule in that the first column defines the element(s) that are acted on, or wrapped, the second column defines the element that is the container or wrapper, and the third column defines the optional qualifier. The first column may be very lengthy in its description of exactly what sequence of elements to match on and wrap. The second column is always just the wrapper element name and possibly attribute(s) that are assigned to that element.

The syntax of the first column is similar to that of an EDD (or DTD) general rule syntax. It describes a sequence of one or more elements, which if met, will cause those elements to be wrapped. To identify an element you use the “E:” prefix, which is followed by the element name and/or a qualifier label. You can specify a sequence of elements by separating them with a comma, and if you want to specify optional groups of elements use parenthesis to define the group and the vertical bar character to separate the elements within the group. Special frequency operators follow an element or group to indicate the number of times that item can exist. The options are “*” (zero or more), “+” (one or more), and “?” (zero or one). If no frequency operator is provided, that means the element must exist once.

The following simple example performs these wrapping rules:

E:li+ ul  
(E:p | E:ul)+ body  
E:title, E:shortdesc?, E:body topic  
E:topic+ dita  

While these rules will “work”, it’s not a very realistic wrapping table for a number of reasons. First, it assumes that all topics are defined by the same heading level; there’s no topic hierarchy created by these rules. Also, it assumes that the content in the topics only consist of paragraphs and bulleted lists (and these bulleted lists only have one paragraph per list item).

A possibly more realistic example would be one that makes used of qualifiers. The following examples show a mapping table that uses qualifiers and a wrapping table that makes use of those qualifiers.

First, a partial mapping table example. These mapping rules assign qualifiers for the different heading levels so this hierarchy can be preserved. No qualifier is assigned to the <shortdesc> element since this is a unique element, only used in one situation. The “Body” tag is mapped to a <p> element and assigned a “L0” (level 0) qualifier. You could have additional types of paragraphs at this level and give them all “L0” qualifiers, and they would all get grouped together in the wrapping rule. The “Bullet1” tag is mapped to a <p> element and assigned a “B1” qualifier. This allows you to have list items that have multiple paragraphs, with the “Bullet1Cont” tag using a “L1” (level 1) qualifier.

P:Title title H0
P:Heading1 title H1
P:Heading2 title H2
P:Info shortdesc  
P:Body p L0
P:Bullet1 p B1
P:Bullet1Cont p L1

Next, a partial wrapping table example makes use of the qualifiers defined above. The list items always start with a “B1” item (note that the element name is not needed when referring to a “class” of elements), and are followed by zero or more “L1” items (in this case it’s only the Bullet1Cont paras, but could be other items like nested lists or figures, etc.). The “B1” <li> elements (one or more) are wrapped in a <ul>, which is assigned a “L0” qualifier. Then, all “L0” items are wrapped in <body>. Note that using qualifiers can simplify the wrapping rules by allowing you to refer to a group of elements. This also makes it easier to add new elements in the future as long as you remember the “rules” you used for the qualifiers.

In this example, when wrapping topics, because we assigned qualifiers to each of the heading levels, we are able to maintain the original hierarchy. Start at the lowest level (“H2” in this case) and wrap all <title>, <shortdesc> and <body> sequences in a <topic> element (which is assigned a “T2” qualifier). Then go to the next level (“H1”) and wrap those <title>, <shortdesc>, <body>, and zero or more “T2” <topic> sequences in a <topic> (assigned a “T1” qualifier). Then one more level to get the “T0” topics. It’s not likely that a file with have multiple “T0” topics, but just in case, make the final rule inclusive enough to wrap up more than one in a <dita> element.

E:[B1], E:[L1]* li B1
E:li[B1]+ ul L0
E:[L0]+ body  
E:title[H2], E:shortdesc?, E:body? topic T2
E:title[H1], E:shortdesc?, E:body?, E:topic[T2]* topic T1
E:title[H0], E:shortdesc?, E:body?, E:topic[T1]* topic T0
E:topic[T0]+ dita  

The root <dita> element may not always be needed, but for the FM2DITA topic processing tools, this is required.

...