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:
[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.
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">
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.
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.
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.