doc/xmllint.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl"
   href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<refentry>
  <refentryinfo>
    <title>xmllint Manual</title>
    <copyright>
      <year>2001</year>
    </copyright>
    <copyright>
      <year>2004</year>
    </copyright>
    <author>
      <firstname>John</firstname>
      <surname>Fleck</surname>
    </author>
    <address><email>jfleck@inkstain.net</email></address>
    <author>
      <firstname>Ziying</firstname>
      <surname>Sherwin</surname>
    </author>
    <address><email>sherwin@nlm.nih.gov</email></address>
    <author>
      <firstname>Heiko</firstname>
      <surname>Rupp</surname>
    </author>
    <address><email>hwr@pilhuhn.de</email></address>
    
    <releaseinfo>This is release 0.4 of the xmllint Manual.</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>xmllint</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>xmllint</refname>
    <refpurpose>command line <acronym>XML</acronym> tool</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>xmllint</command>
      <group>
	<arg>--version</arg>
	<arg>--debug</arg>
	<arg>--shell</arg>
	<arg>--debugent</arg>
	<arg>--copy</arg>
	<arg>--recover</arg>
	<arg>--noent</arg>
	<arg>--nocdata</arg>
	<arg>--nsclean</arg>
	<arg>--noout</arg>
	<arg>--htmlout</arg>
	<arg>--nowrap</arg>
	<arg>--valid</arg>
	<arg>--postvalid</arg>
	<arg>--dtdvalid <replaceable>URL</replaceable></arg>
	<arg>--dtdvalidfpi <replaceable>FPI</replaceable></arg>
	<arg>--timing</arg>
	<arg>--repeat</arg>
	<arg>--insert</arg>
	<arg>--compress</arg>
	<arg>--html</arg>
	<arg>--push</arg>
	<arg>--memory</arg>
	<arg>--nowarning</arg>
	<arg>--noblanks</arg>
	<arg>--format</arg>
	<arg>--testIO</arg>
	<arg>--encode <replaceable>encoding</replaceable></arg>
	<arg>--catalogs</arg>
	<arg>--nocatalogs</arg>
	<arg>--auto</arg>
	<arg>--xinclude</arg>
	<arg>--loaddtd</arg>
	<arg>--dtdattr</arg>
	<arg>--dropdtd</arg>
	<arg>--stream</arg>
	<arg>--chkregister</arg>
	<arg>--relaxng</arg>
	<arg>--schema</arg>
	<arg>--nonet</arg>
      </group>
      <arg><option><replaceable>xmlfile</replaceable></option></arg>
  </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="introduction">
    <title>Introduction</title>
    <para>
      The xmllint program parses one or more XML files, specified on the
      command line as <replaceable>xmlfile</replaceable>. It prints various
      types of output, depending upon the options selected. It is useful for
      detecting errors both in <acronym>XML</acronym> code and in the
      <acronym>XML</acronym> parser itself.
    </para>

    <para>
      It is included in <application>libxml2</application>.
    </para>
  </refsect1>
  <refsect1 id="options">
    <title>Options</title>
    <variablelist>
      <varlistentry>
	<term><option>--version</option></term>
	<listitem>
	  <simpara>
	    Display the version of
	    <application>libxml2</application> used.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--debug</option></term>
	<listitem>
	  <simpara>
	    Parse a file and output an annotated tree of the
	    in-memory version of the document.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--shell</option></term>
	<listitem>
	  <simpara>
	    Run a navigating shell. Details on available commands in shell mode
	    are below.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--debugent</option></term>
	<listitem>
	  <simpara>
	    Debug the entities defined in the document.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--copy</option> </term>
	<listitem>
	  <simpara>
	    Test the internal copy implementation.
	  </simpara>
	</listitem>
      </varlistentry>
    
      
      <varlistentry>
	<term><option>--recover</option></term>
	<listitem>
	  <simpara>
	    Output any parsable portions of an invalid
	    document.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--noent</option></term>
	<listitem>
	  <simpara>
	    Substitute entity values for entity
	    references. By default, <application>xmllint</application> leaves entity
	    references in place.
	  </simpara>
	</listitem>
      </varlistentry>
   
      <varlistentry>
	<term><option>--nocdata</option></term>
	<listitem>
	  <simpara>
	    Substitute CDATA section by equivalent text nodes.
	  </simpara>
	</listitem>
      </varlistentry>
   
      <varlistentry>
	<term><option>--nsclean</option></term>
	<listitem>
	  <simpara>
	    Remove redundant namespace declarations.
	  </simpara>
	</listitem>
      </varlistentry>
   
      <varlistentry>
	<term><option>--noout</option></term>
	<listitem>
	  <simpara>
	    Suppress output. By default,
	    <application>xmllint</application> outputs the result tree.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--htmlout</option></term>
	<listitem>
	  <simpara>
	    Output results as an <acronym>HTML</acronym>
	    file. This causes <application>xmllint</application> to output
	    the necessary <acronym>HTML</acronym> tags surrounding the result tree
	    output so the results can be displayed in a browser. 
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--nowrap </option></term>
	<listitem>
	  <simpara>
	    Do not output HTML doc wrapper.
	  </simpara>
	</listitem>
      </varlistentry>

<varlistentry>
	<term><option>--valid </option></term>
	<listitem>
	  <simpara>
	    Determine if the document is a valid instance
	    of the included Document Type Definition (<acronym>DTD</acronym>). A
	    <acronym>DTD</acronym> to be validated against also can be specified at
	    the command line using the <option>--dtdvalid</option> option. By default,
	    <application>xmllint</application> also checks to determine if the
	    document is well-formed.
	  </simpara>
	</listitem>
      </varlistentry>
   
 <varlistentry>
	<term><option>--postvalid</option></term>
	<listitem>
	  <simpara>
	    Validate after parsing is completed.
	  </simpara>
	</listitem>
      </varlistentry>
   
    <varlistentry>
	<term> <option>--dtdvalid</option> <replaceable>URL</replaceable></term>
	<listitem>
	  <simpara>
	    Use the
      <acronym>DTD</acronym> specified by <replaceable>URL</replaceable> for
      validation.
	  </simpara>
	</listitem>
      </varlistentry>
   
    <varlistentry>
	<term> <option>--dtdvalidfpi</option> <replaceable>FPI</replaceable></term>
	<listitem>
	  <simpara>
	    Use the
      <acronym>DTD</acronym> specified by the Public Identifier
      <replaceable>FPI</replaceable> for validation, note that this
      will require a Catalog exporting that Public Identifier to work.
	  </simpara>
	</listitem>
      </varlistentry>
   
     <varlistentry>
	<term><option>--timing</option></term>
	<listitem>
	  <simpara>
	    Output information about the time it takes
	    <application>xmllint</application> to perform the various steps.
	  </simpara>
	</listitem>
      </varlistentry>

   <varlistentry>
	<term><option>--repeat</option></term>
	<listitem>
	  <simpara>
	    Repeat 100 times, for timing or profiling.
	  </simpara>
	</listitem>
      </varlistentry>
   
    <varlistentry>
	<term><option>--insert</option></term>
	<listitem>
	  <simpara>
	    Test for valid insertions.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--compress</option></term>
	<listitem>
	  <simpara>
	    Turn on gzip compression of output.
	  </simpara>
	</listitem>
      </varlistentry>
   
    <varlistentry>
	<term><option>--html</option></term>
	<listitem>
	  <simpara>
	    Use the <acronym>HTML</acronym> parser.
	  </simpara>
	</listitem>
      </varlistentry>
   
    <varlistentry>
	<term><option>--push</option></term>
	<listitem>
	  <simpara>
	    Use the push mode of the parser.
	  </simpara>
	</listitem>
      </varlistentry>
   

    <varlistentry>
	<term><option>--memory</option></term>
	<listitem>
	  <simpara>
	   Parse from memory.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--nowarning</option></term>
	<listitem>
	  <simpara>
	   Do not emit warnings from the parser and/or validator.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--noblanks</option></term>
	<listitem>
	  <simpara>
	   Drop ignorable blank spaces.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--format</option></term>
	<listitem>
	  <simpara>
	   Reformat and reindent the output. The $XMLLINT_INDENT
	   environment variable controls the indentation (default 
	   value is two spaces &quot;  &quot;).
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--testIO</option></term>
	<listitem>
	  <simpara>
	   Test user input/output support.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
      <term><option>--encode</option> <replaceable>encoding</replaceable></term>
	<listitem>
	  <simpara>
	   Output in the given encoding.
	  </simpara>
	</listitem>
      </varlistentry>
    
    <varlistentry>
	<term><option>--catalogs</option></term>
	<listitem>
	  <simpara>
	   Use the catalogs from $SGML_CATALOG_FILES. Otherwise /etc/xml/catalog
	   is used by default.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--nocatalogs</option></term>
	<listitem>
	  <simpara>
	   Do not use any catalogs.
	  </simpara>
	</listitem>
      </varlistentry>
    
    <varlistentry>
	<term><option>--auto</option></term>
	<listitem>
	  <simpara>
	   Generate a small document for testing purposes.
	  </simpara>
	</listitem>
      </varlistentry>

    <varlistentry>
	<term><option>--xinclude</option></term>
	<listitem>
	  <simpara>
	   Do XInclude processing.
	  </simpara>
	</listitem>
      </varlistentry>
    <varlistentry>
	<term><option>--loaddtd</option></term>
	<listitem>
	  <simpara>
	   Fetch external DTD.
	  </simpara>
	</listitem>
      </varlistentry>
    
    <varlistentry>
	<term><option>--dtdattr</option></term>
	<listitem>
	  <simpara>
	   Fetch external DTD and populate the tree with inherited attributes.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--dropdtd</option></term>
	<listitem>
	  <simpara>
	    Remove <acronym>DTD</acronym> from output.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--stream</option></term>
	<listitem>
	  <simpara>Use streaming API - useful when  used  in combination with
              --relaxng or --valid options for validation of files that are
	    too large to be held in memory.</simpara> 
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--chkregister</option></term>
	<listitem>
	  <simpara>Turn on node registration. Useful for developeres testing
	  libxml2 node tracking code.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--relaxng</option> <replaceable>schema</replaceable></term>
	<listitem>
	  <simpara>Use RelaxNG file named <replaceable>schema</replaceable> for
	  validation.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--schema</option> <replaceable>schema</replaceable></term>
	<listitem>
	  <simpara>Use a W3C XML Schema file named <replaceable>schema</replaceable> for validation.</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
      <option>--nonet</option></term>
	<listitem>
	  <simpara>Do not use the Internet to fetch DTD's or entities.</simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="shell">
    <title>Shell</title>
    <para>
      <application>xmllint</application> offers an interactive shell mode
      invoked with the <option>--shell</option> command. Available commands in
      shell mode include:
    </para>
    <variablelist>
      <varlistentry>
	<term><option>base</option></term>
	<listitem>
	  <simpara>
	    display XML base of the node
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>bye</option></term>
	<listitem>
	  <simpara>
	    leave shell
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>cat <replaceable>node</replaceable></option></term>
	<listitem>
	  <simpara>
	    Display node if given or current node.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>cd <replaceable>path</replaceable></option></term>
	<listitem>
	  <simpara>
	    Change the current node to <replaceable>path</replaceable> (if given
	    and unique) or root if no argument given.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>dir <replaceable>path</replaceable></option></term>
	<listitem>
	  <simpara>
	    Dumps information about the node (namespace, attributes, content).
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>du <replaceable>path</replaceable></option></term>
	<listitem>
	  <simpara>
	    Show the structure of the subtree under path or the current node.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>exit</option></term>
	<listitem>
	  <simpara>
	    Leave the shell.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>help</option></term>
	<listitem>
	  <simpara>
	    Show this help.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>free</option></term>
	<listitem>
	  <simpara>
	    Display memory usage.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>load <replaceable>name</replaceable></option></term>
	<listitem>
	  <simpara>
	    Load a new document with the given name.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>ls <replaceable>path</replaceable></option></term>
	<listitem>
	  <simpara>
	    List contents of <replaceable>path</replaceable> (if given) or the
	    current directory.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>pwd</option></term>
	<listitem>
	  <simpara>
	    Display the path to the current node.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>quit</option></term>
	<listitem>
	  <simpara>
	    Leave the shell.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>save <replaceable>name</replaceable></option></term>
	<listitem>
	  <simpara>
	    Saves the current document to <replaceable>name</replaceable> if
	    given or to the original name.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>validate</option></term>
	<listitem>
	  <simpara>
	    Check the document for error.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>write <replaceable>name</replaceable></option></term>
	<listitem>
	  <simpara>
	    Write the current node to the given filename.
	  </simpara>
	</listitem>
      </varlistentry>
     
    </variablelist>
  </refsect1>
<refsect1>
   <title>Catalogs</title>
     <para>Catalog behavior can be changed by redirecting
     queries to the user's own set of catalogs. This can be done by setting the
     <varname>XML_CATALOG_FILES</varname> environment variable to a list of
     catalogs. An empty one should deactivate loading the default
      <filename>/etc/xml/catalog</filename> default catalog.</para>
  </refsect1>
  <refsect1>
    <title>Debugging Catalogs</title>
    <para>Setting the environment variable <varname>XML_DEBUG_CATALOG</varname>
    using the command <command>&quot;export XML_DEBUG_CATALOG=&quot;</command>
    outputs debugging information related to catalog operations.</para>
  </refsect1>
  <refsect1>
    <title>Error Return Codes</title>
    <para>On the completion of execution, <application>Xmllint</application>
    returns the following error codes:</para>
    <variablelist>
      <varlistentry>
	<term>0</term>
	<listitem>
	  <simpara>No error</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>1</term>
	<listitem>
	  <simpara>Unclassified</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>2</term>
	<listitem>
	  <simpara>Error in DTD</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>3</term>
	<listitem>
	  <simpara>Validation error</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>4</term>
	<listitem>
	  <simpara>Validation error</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>5</term>
	<listitem>
	  <simpara>Error in schema compilation</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>6</term>
	<listitem>
	  <simpara>Error writing output</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>7</term>
	<listitem>
	  <simpara>Error in pattern (generated when
	  <optional>--pattern</optional> option is used)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>8</term>
	<listitem>
	  <simpara>Error in Reader registration (generated when
	  <optional>--chkregister</optional> option is used)</simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>9</term>
	<listitem>
	  <simpara>Out of memory error</simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
</refentry>