### 37.10 Using macros to fine-tune HTML or XML output

You can use macros and macro variables to solve special HTML or XML problems that are not addressed by the usual DITA2Go configuration settings. This section describes the best approach.

Start from the HTML end. Take one of the output .htm files DITA2Go generates from your DITA document and use a plain-text editor to modify the HTML code:

1. Look at the code DITA2Go produces, and decide what additional bits of code are needed to achieve the effect you want; for example, <table>, <tr>, and <td> tags to create a two-cell table around an in-line image and its adjacent text.
2. Add the bits of code to the HTML, on lines of their own where possible, and view the result in a browser. You might have to experiment with variations until you get the effect you want.
3. Include the successful HTML code in DITA2Go macro definitions. Make each separate chunk of added code into one macro. For example (assuming the anchor for each in-line image is at the very start of the adjacent text):

   [GrInfoBefore]
   ; Start a table, row, and cell just before an in-line image:
   <table class="GrInfo"><tr><td>\

   [GrImgEnd]
   ; After an in-line image, start a new cell for the adjacent text:
   </p></td><td><p class="Body">

   [GrInfoAfter]
   ; After the adjacent text, end the cell, row, and table:
   </p></td></tr></table>

   See §37.1.1 Defining macros.

4. Consider where your new HTML-code macros should go in the document flow. Do they precede the opening of some type of paragraph? Follow the closing? Go at the top or bottom of the page? Or just get plunked in at arbitrary points? You might have to define some new paragraph formats to identify places to invoke the macros. For example, if sometimes you have multiple paragraphs of text adjacent to an in-line image, you might need three different format names for those paragraphs:

   GrInfoStart — First paragraph

   GrInfoEnd — Last paragraph

   GrInfo — Sole paragraph

   If you do not want to change format names, you could put HTML Macro PI markers before and after each instance of adjacent text. The starting PI marker would contain:

   <$GrInfoBefore>

   and the ending PI marker would contain:

   <$GrInfoAfter>

   You would keep the same macros defined in Step 3, and get the same result.

5. Tell DITA2Go where to invoke the macros in the output, so the code gets inserted in the right places automatically, by adding settings to the configuration file to invoke your new macros. For example, to invoke the macros defined in Step 3 whenever DITA2Go encounters paragraphs in the formats defined in Step 4:

   [HTMLParaStyles]
   ; Assign code placement to each GrInfo* paragraph format:
   GrInfoStart=CodeBefore
   GrInfoEnd=CodeAfter
   GrInfo=CodeBefore CodeAfter

   [ParaStyleCodeBefore]
   ; Starting and sole paragraphs need code just before them:
   GrInfo*=<$GrInfoBefore>

   [ParaStyleCodeAfter]
   ; Ending and sole paragraphs need code to follow them:
   GrInfo*=<$GrInfoAfter>

   [GraphEndMacros]
   ; The image itself needs code to close its cell:
   *=<$GrImgEnd>

   See §37.1.2 Invoking a macro and §37.9.3 Surrounding or replacing text with code or macros.

6. Convert the file again, and see if the new code shows up where it is needed. Does the code also pop up where it is not wanted? If so, you can include a test to prevent the code from appearing in other places. For example, to avoid creating a table around a graphic that does not have adjacent text, you could modify the macros in Step 3 to use a macro variable and a conditional expression (both shown in boldface):

   [GrInfoBefore]
   <$$GrInf = 1>
   <table class="GrInfo"><tr><td>\

   [GrImgEnd]
   <$_if ($$GrInf)></p></td><td><p class="Body"><$_endif>

   [GrInfoAfter]
   </p></td></tr></table>
   <$$GrInf = 0>

   [MacroVariables]
   ; Put any macro definition sections before this section.
   GrInf=0

   See §37.3 Using macro variables and §37.6.4.2 Using conditional expressions.

Previous Topic: 37.9.6 Implementing drop-down text with macros

Next Topic: 38. Working with processing instructions

Parent Topic: 37. Working with macros

Sibling Topics:

37.1 Defining and invoking macros

37.2 Accessing DITA2Go macro libraries

37.3 Using macro variables

37.4 Using multiple-value list variables

37.5 Accessing settings with configuration macros

37.6 Using expressions in macros

37.7 Passing a parameter to a macro

37.8 Debugging macros

37.9 Deploying macros and macro variables

Table of Contents • Index