List of XM processing instructions

[kmartin7]

Is there a comprehensive list of processing instructions XM uses so we can customize some templates?

[Derek Read]

Background:

Our philosophy is to keep the XML produced by our products as clean as possible. Historically we've thought long and hard when and if to use PIs to implement any particular feature.

Types of PIs Recognized by XMetaL Author (and XMAX):

There are only two cases I can think of where XMetaL Author uses PIs: for "replacement text" (essentially an "insert text here" prompt that sits inline in a document) and for the Change Tracking feature built into XMetaL Author (aka: Revision Marking).

Formats:

The format of replacement text is somewhat configurable. Typically this is done inside the customization's CTM file (ie: when element X is inserted, include replacement text to prompt the user to fill it in properly), or when creating an XML template, but these types of PIs can be inserted at any time (via scripting using APIs for example). To be recognized, the PI's target must be "xm-replace_text" while the PI's data can be anything validly contained within a PI's data (W3C XML Recommendation - Processing Instructions). The text contained within the data section is what will be rendered in the document as the text "prompt". The data section of the PI follows the first whitespace though it may itself contain whitespaces.

The format of the Change Tracking PIs is not configurable.

Examples:

Replacement Text:

Code:

<?xm-replace_text Topic Title?>

Change Tracking Deletion:

Code:

<?xm-deletion_mark author="dread" time="20090115T155627-0800"
data="&lt;p&gt;this is a deletion&lt;/p&gt;"?>

Change Tracking Insertion:

Code:

<?xm-insertion_mark_start author="dread" time="20090115T155630-0800"?>
<p>this is an insertion</p>
<?xm-insertion_mark_end?>

Other Types of PIs:

Author Created:
Document authors are free to insert their own PIs. In this case pretty much anything goes. These will do nothing in XMetaL Author (or XMAX) unless they match one of the formats above or the customization currently loaded contains special code to handle them. The most likely use-case for these would be to insert a PI that is used by other software. For example, a transformation engine might support specific PIs, or a browser you are targeting might support the W3C xml-stylesheet PI.

Developer Created:
Customization developers may decide their customization warrants the use of PIs. In this case they are free to make up their own target and data values. These PIs will not have any special meaning to XMetaL Author (or XMAX) unless the customization is programmed to recognize them and triggers certain actions using the many events and APIs available in the product.

Note: if you use XMetaL Author together with XMetaL Reviewer that product (Reviewer) uses PIs to track changes, comments, and other things when the two products are communicating. These PIs are typically removed when saving the document to another location (outside of Reviewer) and so other applications will never see them.

[mag3737]

To summarize, the only PI you need to know about for creating templates in XMetaL is "xm-replace_text" as Derek described it below.  You can include as many of these in your template as you need, anywhere content is allowed.  Only the name "xm-replace_text" is required; the rest can be whatever you wish, and will form the prompt that is displayed when the user opens the template.

(By the way, when you open in XMetaL Author an XMetaL Reviewer document with embedded comments, the Reviewer PIs Derek mentioned are actually in there, but we prevent you from ever seeing them by stripping them out if you switch to Plain Text View.)

[kmartin7]

We were just wondering if there was one that we could use that would display static text specific to a template that would NOT get published. More instructional than anything else. Make sense? Not a big issue at all, just trying understand everything before we start customization and deploy.

[Derek Read]

So, what would this text say? Do you want to guide the user in understanding the use for the template, or perhaps something else?

[mag3737]

You can do something like this very easily by making up your own PIs.  Since they will be "known" only by you, they should be ignored by the DITA OT and other processors.  You can add custom CSS so that XMetaL will display them distinctively during editing.  For example:

Put this PI in your document:

Code:

<?kmartin7 This is a very special PI?>

Add this to your CSS:

Code:

$procins[xm-pi-target="kmartin7"] {
display: inline;
color: Red;
background: Yellow;
}

("Add to which CSS?", you might justifiably ask.  In theory you should probably add it to every one of the DITA/XACs/[topicname]/[topicname]_ditabase-specialized.css files.  In practice, I would probably add it just once, to DITA/XACs/ditabase/ditabase-base-override.css, and then hopefully remember that when I upgrade/repair my XMetaL installation this file may be overwritten.)

Note about adding these in XMetaL:  You can add "custom" PIs using Insert > Advanced > Processing Instruction.  The very next thing you type should be the target ("kmartin7") then space, then the rest of the content.  The PI will initially be styled with the default PI colors.  To have your overriding colors kick in, change between Normal/Tags On after you finish typing the PI target name.

[jsmart]

Derek:

Can you advise best method to remove the  xm-replace_text.
InsertReplaceText call works great. We insert by API classes.

The GotoNext(0) does not seem to find xm-replace_text.  Want to loop the
text and remove all the PROCINs like <?xm-replace_text mystuff?>

Picture of Help Topic attached that mentions the call can remove
PROCINs  maybe all but not xm-replace_text.

Other XMetaL users - these are powerful features, need more info to exploit this feature.

[mag3737]

GotoNext(0) does match replace-text PIs in my testing, but there's a better way to remove them all.  The problem with GotoNext() is that I couldn't see an obvious way to write a loop that would terminate.

Here's what I would do instead:

Code:

//XMetaL Script Language JScript:

var nodes = ActiveDocument.getNodesByXPath("//processing-instruction('xm-replace_text')");
while (nodes.length > 0) {
myparent = nodes.item(0).parentNode;
myparent.removeChild(nodes.item(0));
}

[sethim]

Hi Tom,

I'm trying the same thing to access processing instructions for tracking changes. so instead of using xm-replace_text I'm using 'Document.getNodesByXPath("//processing-instruction('xm-insertion_mark_start')");'  but everytime a no nodes is being returned.

Is there a different syntax for track changes??

Thanks

[Derek Read]

You can't use getNodesByXPath() in this particular case because of the way XMetaL keeps track of revision marking 'nodes' (in memory). In the source XML they are true and proper PIs (as you can see when you switch to Plain Text view or upon examination with another tool after saving) but for various complex reasons XMetaL Author (and XMAX) doesn't really add them directly to it's DOM node list and so DOM related calls will fail specifically (and only) for these PIs.

What do you need to with them? Do you need to 'accept' them, 'reject' them, 'accept all', 'reject all', or are you attempting to remove them, check their content, replace them with something else, etc?

There are APIs that correspond to the functions exposed in the "Accept or Reject Changes" dialog. Perhaps that is what you are looking for? The methods are:
  ActiveDocument.GotoNextChange()
  ActiveDocument.GotoPrevChange()
  ActiveDocument.AcceptAllChanges()
  ActiveDocument.RejectAllChanges()