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:
[HtmlStyles]
; Assign code placement to each GrInfo* paragraph format:
GrInfoStart=CodeBefore
GrInfoEnd=CodeAfter
GrInfo=CodeBefore CodeAfter
[StyleCodeBefore]
; Starting and sole paragraphs need code just before them:
GrInfo*=<$GrInfoBefore>
[StyleCodeAfter]
; 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.7 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