Embedding Target Fragments

Whatever target format you decide to produce, PerlPoint cannot generate everything generically for it - there are always language elements that have no expression in PerlPoint, or that are not addressed by the format generator. For example, think of HTML output and CSS, if you want to assign multiple classes to a text fragment there is no direct PerlPoint way for it.

    <!-- How to produce this HTML with PerlPoint? -->
    bla bla <span class="multi classed">content</span> bla bla

In such cases, target format fragments can be embedded directly via \EMBED. \EMBED takes a lang parameter which declares what format is included. For our class example this would be "html" (preferably lowercased). Then, everything until an \END_EMBED tag is treated as belonging to the embedded part, including empty lines that normally would complete the current paragraph.

    bla bla
    \EMBED{lang=html}<span class="multi classed">\END_EMBED
    content\EMBED{lang=html}</span>\END_EMBED

Please note that \EMBED has no tag body - the < following this tag in our example does not open a tag body, but is the first character of the embedded text.

When PerlPoint finds an embedded part, it first checks if the specified language matches the current target format. This does not mean that it has exactly the same, but that the target format generator accepts this format. In our example, "html" is accepted both by pp2html (producing HTML) and all the XHTML generators invoked with perlpoint -target XHTML, which produce XHTML. To find out which formats are accepted for your call, please see the generators documentation. Usually you can assume that at least the target language itself is supported.

If the language is not accepted the embedded part is skipped. Otherwise, which is more interesting, the embedded fragment is made part of the generated output, without further processing. For our HTML example this means that the <span class="multi classed"> and </span> parts appear in the HTML produced.

Please note that embedded parts can result in results that are syntactically invalid, from the target formats point of view. It's up to the user to take care of that, PerlPoint doesn't analyze what you embed. For example, when adding an opening <span> tag into HTML output one should take attention to complete it by a related </span>.

When using embedded parts more often, it can be convenient to hide them by handy macros:

    // macro definition
    +MULTI_CLASSED:\EMBED{lang=html}
                     <span class="multi classed">
                   \END_EMBED__body__\EMBED{lang=html}
                     </span>
                   \END_EMBED
  
    // macro use
    bla bla MULTI_CLASSED<content> bla bla