******************************************************************************
Release Notes for PXP (Last updated:  20-Jul-2001)
******************************************************************************


==============================================================================
Linker problems
==============================================================================

------------------------------------------------------------------------------
Assert_failure ("pxp_lexers.ml", 1573, 1585)
------------------------------------------------------------------------------

This issue applies to: PXP 1.1

Problem description: 

"We just install the pxp parser and have trouble in using it. 
We always obtained an exception that we can not supress. 
Do you know if it's a problem of setting configuration options. 
 
#  let d = parse_dtd_entity default_config (from_file "DAG.xml");; 
                                              ^^^^^^^^^^^? 
Uncaught exception: Assert_failure ("pxp_lexers.ml", 1573, 1585)."



Explanation: You need to link a lexer to the executable. (Ok, the error message 
could be better; an Assert_failure is not very explanative.) Lexers are 
dynamically registered at runtime in the module Pxp_lexers, so you can link an 
executable that does not contain a lexer without producing a linker error.

Example how to link correctly:

-  Direct linking without findlib: 
   
   ocamlc -o my_exec ... pxp_engine.cma pxp_lex_iso88591.cma
             pxp_lex_link_iso88591.cmo
   
   Don't forget to add the .cmo file! It contains the registering code that 
   plugs the lexers from pxp_lex_iso88591.cma into the registry. It _must_ be a 
   .cmo file, otherwise the initialization call would be "garbage-collected" at 
   link-time. (.cmx file if ocamlopt is used.) 
   
-  Linking with findlib: 
   
   
   ocamlfind ocamlc -o my_exec ... -package "pxp_engine,pxp_lex_iso88591" -linkpkg
   
   
   
For the other lexers, the linker calls are similar.

The following combinations of lexers are reasonable:

-  pxp_lex_iso88591 alone
   
-  pxp_lex_utf8 alone
   
-  pxp_lex_iso88591 + pxp_lex_utf8
   
-  pxp_wlex alone
   
It is not reasonable not to have a lexer at all, even if PXP is only used to 
represent XML trees internally, and not as parser. There must be a lexer for 
the character set that is used for the internal representation of strings. For 
example, if config.encoding = `Enc_utf8 (see module Pxp_yacc for the config 
record), there must be a lexer for UTF-8 (i.e. pxp_lex_utf8 or pxp_wlex).