### 38.5 Inserting code with PI markers

DITA2Go can insert the content of a PI marker directly in output, at the location where it occurs in your DITA document. This is what happens by default to the content of any PI marker of type Code. For example, you could include a literal &nbsp; in your HTML output with:

    <?dthtm code="&nbsp;" ?>

If Code PI marker content includes DITA2Go macros, the macros are expanded.

To place PI marker content at a location in HTML or XML that is outside of any paragraph, dedicate a paragraph format to this use (for example, MarkerOnly). Put the PI marker in an otherwise empty element to which you have assigned the MarkerOnly paragraph format, and assign the following property:

    [HTMLParaStyles]
    MarkerOnly = Raw

See §30.2.4 Stripping paragraph properties.

If you assign the Code property to a PI marker type (see §38.4 Assigning properties to PI marker types), you can have DITA2Go surround the content with additional “before” and “after” code, or replace the content with code:

    [MarkerTypeCodeBefore]
    ; marker type name = macro
    ; for PI markers assigned the Code property in MarkerTypes.

    [MarkerTypeCodeAfter]
    ; marker type name = macro
    ; for PI markers assigned the Code property in MarkerTypes.

    [MarkerTypeCodeReplace]
    ; marker type name = macro
    ; for PI markers assigned the Code property in MarkerTypes.

DITA2Go expands macros assigned in these sections. If the PI marker type is assigned the Code property and PI marker content includes macros, those macros are expanded, also.

Suppose you need to provide code that must be processed at the start of a topic, before anything has been written to the topic file; for example, variable content to be included in the <head> element of each HTML topic.

Because the same variable can be assigned a different value multiple times in a document, DITA2Go processes each assignment as it is encountered. Therefore, the assignment of a particular value to a variable must ordinarily precede the point where the variable is used. To get around this restriction, you can assign property TopicStartCode to a PI marker, to have the code executed before the topic starts.

For example, to provide a Help keyword in an XML section of the <head> element, you could assign property TopicStartCode to a custom PI marker:

    [MarkerTypes]
    F1Keyword = TopicStartCode

    [MarkerTypeCodeBefore]
    F1Keyword = <$$F1Key = "

    [MarkerTypeCodeAfter]
    F1Keyword = ">

    [Inserts]
    Head = <$KeyIndexF>

In macro <$KeyIndexF>, you would include code such as the following:

    <Help:Keyword Index="F" Term="<$$F1Key>"/>

As another example, to include a variable number of keywords, each in its own <meta> tag:

    [MarkerTypes]
    MetaKeys = TopicStartCode

    [MarkerTypeCodeBefore]
    MetaKeys = <$$KeyCount++><$$Keywords[$$KeyCount] = "

    [MarkerTypeCodeAfter]
    MetaKeys= ">

    [Inserts]
    Head = <$AddKeywords>

    [AddKeywords]
    <$_repeat ($$KeyCount)>
    <meta name="Help.Keywords" content="<$$Keywords[$$_count]>" />\n
    <$_endrepeat><$$KeyCount=0>

    [Macros]
    OmitMacroReturns=Yes

    [MacroVariables]
    KeyCount=0

In this variation, you would use a counter ($$KeyCount) that starts at zero. As DITA2Go processes the MetaKeys markers for the start of the topic, the counter is incremented before each marker. The counter is used to index an array variable, into which the marker content is stored. Each succeeding MetaKeys marker gets its own slot in the array.

When DITA2Go is ready to write the <head> of the topic, the <$_repeat> loop (see §37.6.4.3 Using loop structures) writes as many <meta> tags as there were MetaKeys markers, each with the content from one marker, and the counter is set back to zero for the next file.

Previous Topic: 38.4 Assigning properties to PI marker types

Next Topic: 39. Working with templates

Parent Topic: 38. Working with processing instructions

Sibling Topics:

38.1 Understanding DITA2Go PI markers

38.2 Understanding effects of PI markers

38.3 Adding attributes with PI markers

38.4 Assigning properties to PI marker types