<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">

<s1 title="&XercesCName; Sample 14: IDOMPrint">

    <s2 title="IDOMPrint">
        <p>IDOMPrint parses an XML file, constructs the DOM tree, and walks
		through the tree printing each element. It thus dumps the XML back
		(output same as SAXPrint).</p>

        <s3 title="Building on Windows">
        <p>Load the &XercesCInstallDir;-win32\samples\Projects\Win32\VC6\samples.dsw
        Microsoft Visual C++ workspace inside your MSVC IDE. Then
        build the project marked IDOMPrint.
        </p>
        </s3>
        <s3 title="Building on UNIX">
<source>cd &XercesCInstallDir;-linux/samples
./runConfigure -p&lt;platform&gt; -c&lt;C_compiler&gt; -x&lt;C++_compiler&gt;
cd IDOMPrint
gmake</source>
        <p>
        This will create the object files in the current directory and the executable named
        IDOMPrint in '&XercesCInstallDir;-linux/bin' directory.</p>

        <p>To delete all the generated object files and executables, type</p>
<source>gmake clean</source>
        </s3>

        <s3 title="Running IDOMPrint">

          <p>The IDOMPrint sample parses an XML file, using either a validating
		  or non-validating IDOM parser configuration, builds a DOM tree,
		  and then walks the tree and outputs the contents of the nodes
		  in a 'canonical' format. To run IDOMPrint, enter the following:</p>
<source>IDOMPrint &lt;XML file&gt;</source>
          <p>The following parameters may be set from the command line </p>
<source>Usage: IDOMPrint [options] file

This program invokes the &XercesCName; IDOM parser and builds the DOM
tree. It then traverses the DOM tree and prints the contents
of the tree. Options are NOT case sensitive.

Options:
    -e          Expand entity references. Default is no expansion.
    -u=xxx      Handle unrepresentable chars [fail | rep | ref*]
    -v=xxx      Validation scheme [always | never | auto*]
    -n          Enable namespace processing. Default is off.
    -x=XXX      Use a particular encoding for output. Default is
                the same encoding as the input XML file. UTF-8 if
                input XML file has not XML declaration.
    -?          Show this help (must be the only parameter)

  * = Default if not provided explicitly

The parser has intrinsic support for the following encodings:
    UTF-8, USASCII, ISO8859-1, UTF-16[BL]E, UCS-4[BL]E,
    WINDOWS-1252, IBM1140, IBM037</source>
          <p><em>-u=fail</em> will fail when unrepresentable characters are encountered<br/>
             <em>-u=rep</em> will replace with the substitution character for that codepage<br/>
             <em>-u=ref</em> will report the character as a reference</p>
          <p><em>-v=always</em> will force validation<br/>
             <em>-v=never</em>  will not use any validation<br/>
             <em>-v=auto</em>   will validate if a DOCTYPE declaration is present in the XML document</p>
          <p>Here is a sample output from IDOMPrint</p>
<source>cd &XercesCInstallDir;-linux/samples/data
IDOMPrint -v personal.xml

&lt;?xml version="1.0" encoding="iso-8859-1"?&gt;

&lt;!DOCTYPE personnel SYSTEM "personal.dtd"&gt;
&lt;!-- @version: --&gt;
&lt;personnel&gt;

&lt;person id="Big.Boss"&gt;
  &lt;name&gt;&lt;family&gt;Boss&lt;/family&gt; &lt;given&gt;Big&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;chief@foo.com&lt;/email&gt;
  &lt;link subordinates="one.worker two.worker three.worker
                         four.worker five.worker"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;person id="one.worker"&gt;
  &lt;name&gt;&lt;family>Worker&lt;/family&gt; &lt;given&gt;One&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;one@foo.com&lt;/email&gt;
  &lt;link manager="Big.Boss"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;person id="two.worker"&gt;
  &lt;name&gt;&lt;family&gt;Worker&lt;/family&gt; &lt;given&gt;Two&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;two@foo.com&lt;/email&gt;
  &lt;link manager="Big.Boss"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;person id="three.worker"&gt;
  &lt;name&gt;&lt;family>Worker&lt;/family&gt; &lt;given&gt;Three&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;three@foo.com&lt;/email&gt;
  &lt;link manager="Big.Boss"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;person id="four.worker"&gt;
  &lt;name&gt;&lt;family&gt;Worker&lt;/family&gt; &lt;given&gt;Four&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;four@foo.com&lt;/email&gt;
  &lt;link manager="Big.Boss"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;person id="five.worker"&gt;
  &lt;name&gt;&lt;family&gt;Worker&lt;/family&gt; &lt;given&gt;Five&lt;/given&gt;&lt;/name&gt;
  &lt;email&gt;five@foo.com&lt;/email&gt;
  &lt;link manager="Big.Boss"&gt;&lt;/link&gt;
&lt;/person&gt;

&lt;/personnel&gt;</source>
          <p>Note that IDOMPrint does not reproduce the original XML file. IDOMPrint and
           SAXPrint produce different results because of the way the two APIs store data
           and capture events.</p>
        </s3>
    </s2>
</s1>