path: root/doc/xmlcatalog.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" [

    <!ENTITY xmlcatalog "<command>xmlcatalog</command>">
]>

<refentry>

<refentryinfo>
    <title>xmlcatalog Manual</title>
    <productname>libxml2</productname>
    <copyright>
        <year>2001</year>
        <year>2004</year>
    </copyright>
    <author>
        <firstname>John</firstname>
        <surname>Fleck</surname>
        <affiliation>
            <address>
                <email>jfleck@inkstain.net</email>
            </address>
        </affiliation>
    </author>
    <!-- still a bit buggy output, will talk to docbook-xsl upstream to fix this -->
    <!-- <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> -->
    <!-- <edition>0.3</edition> -->
</refentryinfo>

<refmeta>
    <refentrytitle>xmlcatalog</refentrytitle>
    <manvolnum>1</manvolnum>
</refmeta>

<refnamediv>
    <refname>xmlcatalog</refname>
    <refpurpose>
        Command line tool to parse and manipulate <acronym>XML</acronym>
        or <acronym>SGML</acronym> catalog files.
    </refpurpose>
</refnamediv>

<refsynopsisdiv>
    <cmdsynopsis>
    <command>xmlcatalog</command>
    <group choice="opt">
        <arg choice="plain"><option>--sgml</option></arg>
        <arg choice="plain"><option>--shell</option></arg>
        <arg choice="plain"><option>--convert</option></arg>
        <arg choice="plain"><option>--create</option></arg>
        <arg choice="plain"><option>--del <replaceable>VALUE(S)</replaceable></option></arg>
        <arg choice="plain">
            <group choice="opt">
                <arg choice="plain">
                    <option>--add
                     <replaceable>TYPE</replaceable>
                     <replaceable>ORIG</replaceable>
                     <replaceable>REPLACE</replaceable>
                    </option>
                </arg>
                <arg choice="plain"><option>--add <replaceable>FILENAME</replaceable></option></arg>
            </group>
        </arg>
        <arg choice="plain"><option>--noout</option></arg>
        <arg choice="plain"><option>--no-super-update</option></arg>
        <arg choice="plain">
            <group choice="opt">
                <arg choice="plain"><option>-v</option></arg>
                <arg choice="plain"><option>--verbose</option></arg>
            </group>
        </arg>
    </group>
    <arg choice="req" rep="norepeat"><replaceable>CATALOGFILE</replaceable></arg>
    <arg choice="req" rep="repeat"><replaceable>ENTITIES</replaceable></arg>
    </cmdsynopsis>
</refsynopsisdiv>

<refsect1 id="description">
    <title>DESCRIPTION</title>
    <para>
        &xmlcatalog; is a command line application allowing users to monitor and
        manipulate <acronym>XML</acronym> and <acronym>SGML</acronym> catalogs. It
        is included in <citerefentry>
            <refentrytitle>libxml</refentrytitle>
            <manvolnum>3</manvolnum>
        </citerefentry>.
    </para>
    <para>
        Its functions can be invoked from a single command from the command line,
        or it can perform multiple functions in interactive mode. It can operate
        on both <acronym>XML</acronym> and <acronym>SGML</acronym> files.
    </para>
</refsect1>

<refsect1 id="options">
    <title>OPTIONS</title>
    <para>
        &xmlcatalog; accepts the following options (in alphabetical order):
    </para>

    <variablelist>

        <varlistentry>
            <term>
                <option>--add
                 <replaceable>TYPE</replaceable>
                 <replaceable>ORIG</replaceable>
                 <replaceable>REPLACE</replaceable>
                </option>
            </term>
            <listitem>
                <para>
                    Add an entry to <filename>CATALOGFILE</filename>. <replaceable>TYPE</replaceable>
                    indicates the type of entry. Possible types are: <simplelist type="inline">
                        <member><parameter>public</parameter></member>
                        <member><parameter>system</parameter></member>
                        <member><parameter>uri</parameter></member>
                        <member><parameter>rewriteSystem</parameter></member>
                        <member><parameter>rewriteURI</parameter></member>
                        <member><parameter>delegatePublic</parameter></member>
                        <member><parameter>delegateSystem</parameter></member>
                        <member><parameter>delegateURI</parameter></member>
                        <member><parameter>nextCatalog</parameter></member>
                    </simplelist>. <replaceable>ORIG</replaceable> is the original
                    reference to be replaced, and <replaceable>REPLACE</replaceable>
                    is the <acronym>URI</acronym> of the replacement entity to be
                    used. The <option>--add</option> option will not overwrite
                    <filename>CATALOGFILE</filename>, outputting
                    to <filename class="devicefile">stdout</filename>, unless
                    <option>--noout</option> is used. The <option>--add</option> will
                    always take three parameters even if some of the <acronym>XML</acronym>
                    catalog constructs will have only a single argument.
                </para>
                <!--
                    FIXME - Is my list of possible types correct? Are SGML types the same?
                -->
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--add <replaceable>FILENAME</replaceable></option></term>
            <listitem>
                <para>
                    If the <option>--add</option> option is used following
                    the <option>--sgml</option> option, only a single argument,
                    a <replaceable>FILENAME</replaceable>, is used. This is used to add
                    the name of a catalog file to an <acronym>SGML</acronym> supercatalog,
                    a file that contains references to other included <acronym>SGML</acronym>
                    catalog files.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--convert</option></term>
            <listitem>
                <para>
                    Convert SGML catalog to XML.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--create</option></term>
            <listitem>
                <para>
                    Create a new <acronym>XML</acronym> catalog. Outputs
                    to <filename class="devicefile">stdout</filename>,
                    ignoring <replaceable>filename</replaceable> unless <option>--noout</option> is
                    used, in which case it creates a new catalog
                    file <replaceable>filename</replaceable>.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--del <replaceable>VALUE(S)</replaceable></option></term>
            <listitem>
                <para>
                    Remove entries from <replaceable>CATALOGFILE</replaceable>
                    matching <replaceable>VALUE(S)</replaceable>. The <option>--del</option>
                    option will not overwrite <replaceable>CATALOGFILE</replaceable>,
                    outputting to <filename class="devicefile">stdout</filename>,
                    unless <option>--noout</option> is used.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--noout</option></term>
            <listitem>
                <para>
                    Save output to the named file rather than outputting
                    to <filename class="devicefile">stdout</filename>.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--no-super-update</option></term>
            <listitem>
                <para>
                    Do not update the <acronym>SGML</acronym> super catalog.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--shell</option></term>
            <listitem>
                <para>
                    Run a shell allowing interactive queries on catalog
                    file <replaceable>CATALOGFILE</replaceable>. For the set of available
                    commands see <xref linkend="shell"/>.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>--sgml</option></term>
            <listitem>
                <para>
                    Uses <acronym>SGML</acronym> super catalogs for <option>--add</option>
                    and <option>--del</option> options.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>-v</option></term>
            <term><option>--verbose</option></term>
            <listitem>
                <para>Output debugging information.</para>
            </listitem>
        </varlistentry>

    </variablelist>

    <para>
        Invoking &xmlcatalog; non-interactively without a designated action
        (imposed with options like <option>--add</option>) will result in a lookup
        of the catalog entry for <replaceable>ENTITIES</replaceable> in the
        catalog denoted with <replaceable>CATALOGFILE</replaceable>. The
        corresponding entries will be output to the command line. This mode of
        operation, together with <option>--shell</option> mode and non-modifying
        (i.e. without <option>--noout</option>) direct actions, allows for
        a special shortcut of the void <replaceable>CATALOGFILE</replaceable>
        specification (possibly expressed as &quot;&quot; in the shell
        environment) appointing the default system catalog. That simplifies the
        handling when its exact location is irrelevant but the respective built-in
        still needs to be consulted.
    </para>
</refsect1>

<refsect1 id="shell">
    <title>SHELL COMMANDS</title>
    <para>
        Invoking &xmlcatalog; with
        the <option>--shell <replaceable>CATALOGFILE</replaceable></option> option opens
        a command line shell allowing interactive access to the catalog file
        identified by <replaceable>CATALOGFILE</replaceable>. Invoking the shell
        provides a command line prompt after which the following commands (described in
        alphabetical order) can be entered.
    </para>

    <variablelist>

        <varlistentry>
            <term>
                <option>add
                 <replaceable>TYPE</replaceable>
                 <replaceable>ORIG</replaceable>
                 <replaceable>REPLACE</replaceable>
                </option>
            </term>
            <listitem>
                <para>
                    Add an entry to the catalog file. <replaceable>TYPE</replaceable>
                    indicates the type of entry. Possible types are: <simplelist type="inline">
                        <member><parameter>public</parameter></member>
                        <member><parameter>system</parameter></member>
                        <member><parameter>uri</parameter></member>
                        <member><parameter>rewriteSystem</parameter></member>
                        <member><parameter>rewriteURI</parameter></member>
                        <member><parameter>delegatePublic</parameter></member>
                        <member><parameter>delegateSystem</parameter></member>
                        <member><parameter>delegateURI</parameter></member>
                        <member><parameter>nextCatalog</parameter></member>
                    </simplelist>. <replaceable>ORIG</replaceable> is the original
                    reference to be replaced, and <replaceable>REPLACE</replaceable>
                    is the <acronym>URI</acronym> of the replacement entity to be
                    used. The <option>--add</option> option will not overwrite
                    <filename>CATALOGFILE</filename>, outputting
                    to <filename class="devicefile">stdout</filename>, unless
                    <option>--noout</option> is used. The <option>--add</option> will
                    always take three parameters even if some of the <acronym>XML</acronym>
                    catalog constructs will have only a single argument.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>debug</option></term>
            <listitem>
                <para>
                    Print debugging statements showing the steps &xmlcatalog; is executing.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>del <replaceable>VALUE(S)</replaceable></option></term>
            <listitem>
                <para>
                    Remove the catalog entry corresponding to <replaceable>VALUE(S)</replaceable>.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>dump</option></term>
            <listitem>
                <para>Print the current catalog.</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>exit</option></term>
            <listitem>
                <para>Quit the shell.</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term>
            <listitem>
                <para>
                    Execute a Formal Public Identifier lookup of the catalog entry
                    for <replaceable>PUBLIC-ID</replaceable>. The corresponding entry will be
                    output to the command line.
                </para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>quiet</option></term>
            <listitem>
                <para>Stop printing debugging statements.</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term>
            <listitem>
                <para>
                    Execute a Formal Public Identifier lookup of the catalog entry
                    for <replaceable>SYSTEM-ID</replaceable>. The corresponding entry will be
                    output to the command line.
                </para>
            </listitem>
        </varlistentry>

    </variablelist>
</refsect1>

<refsect1 id="environment">
    <title>ENVIRONMENT</title>
    <variablelist>

        <varlistentry>
            <term><envar>XML_CATALOG_FILES</envar></term>
            <listitem>
                <para><acronym>XML</acronym> catalog behavior can be changed by redirecting
                    queries to the user's own set of catalogs. This can be done by setting
                    the <envar>XML_CATALOG_FILES</envar> environment variable to a space-separated
                    list of catalogs. Use percent-encoding to escape spaces or other characters.
                    An empty variable should deactivate loading the default <filename>/etc/xml/catalog</filename> catalog.
                </para>
            </listitem>
        </varlistentry>

    </variablelist>
</refsect1>

<refsect1 id="diagnostics">
    <title>DIAGNOSTICS</title>
    <para>
        &xmlcatalog; return codes provide information that can be used when
        calling it from scripts.
    </para>
    <variablelist>

        <varlistentry>
            <term><errorcode>0</errorcode></term>
            <listitem>
                <para>No error</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><errorcode>1</errorcode></term>
            <listitem>
                <para>Failed to remove an entry from the catalog</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><errorcode>2</errorcode></term>
            <listitem>
                <para>Failed to save to the catalog, check file permissions</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><errorcode>3</errorcode></term>
            <listitem>
                <para>Failed to add an entry to the catalog</para>
            </listitem>
        </varlistentry>

        <varlistentry>
            <term><errorcode>4</errorcode></term>
            <listitem>
                <para>Failed to look up an entry in the catalog</para>
            </listitem>
        </varlistentry>

    </variablelist>
</refsect1>

<refsect1 id="seealso">
    <title>SEE ALSO</title>
    <para><citerefentry>
            <refentrytitle>libxml</refentrytitle>
            <manvolnum>3</manvolnum>
        </citerefentry>
    </para>
    <para>
        More information can be found at
        <itemizedlist>
            <listitem>
                <para><citerefentry>
                        <refentrytitle>libxml</refentrytitle>
                        <manvolnum>3</manvolnum>
                    </citerefentry> web page <ulink url="https://gitlab.gnome.org/GNOME/libxml2"/>
                </para>
            </listitem>
            <listitem>
                <para><citerefentry>
                        <refentrytitle>libxml</refentrytitle>
                        <manvolnum>3</manvolnum>
                    </citerefentry> catalog support web page
                    at <ulink url="https://gitlab.gnome.org/GNOME/libxml2/-/wikis/Catalog-support"/>
                </para>
            </listitem>
            <listitem>
                <para>James Clark's <acronym>SGML</acronym> catalog
                    page <ulink url="http://www.jclark.com/sp/catalog.htm"/>
                </para>
            </listitem>
            <listitem>
                <para><acronym>OASIS</acronym> <acronym>XML</acronym> catalog specification
                    <ulink url="http://www.oasis-open.org/committees/entity/spec.html"/>
                </para>
            </listitem>
        </itemizedlist>
    </para>
</refsect1>

</refentry>