<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "docbookV4.2/docbookx.dtd" []>
<refentry>
  <refmeta>
    <refentrytitle>pydtd2xsd</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>pydtd2xsd</refname>
    <refpurpose>convert XML Document Type Declarations to XML
      Schema</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>pydtd2xsd</command>
      <arg>--dtd-file <replaceable>file</replaceable></arg>
      <arg>--repr-file <replaceable>file</replaceable></arg>
      <arg>--use-repr-file</arg>
      <arg rep="repeat">--ns-uri <replaceable>prefix</replaceable>
	<replaceable>URI</replaceable></arg>
      <arg rep="repeat">--ns-schema-file <replaceable>prefix</replaceable>
	<replaceable>file</replaceable></arg>
      <arg>--no-ns-workaround</arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para><application>pydtd2xsd</application> converts XML Document
      Type Declarations into XML Schemata. It can handle
      DTDs that use complex entity substitutions,
      XML namespace prefixes for several namespaces, and are
      distributed over several files.</para>
  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
	<term>--dtd-file <replaceable>file</replaceable></term>
	<listitem>
	  <para>Read the DTD from
	    <replaceable>file</replaceable>. Note, however, that use
	    of the --use-repr-file or --repr-file options may supress
	    reading the DTD file.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--repr-file <replaceable>file</replaceable></term>
	<listitem>
	  <para>Read the compiled DTD from
	    <replaceable>file</replaceable>. Implies --use-repr-file.</para>
	  <warning>
	    <para>Since the compiled DTD is stored as Python code,
	      this means that <emphasis>any</emphasis> Python code
	      that somehow ended up in <replaceable>file</replaceable>
	      will be evaluated!</para>
	  </warning>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--use-repr-file</term>
	<listitem>
	  <para>Attempt to read the DTD from a precompiled DTD
	    representation file, or, if this file does not exist,
	    generate it. If --repr-file is not given the filename will
	    be determined by replacing the .dtd suffix of the DTD file
	    with .prp. This can save a great deal of time.</para>
	  <warning>
	    <para>Since the compiled DTD is stored as Python code,
	      this means that <emphasis>any</emphasis> Python code
	      that somehow ended up in the representation file
	      will be evaluated!</para>
	  </warning>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--ns-uri <replaceable>prefix</replaceable>
	  <replaceable>URI</replaceable></term>
	<listitem>
	  <para>Associate the namespace prefix
	    <replaceable>prefix</replaceable> with the namespace URI
	    <replaceable>URI</replaceable>. If
	    <replaceable>prefix</replaceable> is
	    <userinput>None</userinput> then the namespace URI will be
	    associated with elements that do not have a prefix. If
	    <replaceable>URI</replaceable> is
	    <userinput>None</userinput>, which is only permissible if
	    <replaceable>prefix</replaceable> is also
	    <userinput>None</userinput>, then elements without a
	    prefix will not be associated with a namespace.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--ns-schema-file <replaceable>prefix</replaceable>
	  <replaceable>file</replaceable></term>
	<listitem>
	  <para>Write the XML Schema file for the namespace with the
	    associate prefix <replaceable>prefix</replaceable> to
	    <replaceable>file.</replaceable>
	    If
	    <replaceable>prefix</replaceable> is
	    <userinput>None</userinput> then the XML Schema file for
	    elements with no prefix (which may or may not be
	    associated with a namespace, see --ns-uri) will be written
	    to <replaceable>file</replaceable>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--no-ns-workaround</term>
	<listitem>
	  <para>For DTDs that mix elements associated with a namespace
	  with elements not associated with a namespace, normally the
	    elements not associated with a namespace are imported by
	    the other XML Schemata by <computeroutput>&lt;xsd:import
	      schemaLocation='file'&gt;</computeroutput>. With this
	    option an additional
	    <computeroutput>namespace=''</computeroutput> attribute
	    will be generated which seems to violate the XML Schema
	    specification, but is necessary to make the schemata work
	    with certain programs, such as <productname>Syntext
	      Serna</productname>.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Usage</title>
    <para>In order to make schema files for a DTD that mixes
      namespaceless TEI with MathML, we could invoke pydtd2xsd
      thus: <userinput>pydtd2xsd --dtd-file math-tei.dtd --ns-uri None
	None --ns-uri math http://www.w3.org/1998/Math/MathML
	--ns-schema-file None math-tei.xsd --ns-schema-file math
	mathml.xsd</userinput></para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para>
      <author>
	<firstname>Oliver M.</firstname>
	<surname>Haynold</surname>
	<contrib>Original author</contrib>
      </author>
    </para>
  </refsect1>
  <refsect1>
    <title>Bugs</title>
    <para>Namespaces should be inferred from
      <symbol>xmlns:xxx</symbol> attribute declarations with fixed
      values in the DTD.</para>
    <para>There is no support for notations.</para>
    <para>There must be a 1:1 mapping of prefixes to namespaces across
      the DTD.</para>
  </refsect1>
  <refsect1>
    <title>Copyright</title>
    <para><application>pydtd2xsd</application> is copyright (c) 2004
      by Oliver M. Haynold.</para>    
    <para>This program is free software; you can redistribute it
      and/or modify it under the terms of the GNU General Public
      License as published by the Free Software Foundation; either
      version 2 of the License, or (at your option) any later
      version.</para>
    <para>This program is distributed in the hope that it will be
      useful, but WITHOUT ANY WARRANTY; without even the implied
      warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
      See the GNU General Public License for more details.</para>
    <para>You should have received a copy of the GNU General Public
      License along with this program; if not, write to the Free
      Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
      MA  02111-1307  USA</para>
  </refsect1>
</refentry>


