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