XML Data Islands ($X$ Commands)

The Advanced Find & Replace dialog provides $M$ commands that help you manage MS help 2 XML data Islands embedded in HTML topics. See your VSHIK documentation for more information on XML data Islands.

Reference Info:

[New for FAR HTML 5] Instead of using these low level $M$ search commands, use the Tag Editor dialog (Authoring menu). For most jobs this is a much easier and safer way to manipulate help tags. Eventually we will deprecate the $M$ commands and replace them with a simpler command. For now they are still fully supported in FAR.

 

XML Data Island Search Commands:

In the Advanced Find & Replace dialog set:

Starting with: <xml>
Ending with:   </xml>
Replace Text: $X*$ or $X+$ or $X-$ or $X$ or $X@$
     followed by the new XML markup.

$X*$ Replace XML markup with supplied XML.
$X+$ Merge supplied XML markup into match. Duplicates are never added.
$X-$ Remove supplied XML from match.
$X?$ Find all XML markup in all HTML files. New Markup not required for this command.
$X@$ Find supplied XML.


Note:

  • The following examples assume you have already create a list of HTML files in the FAR main window to work on.
  • As usual FAR Find & Replace will prompt you for all destructive changes and display a preview of the actual match and replace text.
  • If the XML code in the match and in the replace text are identical, FAR will skip the file as there is nothing to do. This is different from the usual FAR Find & Replace behaviour.
  • The $X*$ and $X+$ commands will force the XML code into the header of any file not already containing an XML Data Island.
  • The $X$ commands can only be used in the Replace text field.
  • The $X$ command should be the first line of the replace text. The XML markup follows on the second and consecutive lines.
  • The <xml> and </xml> lines in the replace text are optional. If you omit them they will still be inserted if required into final replace text.
  • The Markup indent can be set for all items in the replace block by inserting spaces before the first XML markup item.
Example 1: $X*$ Replace XML
Starting with: <xml>
Ending with: </xml>
Replace Text: $X*$
   <MSHelp:RLTitle Title="About This Button (HelpWare)"/>
   <MSHelp:Attr Name="helpware" Value="h2reg"/>
   <MSHelp:Attr Name="Locale" Value="kbEnglish"/>
   <MSHelp:Attr Name="TopicType" Value="kbRef"/>
   <MSHelp:Attr Name="LinkGroup" Value="HelpwareHelp"/>
   <MSHelp:Keyword Index="F" Term="System.Windows.Forms.Button"/>

Description:  In the above example the $X*$ command tells FAR to replace all occurrences of <xml>...</xml> with the specified data Island. If an HTML file does not contain an XML Data Island we force it into the HTML head section immediately after the </title> tag.

VS. NET Note: Collections that plug into MS.VSCC must have the Locale and TopicType items defined in all topics XML data Islands. The Helpware items are markup specifically for our software company.

Example 2: $X+$ Merge XML
Starting with: <xml>
Ending with: </xml>
Replace Text: $X+$
<xml>
   <MSHelp:Keyword Index="F" Term="IAnimation.Interval"/>
   <MSHelp:Keyword Index="F" Term="MyAssemblyNamespace.IAnimation.Interval"/>
</xml>

Description:  In the above example the $X+$ command tells FAR to check all XML Data Island markup and add in these two lines if they do not already exist. Files containing no <xml>...</xml> section will also be added to.

Example 3: $X-$ Remove XML
Starting with: <xml>
Ending with: </xml>
Replace Text: $X-$
<xml>
   <MSHelp:Keyword Index="F" Term="IAnimation.Interval"/>
   <MSHelp:Keyword Index="F" Term="MyAssemblyNamespace.IAnimation.Interval"/>
</xml>

Description:  In the above example the $X-$ command tells FAR to check all XML Data Island markup and to remove any of the markup specified in the replace text.

Example 4: $X?$ Find All XML
Starting with: <xml>
Ending with: </xml>
Replace Text: $X?$  ;Any other replace text is ignored

Description:  In the above example the $X?$ command tells FAR to find all XML Data Island markup and finally display the list (sorted with duplicates removed) in the H2 Utilities window XML Markup page. The Find & Replace preview dialog is not display during search. Notice this command uses the Replace Text field however no replacements are preformed. This was just a convenient way to trigger a customized search.

Example 4: $X@$ Find XML
Starting with: <xml>
Ending with: </xml>
Replace Text: $X@$
<xml>
   <MSHelp:Keyword Index="F" Term="IAnimation.Interval"/>
   <MSHelp:Keyword Index="F" Term="MyAssemblyNamespace.IAnimation.Interval"/>
</xml>

Description:  In the above example the $X@$ command tells FAR to search for the specified XML markup. Only files containing all specified items will be matched. The Find & Replace preview dialog is not display during search. Notice this command uses the Replace Text field however no replacements are preformed. This was just a convenient way to trigger a customized search.

http://www.HelpwareGroup.com/