diff options
Diffstat (limited to 'doc/xmlcatalog_man.xml')
| -rw-r--r-- | doc/xmlcatalog_man.xml | 652 |
1 files changed, 400 insertions, 252 deletions
diff --git a/doc/xmlcatalog_man.xml b/doc/xmlcatalog_man.xml index b35002f..088cc23 100644 --- a/doc/xmlcatalog_man.xml +++ b/doc/xmlcatalog_man.xml @@ -3,297 +3,445 @@ 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> - <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> - - <releaseinfo>This is release 0.3 of the xmlcatalog Manual.</releaseinfo> - </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> - <arg>--shell</arg> - <arg>--create</arg> - <arg>--add <replaceable>type</replaceable> - <replaceable>orig</replaceable> <replaceable>replace</replaceable></arg> - <arg>--del <replaceable>values</replaceable></arg> - <arg>--noout</arg> - <arg>--verbose</arg> - </group> - <arg><option><replaceable>catalogfile</replaceable></option></arg> - <arg><option><replaceable>entities</replaceable></option></arg> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1 id="introduction"> - <title>Introduction</title> - <para> - <application>xmlcatalog</application> is a command line application - allowing users to monitor and manipulate <acronym>XML</acronym> and - <acronym>SGML</acronym> catalogs. It is included in - <application>libxml2</application>. - </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="cloptions"> - <title>Command Line Options</title> - <variablelist> - <varlistentry> - <term><option>--shell</option> <replaceable>filename</replaceable></term> + +<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> + <!-- date should be the date of the latest change or the release version --> + <date>2006-03-05</date> + <!-- 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>--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> + <para>More information can be found at + <itemizedlist> + <listitem> + <para><citerefentry> + <refentrytitle>libxml</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry> web page <ulink url="http://www.xmlsoft.org/"/> + </para> + </listitem> + <listitem> + <para><citerefentry> + <refentrytitle>libxml</refentrytitle> + <manvolnum>3</manvolnum> + </citerefentry> catalog support web page + at <ulink url="http://www.xmlsoft.org/catalog.html"/> + </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> + +<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> - <simpara> - Run a shell - allowing interactive queries on catalog file - <replaceable>filename</replaceable>. - </simpara> + <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>rewriteSystem</parameter></member> + <member><parameter>rewriteURI</parameter></member> + <member><parameter>delegatePublic</parameter></member> + <member><parameter>delegateSystem</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>--create</option> <replaceable>filename</replaceable></term> + </varlistentry> + + <varlistentry> + <term><option>--add <replaceable>FILENAME</replaceable></option></term> <listitem> - <simpara> - Create a new - <acronym>XML</acronym> catalog. Outputs to stdout, ignoring - <replaceable>filename</replaceable> unless <option>--noout</option> is - used, in which case it creates a new catalog file - <replaceable>filename</replaceable>. - </simpara> + <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> - <varlistentry> - <term><option>--add</option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable> <replaceable>filename</replaceable></term> + <varlistentry> + <term><option>--create</option></term> <listitem> - <simpara> - Add an entry to catalog file - <filename>filename</filename>. <replaceable>type</replaceable> - indicates the type of entry. Possible types are 'public', 'system', - 'rewriteSystem', 'rewriteURI', 'delegatePublic', 'delegateSystem', - and 'nextCatalog'. <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 - <replaceable>filename</replaceable>, outputting to stdout, 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. -<!-- -FIXME - Is my list of possible types correct? Are SGML types the same? ---> - </simpara> - <simpara> - 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. - </simpara> + <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</option> <replaceable>'values'</replaceable> <replaceable>filename</replaceable></term> + </varlistentry> + + <varlistentry> + <term><option>--del <replaceable>VALUE(S)</replaceable></option></term> <listitem> - <simpara> - Remove entries from the catalog file - <replaceable>filename</replaceable> matching - <replaceable>'values'</replaceable>. The <option>--del</option> option - will not overwrite <replaceable>filename</replaceable>, outputting to - stdout, unless <option>--noout</option> is used. - </simpara> + <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> + </varlistentry> + + <varlistentry> <term><option>--noout</option></term> <listitem> - <simpara> - Save output to the named file rather than - outputting to stdout. - </simpara> + <para> + Save output to the named file rather than outputting + to <filename class="devicefile">stdout</filename>. + </para> </listitem> - </varlistentry> - <varlistentry> - <term><option>--sgml</option></term> + </varlistentry> + + <varlistentry> + <term><option>--no-super-update</option></term> <listitem> - <simpara> - Uses SGML Super catalogs for --add and --del options - </simpara> + <para> + Do not update the <acronym>SGML</acronym> super catalog. + </para> </listitem> - </varlistentry> - <varlistentry> - <term><option>-v</option> or <option>--verbose</option></term> + </varlistentry> + + <varlistentry> + <term><option>--shell</option></term> <listitem> - <simpara> - output debugging - information. - </simpara> + <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> - </variablelist> - </refsect1> - - <refsect1 id="shell"> - <title>Shell Commands</title> - <para>Invoking <application>xmlcatalog</application> with the - <option>--shell</option> <replaceable>filename</replaceable> option opens - a command line shell allowing interactive access to the catalog file - identified by <replaceable>filename</replaceable>. Invoking the shell - provides a command line prompt after which commands can be entered. - </para> - - <variablelist> - <varlistentry> - <term><option>public</option> <replaceable>'PublicID'</replaceable></term> + </varlistentry> + + <varlistentry> + <term><option>--sgml</option></term> <listitem> - <simpara> - Execute a - public identifier lookup of the catalog entry for - <replaceable>'PublicID'</replaceable>. The corresponding entry will be - output to the command line. - </simpara> + <para> + Uses <acronym>SGML</acronym> super catalogs for <option>--add</option> + and <option>--del</option> options. + </para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>system</option> <replaceable>'SystemID'</replaceable></term> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> - <simpara> - Execute a - public identifier lookup of the catalog entry for - <replaceable>'SystemID'</replaceable>. The corresponding entry will be - output to the command line. - </simpara> + <para>Output debugging information.</para> </listitem> - </varlistentry> - <varlistentry> - <term><option>add </option> <replaceable>'type'</replaceable> <replaceable>'orig'</replaceable> <replaceable>'replace'</replaceable></term> + </varlistentry> + + </variablelist> +</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> - <simpara> - Add an entry to the catalog - file. <replaceable>type</replaceable> indicates the type of - entry. Possible types are 'public', 'system', 'rewriteSystem', - 'rewriteURI', 'delegatePublic', 'delegateSystem', and - 'nextCatalog'. <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. - </simpara> + <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>rewriteSystem</parameter></member> + <member><parameter>rewriteURI</parameter></member> + <member><parameter>delegatePublic</parameter></member> + <member><parameter>delegateSystem</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>del</option> <replaceable>'values'</replaceable></term> + </varlistentry> + + <varlistentry> + <term><option>debug</option></term> <listitem> - <simpara> - Remove the - catalog entry corresponding to <replaceable>'values'</replaceable>. - </simpara> + <para> + Print debugging statements showing the steps &xmlcatalog; is executing. + </para> </listitem> - </varlistentry> + </varlistentry> - <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> - <simpara> - Print the current catalog. - </simpara> + <para>Print the current catalog.</para> </listitem> - </varlistentry> + </varlistentry> - <varlistentry> - <term><option>debug</option></term> + <varlistentry> + <term><option>exit</option></term> <listitem> - <simpara> - Print debugging statements showing the steps - <application>xmlcatalog</application> is executing. - </simpara> + <para>Quit the shell.</para> </listitem> - </varlistentry> - - <varlistentry> + </varlistentry> + + <varlistentry> + <term><option>public <replaceable>PUBLIC-ID</replaceable></option></term> + <listitem> + <para> + Execute a 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> - <simpara> - Stop printing debugging statements. - </simpara> + <para>Stop printing debugging statements.</para> </listitem> - </varlistentry> - - <varlistentry> - <term><option>exit</option></term> + </varlistentry> + + <varlistentry> + <term><option>system <replaceable>SYSTEM-ID</replaceable></option></term> + <listitem> + <para> + Execute a 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> - <simpara> - Quit the shell. - </simpara> + <para> + 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 list + of catalogs. An empty one should deactivate loading the + default <filename>/etc/xml/catalog</filename> default catalog. + </para> </listitem> - </varlistentry> - </variablelist> - - </refsect1> - - <refsect1 id="return"> - <title>Return values</title> - <para><application>xmlcatalog</application>'s return codes provide - information that can be used when calling it from scripts.</para> - - <para>0: normal</para> - <para>1: Failed to remove an entry from the catalog</para> - <para>2: Failed to save to the catalog, check file permissions</para> - <para>3: Failed to add an entry to the catalog</para> - <para>4: Failed to lookup and entry in the catalog</para> - </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>References</title> - <para><ulink url="http://www.xmlsoft.org/">libxml web page</ulink></para> - - <para><ulink url="http://www.xmlsoft.org/catalog.html"><application>libxml</application> - catalog support web page</ulink></para> - - <para><ulink url="http://www.jclark.com/sp/catalog.htm">James Clark's - <acronym>SGML</acronym> catalog page</ulink></para> - - <para><ulink - url="http://www.oasis-open.org/committees/entity/spec.html"><acronym>OASIS</acronym> - <acronym>XML</acronym> catalog specification</ulink></para> + </varlistentry> + + </variablelist> </refsect1> +<refsect1 id="diagnostics"> + <title>DIAGNOSTICS</title> + <para> + &xmlcatalog;'s 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 lookup 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> +</refsect1> </refentry> |