Renames paragraph tags based on surrounding paragraph tags.
If you are converting into multiple structural models, it is typically required to have unique paragraph tags in each model group. This is needed to differentiate between concept and task, for example, but also within topics (like task) to identify paragraphs within different sections. This command assigns a prefix to specified paragraph tags based on tag matching rules defined in the RetagParas section of the fm2dita.ini file.
This command can make multiple passes over a document, allowing you to build up “layers” of tag names based on changes made in a previous pass. There are two basic types of rules that can be used. A “tag until” rule starts assigning a prefix to the tag of all paragraphs that follow a specified paragraph tag until it reaches another specified paragraph tag. A “look ahead” rule assigns a prefix to a specified paragraph’s tag if the paragraph tags that follow match the specified rule. Using a combination of these rules provides very powerful retagging capabilities.
This command requires initial setup in the RetagParas section of the fm2dita.ini file. The following options may be set:
NumPasses - the number of passes or iterations to perform. For more than one pass, you’ll need to add additional RetagParas-<N> sections to the INI file. Default value: “1”
Delim - the delimiter character used to separate the tag name from the associated prefix (described below). Default value: “>”
Count - the number of tag/prefix rules in this section.
<N> - tag/prefix rules identified by sequential numeric values (starting with “1”). Depending on the format of the tag/prefix rules, different types of processing is performed (see below for details and examples). The prefix is optional, and if provided is separated from the tag name by the “Delim” character.
Refer to the information in Editing the fm2dita.ini File for additional information on these INI parameters.
This command must be run before applying the conversion table (since the conversion table should be designed to key off of these new tag names).
Although there are two basic types of rules, “tag until” and “look ahead”, there are three formats for rules that can be used in a RetagParas section. The fundamental syntax for all rules is as follows (note that the square brackets here are actual characters, not indicators of optional content):
TAG[MATCHRULE]>PREFIX
Where:
Specifies the paragraph tag to operate on or from (depending on the existence of the MATCHRULE). All TAG values must be unique in each section; if you need to use different MATCHRULE values for the same TAG name, create additional sections and increment the number of NumPasses.
Only used for the “look ahead” type of retagging rule. Defines the sequence of paragraph tags that may follow the TAG paragraph. The syntax of the MATCHRULE loosely follows the syntax used for DTD general rule specification. The MATCHRULE can use parenthesis to group tag names separated with a vertical bar, but nested groups are not supported. The following operators are supported to indicate the frequency or existence of tags: “*” (zero or more), “+” (one or more), and “?” (optional). These operators must never be used within a group of tag names, and should follow the closing parenthesis if used. If no operator is used, that tag is required in the sequence.
A prefix string that is applied to the matching paragraph tag names. Depending on the existence of a MATCHRULE, the prefix string is either applied to the TAG paragraph or the paragraph tags that follow the TAG paragraph. The PREFIX is separated from the TAG/MATCHRULE by the Delim character (default “>”) indicated in the INI file. The PREFIX is optional.
If the TAG is specified with a following PREFIX, the command applies that prefix string to all paragraph tags that follow each TAG paragraph tag, until another TAG paragraph tag is encountered.
If the TAG is specified with no PREFIX, it tells the command to stop applying the prefix without adding a new prefix to later paragraph tags.
If the TAG is specified with a following square bracketed MATCHRULE descriptor, that descriptor phrase tells the command to only match a TAG when the sequence of tags indicated in the MATCHRULE is a match. When this match occurs, the PREFIX specified (required in this case) is applied to the TAG paragraph tag, and not the tags that follow.
A document may use H0, H1, and H2 tags for the general headings and a ToDo tag for procedures. The following INI section will retag the paragraphs in the H1 and H2 sections with a “con-” prefix, and the paragraphs in the ToDo sections with a “task-” prefix. It leaves the paragraphs in the H0 section without a prefix (no delimiter character or prefix is specified for the H0 tag).
[RetagParas] NumPasses=1 Delim=> Count=4 1=H0 2=H1>con- 3=H2>con- 4=ToDo>task-
If you want to apply multiple levels of prefixes (often useful to differentiate sections in task topics), set the NumPasses parameter to the number of passes to perform. When applying multiple passes on a document, you should start with the “lowest” level of tags. The following INI sections provide for separate tagging of the “step” content from any content that might precede the steps (in the “context” section of a task).
[RetagParas] NumPasses=2 Delim=> Count=5 1=H0 2=H1 3=H2 4=ToDo 5=step>step- [RetagParas-2] Count=4 1=H0 2=H1>con- 3=H2>con- 4=ToDo>task-
You’ll notice that in the first pass (RetagParas section), only the “step” tags are “prefix restart” paragraphs. The other tags are included so the retagging will stop when the task ends. In the second pass (RetagParas-2 section) an additional prefix is applied, and in this section the “step” tag is omitted so it will itself get another prefix, along with any paragraphs in each step.
The look ahead rules make use of the MATCHRULE descriptor phrase that follows the TAG in a rule definition. This is used when your source document doesn’t contain special heading paragraph tags that you can use to identify specific topic groups. For example, if a document doesn’t use a ToDo tag for task headings, but always starts a task with some Body paragraphs followed by a numbered list with the tag NumStep. This may happen after a H1, H2, or H3 heading.
This type of rule is typically used with a following “tag until” rule in a multipass operation. In the example below, the first pass applies a “task-” prefix to the H1, H2, and H3 headings that match the MATCHRULE descriptor. It leaves all other tags alone. In the second pass, all unprefixed headings are assumed to be concept topics and apply the “con-” prefix to all content after each heading. It also assigned the “task-” prefix to all content after the task-tagged headings.
[RetagParas] NumPasses=2 Delim=> Count=3 1=H1[Body*,NumStep]>task- 2=H2[Body*,NumStep]>task- 3=H3[Body*,NumStep]>task- [RetagParas-2] Count=7 1=H0 2=H1>con- 3=H2>con- 4=H3>con- 5=task-H1>task- 6=task-H2>task- 7=task-H3>task-
You can create multiple groups of rules for the RetagParas command. To make use of this feature, add a RetagParaGroups section to the INI file.
[RetagParasGroups] Count=2 1=First Group 2=Second Group
With this set up, when you run the RetagParas command, you'll get a dialog prompting you to select the group to run.
When using this feature, the section names for the first group will start with “RetagParas1”, the second group will start with “RetagParas2”, and so on. For example, what would normally be the main RetagParas section will be RetagParas1. If this group has multiple passes, what would normally be “RetagParas-2” is now “RetagParas1-2”.
All of the functionality within a group is identical to before.