expat/doc reference.html,1.39,1.40

Update of /cvsroot/expat/expat/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv29395

Modified Files:
	reference.html 
Log Message:
Documented XML_SetExternalEntityRefHandlerArg(), including API
foolishness noted in SF bug #644344.
Closes SF bug #644344.


Index: reference.html
===================================================================
RCS file: /cvsroot/expat/expat/doc/reference.html,v
retrieving revision 1.39
retrieving revision 1.40
diff -u -d -r1.39 -r1.40
--- reference.html	16 Jan 2003 23:15:19 -0000	1.39
+++ reference.html	21 Jan 2003 05:00:51 -0000	1.40
@@ -74,6 +74,7 @@
       <li><a href="#XML_SetDefaultHandler">XML_SetDefaultHandler</a></li>
       <li><a href="#XML_SetDefaultHandlerExpand">XML_SetDefaultHandlerExpand</a></li>
       <li><a href="#XML_SetExternalEntityRefHandler">XML_SetExternalEntityRefHandler</a></li>
+      <li><a href="#XML_SetExternalEntityRefHandlerArg">XML_SetExternalEntityRefHandlerArg</a></li>
       <li><a href="#XML_SetSkippedEntityHandler">XML_SetSkippedEntityHandler</a></li>
       <li><a href="#XML_SetUnknownEncodingHandler">XML_SetUnknownEncodingHandler</a></li>
       <li><a href="#XML_SetStartNamespaceDeclHandler">XML_SetStartNamespaceDeclHandler</a></li>
@@ -1038,6 +1039,30 @@
 
 <p>Since this handler may be called recursively, it should not be saving
 information into global or static variables.</p>
+</div>
+
+<pre class="fcndec" id="XML_SetExternalEntityRefHandlerArg">
+XML_SetExternalEntityRefHandlerArg(XML_Parser p,
+                                   void *arg)
+</pre>
+<div class="fcndef">
+<p>Set the argument passed to the ExternalEntityRefHandler.  If
+<code>arg</code> is not NULL, it is the new value passed to the
+handler set using <code><a href="#XML_SetExternalEntityRefHandler"
+>XML_SetExternalEntityRefHandler</a></code>; if <code>arg</code> is
+NULL, the argument passed to the handler function will be the parser
+object itself.</p>
+
+<p><strong>Note:</strong>
+The type of <code>arg</code> and the type of the first argument to the
+ExternalEntityRefHandler do not match.  This function takes a
+<code>void *</code> to be passed to the handler, while the handler
+accepts an <code>XML_Parser</code>.  This is a historical accident,
+but will not be corrected before Expat 2.0 (at the earliest) to avoid
+causing compiler warnings for code that's known to work with this
+API.  It is the responsibility of the application code to know the
+actual type of the argument passed to the handler and to manage it
+properly.</p>
 </div>
 
 <div class="handler">