This is the beginnings of a Xerces.pm FAQ

Maintainer: Jason E. Stewart

Version: $Id$

A. General Info
===============
A.1 Where is the xerces-p-dev mailing list archive

  - Apache now has an EyeBrowse archive of both the xerces-p-dev and
    xerces-c-dev lists:
    
    http://nagoya.apache.org/eyebrowse/SummarizeList?listId=86

A.2 Where can I find documentation for Xerces.pm

  - Currently Xerces.pm has little perl-specific documentation, I'm
    sorry to say. Xerces-C has detailed API documentation that is
    automatically generated from its header files using Doxygen. These
    can be found at http://xml.apache.org/xerces-c/apiDocs/index.html
    For more information on using Xerces.pm, look at the examples in
    the samples/ directory, and the tests in the t/ directory, and
    read the section on perl-specific API issues in the
    README. Volunteers are welcome to help improve this flaw.

B. Building Xerces.pm
=====================
B.1 I get an undefined symbol error, __eh_alloc, when I compile
    Xerces.so on NetBSD.

  - This is because libgcc.a, which defines __eh_alloc, is not
    compiled PIC under NetBSD, and when it was statically linked into
    perl, the linker only included the symbols need by perl at link
    time. To solve this, perl needs to be recompiled, specifying the
    -whole-archive linker option for libgcc. For example:

    c++ -Wl,-export-dynamic -Wl,-whole-archive -lgcc -Wl,-no-whole-archive \
        -L/usr/pkg/lib -Wl,-E -Wl,-R/usr/pkg/lib -o perl perlmain.o        \   
        lib/auto/DynaLoader/DynaLoader.a  libperl.a `cat ext.libs`         \   
        -lm -lcrypt

B.2 I get iostream errors when I compile

  - Some gcc installations need -DHAS_BOOL to compile and others will
    fail if it is defined. Trying adding/removing -DHAS_BOOL from
    $CFLAGS in Makefile.PL.

C. Unicode Support
==================
C.1 Why do a bunch of tests fail in t/DOMDocument.t?

  - If they are 662..723, try setting your LC_CTYPE environment
    variable to something besides the default value of "C", such as:

    export LC_CTYPE=en_US

  - Otherwise, are you using Perl-5.6.0 or greater?

D. Serializing a DOM tree
=========================
D.1 Why does DOMWriter::writeToString() always output UTF-16 as the encoding?

  Short answer: don't use writeToString(). 

  Use a MemBufFormatTarget instead:

  my $dom = XML::Xerces::XercesDOMParser->new();
  eval{$dom->parse(XML::Xerces::MemBufInputSource->new($document))};
  XML::Xerces::error($@) if $@;
  my $doc = $dom->getDocument();

  my $impl = XML::Xerces::DOMImplementationRegistry::getDOMImplementation('LS');
  my $writer = $impl->createDOMWriter();
  my $target = XML::Xerces::MemBufFormatTarget->new();
  $writer->writeNode($target,$doc);