#### 37.9.3 Surrounding or replacing text with code or macros

For a better way to surround text with any arbitrary content, you can include start, end, before, and after settings in a format configuration file; see §7.4.8 Assigning content-adding properties to formats.

To specify code to be invoked before, after, or in place of a paragraph or character format:

1. List the format name in the configuration section appropriate for your output type:

   [HTMLParaStyles] or

   [HTMLCharStyles] for HTML, XML, or HTML-based Help

   [WordStyles] for Word

   [HelpStyles] for WinHelp.

2. Assign to the format one of the Code* properties listed in Table 37-10. For example:

       [HTMLParaStyles]
       PopHead=CodeBefore

3. List the same format name in the corresponding [ParaStyleCode*] or [CharStyleCode*] or [AnumCode*] section, and assign to it whatever macros (or code, or both) you want inserted at that point in the resulting output. For example:

       [ParaStyleCodeBefore]
       PopHead=<$$isPopup=1>

   This assignment can include any macros of the form <$Macroname> or, for HTML output, <$.\macrofile.htm>.

   Note: If the code you assign requires more than one line, you must specify a macro for it, because a key=value entry cannot exceed one line; see §3.4 Understanding the rules for configuration settings.

You can also assign a macro to a format in section [StyleLinkSrc], to provide code for the href attribute of HTML links; see §28.2.4 Specifying link properties with macros.

Table 37-10 Macro code placement properties

Property | Configuration section* | HTML code placement | RTF code placement
* For HTML conversions, DITA2Go recognizes section names prefixed with Html (as in [HtmlStyleCodeAfter]) for backward compatibility.
    CodeBefore
    [ParaStyleCodeBefore],
    [CharStyleCodeBefore]
| Before the starting element tag, such as <p> | Before the paragraph starting \pard, or before the opening brace for character formats
    CodeAfter
    [ParaStyleCodeAfter],
    [CharStyleCodeAfter]
| Right after the closing element tag | Right after the closing \par, or after the closing brace for character formats
    CodeBeforeAnum
    [AnumCodeBefore]
| Before the paragraph autonumber (does not apply to character formats) | Before the paragraph autonumber (does not apply to character formats)
    CodeAfterAnum
    [AnumCodeAfter]
| After the paragraph autonumber (does not apply to character formats) | After the paragraph autonumber (does not apply to character formats)
    CodeStart
    [ParaStyleCodeStart],
    [CharStyleCodeStart]
| Right after the starting element tag | At the start of the text, after properties; if a starting character format also has a CodeStart macro, both are used
    CodeEnd
    [ParaStyleCodeEnd],
    [CharStyleCodeEnd]
| Before the closing element tag, such as </p> | At the end of the text just before \par, or before the closing brace for character formats
    CodeReplace
    [ParaStyleCodeReplace],
    [CharStyleCodeReplace]
| Instead of paragraph or character content; any CodeBefore or CodeAfter is ignored | Instead of paragraph or character content; any CodeBefore or CodeAfter is ignored
    LinkSrc
    [ParaStyleLinkSrc],
    [CharStyleLinkSrc]
| In the href attribute of an HTML link | Does not apply to RTF output

For example, to precede each major heading in HTML with an image:

    [HTMLParaStyles]
    Heading1=CodeBefore

    [ParaStyleCodeBefore]
    Heading1=<p class="MyImageTag"><$Mona></p>

Later in the configuration file, or in a macro library file:

    [Mona]
    <img src="smile.jpg" alt="Leonardo's friend Mona" />

The effect in the resulting HTML would be to display the image smile.jpg just before each element mapped from a Heading1 paragraph.

A macro does not have to be well formed by itself; only the end result must be well formed, after all macros are included. For example, suppose you use formats A, B, and C, one after the other, and you want all of them centered in HTML output. You could use these settings to achieve that effect:

    [HTMLParaStyles]
    A=CodeBefore
    C=CodeAfter

    [ParaStyleCodeBefore]
    A=<div align="center">

    [ParaStyleCodeAfter]
    C=</div>

Text properties for RTF

You can use [ParaStyleCodeBefore] and [ParaStyleCodeAfter] to place ruled lines or images before and after a heading in RTF output. You can use [ParaStyleCodeStart] to add properties to text in RTF output, such as borders or background shading.

Tables for HTML

You can use [ParaStyleCodeBefore] and [ParaStyleCodeAfter] to construct a table around a paragraph for HTML, possibly with an image in a cell; this works well for notes or tips. You can also construct a table around a series of paragraphs.

Entire document for HTML

You could have a DITA file that contains only a single paragraph, specify CodeReplace for that paragraph format, and assign to it a [ParaStyleCodeReplace] macro; then build the whole HTML output from macros, using macro variables (see §37.3 Using macro variables) to include specific content based on user entries.

See also:

§37.3.5 Creating macro variables from paragraph content

Previous Topic: 37.9.2 Invoking macros at predetermined points in output

Next Topic: 37.9.4 Assigning macros to graphics or tables for HTML

Parent Topic: 37.9 Deploying macros and macro variables

Sibling Topics:

37.9.1 Understanding where to use macros and macro variables

37.9.2 Invoking macros at predetermined points in output

37.9.4 Assigning macros to graphics or tables for HTML

37.9.5 Using HTML Macro PI markers to invoke macros

37.9.6 Implementing drop-down text with macros