NAME

       DtdToHaskell - a XML DTD to Haskell translator

SYNOPSIS

       DtdToHaskell [ dtdfile [ outfile ]]

       Missing file arguments or dashes (-) indicate standard input or output respectively.

DESCRIPTION

       DtdToHaskell  is  a  tool for translating any valid XML DTD into equivalent Haskell types.
       This allows you to generate, edit, and transform  documents  as  normal  typed  values  in
       programs,  and  to  read  and  write  them  as  human-readable XML documents.  It uses the
       Text.XML.HaXml.XmlContent class as a framework for printing and parsing.

       DtdToHaskell reads and parses a DTD from dtdfile (which may be either just  a  DTD,  or  a
       full XML document containing an internal DTD).  It generates into outfile a Haskell module
       containing a collection of type definitions plus some class instance declarations for I/O.

       In order to use the  resulting  module,  you  need  to  import  it,  and  also  to  import
       Text.XML.HaXml.XmlContent.   To  read and write XML files as values of the declared types,
       use some of the convenience functions from XmlContent.

       You will need to study the automatically-generated type declarations  to  write  your  own
       code using them - but most things have pretty obvious parallels to the DTD structure.

LIMITATIONS

       The  generated  Haskell  contains  references to types like OneOf3 where there is a choice
       between n (in this case 3) different tags.  Currently,  the  module  Text.XML.HaXml.OneOfN
       defines  these  types  up to n=20.  If your DTD requires larger choices, then use the tool
       MkOneOf to generate the extra size or range of sizes you need.

       We mangle tag names and attribute names to ensure that they have the correct lexical  form
       in  Haskell,  but  this  means that (for instance) we can't distinguish Myname and myname,
       which are different names in XML but translate to overlapping types in Haskell (and  hence
       probably won't compile).

       Attribute  names  translate into named fields: but because Haskell doesn't allow different
       types to have the same named field, this means your XML document which uses the same  name
       for  similar  attributes  on  different  tags would crash and burn.  We have fixed this by
       incorporating the tagname into the named field in addition to  the  attribute  name,  e.g.
       tagAttr instead of just attr.  Uglier, but more portable.

       XML  namespaces.   Currently,  we  just  mangle the namespace identifier into any tag name
       which uses it.  Probably the right way to do it is to regard the namespace as  a  separate
       imported  module,  and hence translate the namespace prefix into a module qualifier.  Does
       this sound about right?  (It isn't implemented yet.)

       External subset.  Since HaXml release 1.00, we support the XML DTD external subset.   This
       means we can read and parse a whole bunch of files as part of the same DTD, and we respect
       INCLUDE and IGNORE conditional sections.  The sub-DTD files must be available locally - we
       don't go looking for them on the web.

       There  are  some fringe parts of the DTD we are not entirely sure about, such as Tokenised
       Types and Notation Types.  In particular, there is no validity checking of these  external
       references.  If you find a problem, mail us:
            Malcolm.Wallace@cs.york.ac.uk

COPYRIGHT

       The HaXml library and tools were written by and are copyright to
              Copyright © 1998 – 2006    Malcolm Wallace and Colin Runciman

       The library incorporates the module Text.ParserCombinators.HuttonMeijerWallace
              Copyright © 1996           Graham Hutton and Erik Meijer

       with modifications
              Copyright © 1998 – 2000    Malcolm Wallace

       and may also use or incorporate the module Text.PrettyPrint.HughesPJ
              Copyright © 1996 – 1997    John Hughes and Simon Peyton Jones

       The  HaXml  library  is  licensed under the terms of the GNU Lesser General Public Licence
       (LGPL), with the following special exception:

              As a relaxation of clause 6 of the LGPL, the copyright holders of this library give
              permission  to  use,  copy,  link,  modify, and distribute, binary-only object-code
              versions of an executable linked with the Library, without requiring the supply  of
              any  mechanism to modify or replace the Library and relink (clauses 6a, 6b, 6c, 6d,
              6e), provided that all the other terms of clause 6 are complied with.

       The HaXml tools Xtract, Validate, DtdToHaskell, and MkOneOf, are licensed under the  terms
       of the GNU General Public Licence (GPL).

       This  library  and  toolset 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 Licences for more details.

SEE ALSO

       MkOneOf(1), Validate(1)

AUTHOR

       This  contents  of  this  manual  page was copied from the HTML documentation and slightly
       edited by Arjan Oosting <arjan@debian.org> for the Debian  system  (but  may  be  used  by
       others).