From 38c0f1a18bf55303496fef9a09f29290c1bc77da Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <borisk@apache.org>
Date: Mon, 22 Sep 2008 09:50:49 +0000
Subject: [PATCH] Clean up and change the documentation to correspond to the
state of the source code/build system.
git-svn-id: https://svn.apache.org/repos/asf/xerces/c/trunk@697763 13f79535-47bb-0310-9956-ffa450edef68
---
doc/apidocs.xml | 9 +-
doc/build-misc.xml | 278 -------------------
doc/build-other.xml | 535 ------------------------------------
doc/build-winunix.xml | 451 ------------------------------
doc/build.xml | 364 ++++++++++++++++++++++---
doc/createdoc.xml | 4 +-
doc/domcount.xml | 10 +-
doc/domprint.xml | 44 +--
doc/enumval.xml | 4 +-
doc/faq-build.xml | 360 ++----------------------
doc/faq-contributing.xml | 191 ++-----------
doc/faq-distrib.xml | 214 +++------------
doc/faq-other.xml | 131 +--------
doc/faq-parse.xml | 545 ++++++++-----------------------------
doc/install.xml | 44 ++-
doc/memparse.xml | 4 +-
doc/migration.xml | 100 +++++--
doc/migration_archive.xml | 53 ++--
doc/pparse.xml | 12 +-
doc/program-dom.xml | 34 +--
doc/program-others.xml | 501 +++++++++++-----------------------
doc/program-sax.xml | 27 +-
doc/program-sax2.xml | 27 +-
doc/program.xml | 31 ++-
doc/psviwriter.xml | 10 +-
doc/redirect.xml | 12 +-
doc/samples.xml | 61 ++---
doc/sax2count.xml | 12 +-
doc/sax2print.xml | 2 +-
doc/saxcount.xml | 8 +-
doc/saxprint.xml | 2 +-
doc/schema.xml | 116 ++++----
doc/scmprint.xml | 2 +-
doc/senumval.xml | 6 +-
doc/stdinparse.xml | 8 +-
doc/style/dtd/entities.ent | 9 +-
doc/xerces-c_book.xml | 4 +-
doc/xinclude.xml | 6 +-
38 files changed, 1018 insertions(+), 3213 deletions(-)
delete mode 100644 doc/build-misc.xml
delete mode 100644 doc/build-other.xml
delete mode 100644 doc/build-winunix.xml
diff --git a/doc/apidocs.xml b/doc/apidocs.xml
index 3f5841ae1..b8f010d2f 100644
--- a/doc/apidocs.xml
+++ b/doc/apidocs.xml
@@ -28,7 +28,7 @@
<p>&XercesCName; SAX is an implementation of the
<jump href="http://sax.sourceforge.net/">SAX 1.0/2.0</jump> specification.</p>
- <p>&XercesCName; DOM is an implementation of the</p>
+ <p>&XercesCName; DOM is an implementation of the following specifications:</p>
<ul>
<li><jump href="http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/">
DOM Level 1 Specification</jump>, a W3C Recommendation of October 1, 1998</li>
@@ -44,11 +44,12 @@
</ul>
<p>For a complete understanding of how the &XercesCName; APIs work,
- we recommend you to read these documents.</p>
+ we recommend that you read these specifications.</p>
- <p>See the <em><jump href="apiDocs-&XercesC3Series;/index.html">&XercesCName; API documentation</jump></em> for more details.</p>
+ <p>See the <em><jump href="apiDocs-&XercesC3Series;/index.html">&XercesCName; API Reference</jump></em>
+ for the detailed documentation of &XercesCName; interfaces.</p>
- <note>The API documentation is automatically generated using
+ <note>The API Reference is automatically generated using
<jump href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</jump>.</note>
</s2>
diff --git a/doc/build-misc.xml b/doc/build-misc.xml
deleted file mode 100644
index acf0398a1..000000000
--- a/doc/build-misc.xml
+++ /dev/null
@@ -1,278 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!--
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
--->
-
-<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-
-<s1 title="Other Build Instructions">
- <anchor name="ICUPerl"/>
- <s2 title="Building &XercesCName; with ICU">
- <p>&XercesCName; may be built in stand-alone mode using
- native encoding support and also using ICU where you get support for over 180
- different encodings and/or locale specific message support. ICU stands for
- International Components for Unicode and is an open source distribution from
- IBM. You can get ICU libraries from
- <jump href="http://icu-project.org/">ICU project site</jump>.</p>
-
- <note><em>Important:</em> Please remember that <em>ICU and
- &XercesCName; must be built with the same compiler</em>,
- preferably with the same version. You cannot for example,
- build ICU with a threaded version of the xlC compiler and
- build &XercesCName; with a non-threaded one.</note>
- <p/>
- <s3 title="Building on Windows">
- <p>There are two options to build &XercesCName; with ICU on Windows. One is to use the
- MSDEV GUI environment, and the other is to invoke the compiler from the
- command line.</p>
-
- <p>Using, the GUI environment, requires one to edit the project files.
- Here, we will describe only the second option. It involves using the
- perl script '<code>packageBinaries.pl</code>'.</p>
-
- <p><em>Prerequisites:</em></p>
- <ul>
- <li>Perl 5.004 or higher</li>
- <li>Cygwin tools or MKS Toolkit</li>
- <li>zip.exe</li>
- </ul>
-
- <p>Extract &XercesCName; source files from the .zip archive using WinZip, say
- in the root directory (an arbitrary drive x:). It should create a directory like
- '<code>x:\&XercesC3SrcInstallDir;</code>'.</p>
-
- <p>Extract the ICU files, using WinZip, in root directory of the disk
- where you have installed &XercesCName;, sources. After extraction, there
- should be a new directory '<code>x:\icu</code>' which contains all the ICU
- source files.</p>
-
- <p>Start a command prompt to get a new shell window. Make sure you have
- perl, cygwin tools (<code>uname</code>, <code>rm</code>,
- <code>cp</code>, ...), and <code>zip.exe</code> somewhere in the
- path. Next setup the environment for MSVC using
- '<code>VCVARS32.BAT</code>' or a similar file. Then at the prompt
- enter:</p>
-
-<source>
-set ICUROOT=x:\icu
-cd x:\&XercesC3SrcInstallDir;\scripts
-</source>
-
- <p>To build with ICU, either specify using ICU transcoding service,</p>
-
-<source>
-perl packageBinaries.pl -s x:\&XercesC3SrcInstallDir; -o x:\temp\&XercesC3InstallDir;-win32 -t icu
-</source>
-
- <p> or specify using ICU message loader service</p>
-
-<source>
-perl packageBinaries.pl -s x:\&XercesC3SrcInstallDir; -o x:\temp\&XercesC3InstallDir;-win32 -m icu
-</source>
-
- <p>(Match the source directory to your system; the target directory can be
- anything you want.)</p>
-
- <p>If everything is setup right and works right, then you should see a
- binary drop created in the target directory specified above. This script
- will build both ICU and &XercesCName;, and copy the files (relevant to the binary
- drop) to the target directory.</p>
-
- <p>For a description of options available, you can enter:</p>
-<source>perl packageBinaries.pl</source>
- </s3>
- <s3 title="Building on UNIX">
- <p>Extract &XercesCName; source files into, say, the home directory ($HOME).
- It should create a directory like '<code>$HOME/&XercesC3SrcInstallDir;</code>'.</p>
-
- <p>Extract the ICU files into the same directory
- where you have installed &XercesCName; sources. After extraction, there
- should be a new directory '<code>$HOME/icu</code>' which contains all the ICU
- source files.</p>
-
- <p>Build the ICU according to the<jump href="http://icu-project.org/">
- ICU Build instruction in ICU Readme</jump>. Then have its dll, <code>libicuuc*</code>
- and <code>libicudt*</code> available from your library search path.</p>
-
- <p>Then build the &XercesCName; with ICU. This is similar to building a standalone
- &XercesCName; library as instructed in <jump href="build-winunix-&XercesC3Series;.html#UNIX">
- "Building &XercesCName; on UNIX platforms"</jump>; except that you have to specify
- the option <code>'--with-icu=$HOME/icu'</code> together with
- the transcoder option <code>'--enable-transcoder-icu'</code> and/or the message loader option
- <code>'--enable-msgloader-icu'</code>. For example:</p>
- <source>./configure --with-icu=$HOME/icu --enable-msgloader-inmemory --enable-netaccessor-socket --enable-transcoder-icu</source>
-
- <p>Or instead of building the ICU and &XercesCName; manually in two steps,
- you can use the bundled perl script '<code>packageBinaries.pl</code>' which
- will build both of them in one step. For example:</p>
-<source>
-export ICUROOT=$HOME/icu
-cd $HOME/&XercesC3SrcInstallDir;/scripts
-</source>
-
- <p>To build with ICU, either specify using ICU transcoding service,</p>
-
-<source>
-perl packageBinaries.pl -s $HOME/&XercesC3SrcInstallDir; -o $HOME/temp/&XercesC3InstallDir;-aix -t icu
-</source>
-
- <p> or specify using ICU message loader service</p>
-
-<source>
-perl packageBinaries.pl -s $HOME/&XercesC3SrcInstallDir; -o $HOME/temp/&XercesC3InstallDir;-aix -m icu
-</source>
-
- <p>If the parser is built with icu message loader (as mentioned above), or message
- catalog loader, you need an environment variable, XERCESC_NLS_HOME to point to
- the directory, $XERCESCROOT/msg, where the message files reside.
- </p>
-
- </s3>
- </s2>
-
- <anchor name="RPMLinux"/>
- <s2 title="Building &XercesCName; using RPM on Linux">
- <p>&XercesCName; may be built from the distributed source archive directly on Linux
- using RPM. For example: </p>
-<source>
-rpm -ta &XercesC3SrcInstallDir;.tar.gz (rpm 4.0 and older)
-or
-rpmbuild -ta &XercesC3SrcInstallDir;.tar.gz (rpm 4.1 and later; ships with RedHat 8)
-</source>
- <p>The &XercesCName; RPM specification can be found in
- <br/><code>&XercesC3SrcInstallDir;/xerces-c.spec</code>.</p>
- <p>Please refer to the <jump href="http://www.rpm.org/RPM-HOWTO">RPM-HOWTO</jump>,
- for more RPM related information.</p>
- </s2>
-
- <anchor name="UserDoc"/>
- <s2 title="Building User Documentation">
- <p>The user documentation (this very page that you are reading
- on the browser right now), was generated using an XML
- application called StyleBook. This application makes use of
- Xerces-J and Xalan to create the HTML file from the XML source
- files. The XML source files for the documentation are part of
- the &XercesCName; module. These files reside in the
- <code>doc</code> directory.</p>
-
- <p><em>Pre-requisites for building the user documentation are:</em></p>
-
- <ul>
- <li>JDK 1.2.2 (or later).</li>
- <li>Xerces-J 1.0.1 (provided by &XercesC3ToolsInstallDir;)</li>
- <li>Xalan-J 0.19.2 (provided by &XercesC3ToolsInstallDir;)</li>
- <li>Stylebook 1.0-b2 (provided by &XercesC3ToolsInstallDir;)</li>
- </ul>
-
- <p>Before proceeding, copy the contents of the &XercesC3ToolsInstallDir;
- distribution into your <code>$XERCESCROOT</code>. Then invoke
- a terminal or a command window and setup PATH to include the
- JDK 1.2.2 bin directory. Next, cd to the <code>$XERCESCROOT/tools</code>
- directory, and enter:</p>
-
-<source>
-createdocs.bat (Windows)
-./createdocs.sh (UNIX)
-</source>
-
- <p>This should generate the .html files in the 'doc/html' directory.</p>
-
- <p>To regenerate the API documentation, you need to have at least
- <jump href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</jump>
- installed on your system.</p>
-
- <p>If you want the API documentation to
- contain dependency graphs, you also need to have <jump
- href="http://www.research.att.com/sw/tools/graphviz/">GraphViz</jump> installed on
- your system.</p>
-
- <p>If you do not have GraphViz, or do not want to use it, you
- have to edit file <code>$XERCESCROOT/doc/Doxyfile</code> and change <code>HAVE_DOT =
- YES</code> into <code>HAVE_DOT = NO</code>.</p>
-
- <p>To actually regenerate the API documentation, go to directory
- <code>$XERCESCROOT/doc/</code> and start Doxygen. The result can be
- found in directory <code>$XERCESCROOT/doc/html/apiDocs</code>.</p>
- </s2>
-
-
- <anchor name="PortInfo"/>
- <s2 title="I wish to port &XercesCProjectName; to my favourite platform. Do you have any suggestions?">
- <p>All platform dependent code in &XercesCProjectName; has been
- isolated to a couple of files, which should ease the porting
- effort. Please refer to <jump href="program-others-&XercesC3Series;.html#PortingGuidelines">Porting
- Guidelines</jump> for further details.</p>
- </s2>
-
-
- <anchor name="XMLChInfo"/>
- <s2 title="What should I define XMLCh to be?">
- <p>XMLCh should be defined to be a type suitable for holding a
- utf-16 encoded (16 bit) value, usually an <code>unsigned short</code>. </p>
-
- <p>All XML data is handled within &XercesCName; as strings of
- XMLCh characters. Regardless of the size of the
- type chosen, the data stored in variables of type XMLCh
- will always be utf-16 encoded values. </p>
-
-
-
- <p>Unlike XMLCh, the encoding
- of wchar_t is platform dependent. Sometimes it is utf-16
- (AIX, Windows), sometimes ucs-4 (Solaris,
- Linux), sometimes it is not based on Unicode at all
- (HP/UX, AS/400, system 390). </p>
-
- <p>Some earlier releases of &XercesCName; defined XMLCh to be the
- same type as wchar_t on most platforms, with the goal of making
- it possible to pass XMLCh strings to library or system functions
- that were expecting wchar_t parameters. This approach has
- been abandoned because of</p>
-
- <ul>
- <li>
- Portability problems with any code that assumes that
- the types of XMLCh and wchar_t are compatible
- </li>
-
- <li>Excessive memory usage, especially in the DOM, on
- platforms with 32 bit wchar_t.
- </li>
-
- <li>utf-16 encoded XMLCh is not always compatible with
- ucs-4 encoded wchar_t on Solaris and Linux. The
- problem occurs with Unicode characters with values
- greater than 64k; in ucs-4 the value is stored as
- a single 32 bit quantity. With utf-16, the value
- will be stored as a "surrogate pair" of two 16 bit
- values. Even with XMLCh equated to wchar_t, xerces will
- still create the utf-16 encoded surrogate pairs, which
- are illegal in ucs-4 encoded wchar_t strings.
- </li>
- </ul>
- </s2>
-
- <anchor name="HelpInfo"/>
- <s2 title="Where can I look for more help?">
- <p>If you have read this page, followed the instructions, and
- still cannot resolve your problem(s), there is more help. You
- can find out if others have
- solved this same problem before you, by checking the
- <jump href="&MailURI;">&XercesCName; mailing list archives</jump> and
- <jump href="&BugURI;">&XercesCName; bug database</jump>.</p>
- </s2>
-
-</s1>
diff --git a/doc/build-other.xml b/doc/build-other.xml
deleted file mode 100644
index ad5e3b122..000000000
--- a/doc/build-other.xml
+++ /dev/null
@@ -1,535 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!--
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
--->
-
-<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-
-<s1 title="Building on Other Platforms">
- <anchor name="iSeries"/>
- <s2 title="Building &XercesCName; on iSeries (AS/400)">
- <p>The following addresses the requirements and build of
- &XercesCName; natively on the iSeries.
- </p>
- <s3 title="Building &XercesCName; library">
- <p><em>Requirements:</em></p>
-
- <ul>
- <li>OS/400 <code>QSHELL</code> interpreter installed (install base option 30, operating system)</li>
- <li>OS/400 - Portable App Solutions Environment (PASE) installed (install base option 33, operating system)</li>
- <li>iSeries Tools for Developers, PRPQ 5799-PTL (these are the gnu utilities)</li>
- <li>For v5: WebSphere Development ToolsSet, 5722-WDS ( installed option 52, Compiler - ILE C++)</li>
- </ul>
-
- <p><em>Recommendation:</em></p>
-
- <ul>
- <li>There is one option when building the XML4C parser on iSeries.
- For code page translation, you can use the iSeries
- native <code>Iconv400</code> support or <code>icu</code> as the transcoder plug in. If you choose ICU, follow the instructions
- to build the ICU service program with the ICU download. Those instructions
- are not included here. We recommend the use of <code>Iconv400</code>.</li>
- </ul>
-
- <p><em>Setup Instructions:</em></p>
-
- <ul>
- <li>Make sure that you have the requirements installed on your iSeries.
- We highly recommend that you read the write up that accompanies the
- iSeries Tools for Developers PRPQ. There are install instructions as well as
- information about how modules, programs and service programs can be
- created in Unix-like fashion using gnu utilities. Note that symbolic
- links are use in the file system to point to actual iSeries <code>*module</code>,
- <code>*pgm</code> and <code>*srvpgm</code> objects in libraries.</li>
-
- <li>Download the source zip file (NT version) directly to an iSeries IFS directory
- after creating a directory (eg. /XML4Cxxx) and then extract
- the source using a mapped drive. To do this, from Windows Explorer,
- select Tools -> Map Network Drive. Then select an available drive (e.g. F:) and
- specify an iSeries system you want to extract the zip file to
- (e.g. \\<your iSeries name>\root). Click on Finish. Then find the .zip file
- and right click on it and select Extract To ...
- Then select the files you want to extract to the iSeries system.</li>
-
- <li>Create iSeries target library. This library will be the target
- for the resulting modules and &XercesCName; service program. You will
- specify this library on the OUTPUTDIR environment variable
- in step 4.</li>
-
- <li>Set up the following environment variables in your build process
- (use <code>ADDENVVAR</code> or <code>WRKENVVAR CL</code> commands):</li>
- </ul>
-<source>
-XERCESCROOT - <the full path up to the &XercesCName; src directory, but not including 'src'>
-MAKE - '/qibm/proddata/developertools/qsh/bin/gmake'
-OUTPUTDIR - <identifies target iSeries library for *module, *pgm and *srvpgm objects>
-PATH - '/usr/bin:/qibm/proddata/developertools/qsh/bin'
-ICUROOT - (if using ICU) <the path of your ICU installation>
-</source>
-
- <ul>
- <li>For v4r5m0 systems, add QCXXN, to your build process library list.
- This results in the resolution of CRTCPPMOD used by the icc compiler.</li>
- </ul>
-
- <p>You may want to put the environment variables and library list
- setup instructions in a <code>CL</code> program so you will not forget these steps
- during your build.</p>
-
- <p><em>Configure</em></p>
-
- <p>To configure the make files for an iSeries build do the following under Qsh:</p>
-<source>qsh:
-cd <full path to &XercesCName;>/src/xercesc
-edit runConfigure and comment out the line:
- getoptErr=`getopt p:c:x:dm:n:t:r:b:l:z:P:C:h $*`
-runConfigure -p os400 -x icc -c icc -m inmem -t Iconv400 -r none</source>
-
- <p>Troubleshooting:</p>
-<source>error: configure: error: installation or configuration problem:
-C compiler cannot create executables.</source>
-
- <p>If during runConfigure you see the above error message, it
- can mean one of a few things. Either QCXXN is not on your library
- list <em>OR</em> the <code>runConfigure</code> cannot create the temporary
- modules (<code>CONFTest1</code>, etc) it uses to test out the compiler
- options or <code>PASE</code> is not installed. The second reason happens because the test modules already exist
- from a previous run of <code>runConfigure</code>. To correct the problem,
- do the following:</p>
-<source>CL:
-DLTMOD <OUTPUTDIR library>/CONFT* and
-DLTPGM <OUTPUTDIR library>/CONFT*</source>
-
- <p><em>Build</em></p>
- <p>If runConfigure runs fine then do the following under Qsh to actually build the modules:</p>
-<source>qsh:
-cd <full path to &XercesCName;>/src/xercesc
-gmake</source>
-
- <p>The above gmake should result in a service program being created
- in your specified library and a symbolic link to that service program
- placed in <path to &XercesCName;/lib>. It is highly possible that the
- service program will not create however due to number of modules and path names,
- see trouble shooting for the workaround.</p>
-
- <p>After the service program has successfully been created and a link established,
- you can either bind your XML application programs directly to the parser's service program
- via the <code>BNDSRVPGM</code> option on the <code>CRTPGM</code> or
- <code>CRTSRVPGM</code> command or you can specify a binding directory
- on your <code>icc</code> command. To specify an archive file to bind to,
- use the <code>-L, -l</code> binding options on icc. An archive file
- on iSeries is a binding directory. To create an archive file, use
- <code>qar</code> command. (see the iSeries Tools for Developers write up).
- </p>
-
- <p>After building the Xerces-C service program, create a binding directory
- by doing the following (note, this binding directory is used when building
- the samples. Also, note that the .a file below can have a different
- name based on the parser version (using apache xerces versioning)):</p>
-<source>qsh:
-cd <full path to &XercesCName;>/lib
-qar -cuv &XercesC3UnixLib;&XercesC3UnixSoName;.so *.o
-will results in
-command = CRTBNDDIR BNDDIR(yourlib/libxercesc) TEXT('/yourlib/&XercesCName;/lib/&XercesC3UnixLib;&XercesC3UnixSoName;.so')
-command = ADDBNDDIRE BNDDIR(yourlib/libxercesc) OBJ((yourlib/LIBXERCESC *SRVPGM) )</source>
-
-
- <p><em>Troubleshooting gmake problem:</em></p>
- <p>Due to the number of modules (the .o symbolic links) that make up the
- service program and the path to get to those modules, the qshell ld request
- to create the service program will likely fail because the request is too large,
- you may get a message like the following at the end of the gmake request:</p>
-<source>
-FAILURE: spawnp() with errno = 3491
-GMAKE: vfork: Argument list too long.
-</source>
-
- <p>If this is the case, you can manually create the service program by doing the following:</p>
-
-<source>CL:
-CRTSRVPGM (<OUTPUTDIR-library>/libxercesc) MODULE(<OUTPUTDIR-library>/*ALL) EXPORT(*ALL) TEXT('XML4C parser version xxx')
-OPTION(*DUPPROC *DUPVAR *NOWARN) AUT(*USE)
-</source>
-
- <p>Note that if you manually create the service program you want to make sure that
- you do not include any CONFT* modules or samples modules in the OUTPUTDIR library.
- After the service program is manually created you can add a symbolic link to the
- service program into the appropriate /lib directory by qsh:</p>
-
-<source>
-qsh:
-cd <full path to &XercesCName;>/lib
-ln -s /qsys.lib/<outputdir>.lib/libxercesc.srvpgm &XercesC3UnixLib;&XercesC3UnixSoName;.so
-qar -cuv &XercesC3UnixLib;&XercesC3UnixSoName;.so *.o
-</source>
-
- <p>If you are on a v4 system using the ILE C++ PRPQ compiler (which is referred
- to as the 'old' compiler) you will get compiler errors requiring a few manual changes
- to the source:</p>
-
- <ul>
- <li>src/xercesc/dom/impl/DOMDocumentImpl.cpp</li>
- <li>src/xercesc/dom/impl/DOMDocumentImpl.hpp</li>
- <li>src/xercesc/dom/deprecated/DocumentImpl.cpp</li>
- <li>src/xercesc/dom/deprecated/DocumentImpl.hpp</li>
- <li>src/xercesc/validators/common/ContentSpecNode.hpp</li>
- </ul>
-
- <p>Update the following routines in src/xercesc/dom/deprecated/DocumentImpl.cpp as follows:</p>
-<source>
- void DocumentImpl::setUserData(NodeImpl* n, void* data)
- {
- if (!userData && data)
- #ifdef __OS400__
- userData = new RefHashTableOf<char>(29, false, new HashPtr());
- #else
- userData = new RefHashTableOf<void>(29, false, new HashPtr());
- #endif
- if (!data && userData)
- userData->removeKey((void*)n);
- else
- #ifdef __OS400__
- userData->put((void*)n,(char*)data);
- #else
- userData->put((void*)n,data);
- #endif
- }
-
- void* DocumentImpl::getUserData(NodeImpl* n)
- {
- if (userData)
- #ifdef __OS400__
- return (void*)userData->get((void*)n);
- #else
- return userData->get((void*)n);
- #endif
- else
- return null;
- }
-</source>
-
- <p>To update src/xercesc/dom/deprecated/DoumentImpl.hpp as follows:</p>
-
-<source>
- #ifdef __OS400__
- RefHashTableOf<char> *userData;
- #else
-
- RefHashTableOf<void> *userData;
- #endif
-</source>
-
- <p>Update the following routines in src/xercesc/dom/impl/DOMDocumentImpl.cpp as follows:</p>
-<source>
- void DOMDocumentImpl::setUserData(DOMNode* n, void* data)
- {
- if (!fUserData && data)
- #ifdef __OS400__
- fUserData = new (this) RefHashTableOf<char>(29, false, new (this) HashPtr());
- #else
- fUserData = new (this) RefHashTableOf<void>(29, false, new (this) HashPtr());
- #endif
-
- if (!data && fUserData)
- fUserData->removeKey((void*)n);
- else
- #ifdef __OS400__
- fUserData->put((void*)n,(char*)data);
- #else
- fUserData->put((void*)n,data);
- #endif
- }
-
- void* DOMDocumentImpl::getUserData(const DOMNode* n) const
- {
- if (fUserData)
- #ifdef __OS400__
- return (void*) fUserData->get((void*)n);
- #else
- return fUserData->get((void*)n);
- #endif
-
- else
- return 0;
- }
-</source>
-
- <p>To update src/xercesc/dom/impl/DOMDocumentImpl.hpp:</p>
-<source>
- #ifdef __OS400__
- RefHashTableOf<char> *fUserData;
- #else
- RefHashTableOf<void> *fUserData;
- #endif
-</source>
- <p>Update validators/common/ContentSpecNode.hpp removing the following:</p>
-<source>
- #ifndef __OS400__
- inline
- #endif
- ContentSpecNode::~ContentSpecNode()
-</source>
-
- <p>To build for transcoder ICU:</p>
- <ol>
- <li>Make sure you have an <code>ICUROOT</code> path set up so that you can
- find the ICU header files (usually <code>/usr/local</code>)</li>
- <li>Make sure you have created a binding directory (symbolic link)
- in the file system so that you can bind the &XercesCName; service program
- to the ICU service program and specify that on the <code>EXTRA_LINK_OPTIONS</code>
- in <code>src/xercesc/Makefile.incl</code> (usually the default is a link
- in <code>/usr/local/lib</code>).</li>
- </ol>
-
- </s3>
-
- <s3 title="Building Samples on iSeries">
-
- <p>Note that the samples will create programs bind to the BND directory object
- created by qar referenced above.</p>
-<source>qsh
-cd <full path to &XercesCName;>/samples
-runConfigure -p os400 -x icc -c icc
-gmake </source>
-
- </s3>
- </s2>
-
- <anchor name="Mac"/>
- <s2 title="Building &XercesCName; on Macintosh">
- <p>The &XercesCName; Mac port has the key following attributes:
- </p>
-
- <ol>
- <li>Built atop CoreServices APIs and a limited number of Carbon APIs;
- supports builds for both Mac OS Classic, Carbon, and Mac OS X systems.
- </li>
-
- <li>Has a Mac OS native transcoder that utilizes the built-in Mac OS Unicode
- converter [MacOSUnicodeConverter].
- </li>
-
- <li>Has two Mac OS native netaccessor classes. The first is based on Carbon and
- classic supported URLAccess and may be used in the broadest variety of
- configurations [MacOSURLAccess]. The second [MacOSURLAccessCF] is based on
- CFURLAccess, which requires either Carbon or Mac OS X CoreServices.framework.
- This second NetAccessor is useful in Mac OS X configurations where reliance on
- the full Carbon.framework would prohibit execution of the Xerces code in a
- remote context that has no access to the GUI.
- </li>
-
- <li>Supports builds from Metroworks CodeWarrior, Apple Xcode,
- and Mac OS X shell. Projects for Apple Project Builder are still included,
- but may not be up to date (you may need to revise the projects to accomodate
- recent file additions, deletions, or other changes in &XercesCName;).
- </li>
- </ol>
-
- <s3 title="Using &XercesCName; with CodeWarrior">
-
- <p><em>&XercesCName; and CodeWarrior:</em>
- </p>
-
- <p>&XercesCName; may be built with CodeWarrior under Mac OS Classic or Mac OS X. Since
- the &XercesCName; code contains some files with very long names, and earlier versions
- of Mac OS, as well as earlier versions of CodeWarrior, did not support file names
- longer than 32 characters, CodeWarrior 8.0 is required. If you are building &XercesCName;
- on a Mac OS 9 system, be extremely careful in how to unpack and/or transfer the &XercesCName;
- files to that system, to ensure that their file names are not truncated in the process.
- </p>
-
- <p><em>Installing &XercesCName; for use with CodeWarrior:</em>
- </p>
-
- <p>Note: versions of CodeWarrior prior to 8.0 did not support HFS+ long file names,
- and thus required special steps to alter the file names prior to use. This restriction
- has been removed for CodeWarrior 8.0, and the projects now directly reference the unaltered
- source tree. The project files in this release require CodeWarrior v8.0 or higher.
- </p>
-
- <p>It is extemely important to ensure that you retrieve and unpack the sources
- with a tool that does not truncate file names. The command line gnutar utility on Mac
- OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as
- they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X.
- The command line tool tar will truncate path names that get too long; gnutar should be
- used instead. Failure to heed these warnings will result in broken projects.
- </p>
-
- <p><em>Building &XercesCName; with CodeWarrior:</em>
- </p>
-
- <ul>
- <li>Run CodeWarrior (requires CodeWarrior 8.0 with support for long file names).
- </li>
-
- <li>Import the project projects/MacOS/CodeWarrior/XercesLib/XercesLib.mcp.xml,
- saving it back out to the same directory as XercesLib.mcp.
- </li>
-
- <li>This project contains five build targets that build all combinations of
- classic, carbon, debug, and release versions, with an all target that
- builds all of these. Build any or all of these.
- </li>
- </ul>
-
- <p><em>Building &XercesCName; Samples with CodeWarrior:</em>
- </p>
-
- <p>A CodeWarrior project is included that builds the DOMPrint sample. This may
- be used as an example from which to build additional sample projects. Please
- read the following important notes:
- </p>
-
- <ul>
- <li>Once again, it is required that you import the .xml version of the project
- file, and save it back out.
- </li>
-
- <li>The &XercesCName; sample programs are written to assume a command line interface.
- To avoid making Macintosh-specific changes to these command line programs,
- we have opted to instead require that you make a small extension to your
- CodeWarrior runtime that supports such command line programs. Please read
- and follow the usage notes in XercesSampleSupport/XercesSampleStartupFragment.c.
- </li>
- </ul>
-
- </s3>
-
- <s3 title="Building &XercesCName; with Xcode">
-
- <p>Projects are included to build the &XercesCName; library and DOMPrint sample under
- Apple's Xcode for Mac OS X. The following notes apply:
- </p>
-
- <ul>
- <li>Be sure to heed warnings under "special instructions" below regarding which
- tools must be used to unpack archives: gnutar is your friend.
- </li>
-
- <li>The Xcode project builds XercesLib as the framework
- Xerces.framework. This framework, however, does not currently include a
- correct set of public headers. Any referencing code must have an include
- path directive that points into the &XercesCName; src directory.
- </li>
-
- <li>The DOMPrint project illustrates one such usage of the Xerces.framework.
- </li>
- </ul>
-
- </s3>
-
- <s3 title="Building &XercesCName; from the Mac OS X command line">
-
- <p>Support for Mac OS X command line builds is now included in the standard
- "unix" &XercesCName; build infrastructure.
- </p>
-
- <ul>
- <li>In general, the Mac OS X command line build follows the generic unix
- build instructions. You need to set your XERCESCROOT environment variable
- (the full path up to the Xerces-C++ src directory, but not including 'src'),
- <code>./runConfigure</code>, and <code>make</code>. Be sure to heed warnings
- under "special instructions" below regarding which tools must be used to unpack
- archives: gnutar is your friend.
- </li>
- </ul>
-
-<source>export XERCESCROOT="<xerces-c-directory>"
-cd src/xercesc
-./runConfigure -p macosx -n native -t native
-make</source>
-
- <ul>
- <li>Similar instructions apply to build the samples and tests, though the
- <code>-n</code> and <code>-t</code> flags are not used in these cases:
- </li>
- </ul>
-
-<source>cd samples
-./runConfigure -p macosx
-make</source>
-
- </s3>
-
- <s3 title="Special usage information for &XercesCName; on the Macintosh">
-
- <p><em>Unpacking the tar archive</em></p>
-
- <p>It is extemely important to ensure that you retrieve and unpack the sources
- with a tool that does not truncate file names. The command line gnutar utility on Mac
- OS X will do the right thing; older versions of StuffIt truncate names to 31 characters as
- they unpack tar archives, though versions >= 7.0.1 seem to work, at least on Mac OS X.
- The command line tool tar will truncate path names that get too long; gnutar should be
- used instead. Failure to heed these warnings will result in broken projects.
- </p>
-
- <p><em>File Path Specification</em></p>
-
- <p>Apart from the build instructions, above, the most important note
- about use of &XercesCName; on the Macintosh is that &XercesCName; expects
- all filename paths to be specified in unix syntax. If running natively
- under a Mac OS X system, this path will be the standard posix path as
- expected by the shell. The easiest means of creating and interpreting these
- paths will be through the routines <code>XMLCreateFullPathFromFSRef</code>
- and <code>XMLParsePathToFSRef</code> as declared in the file
- <code>MacOSPlatformUtils.hpp</code>. <code>FSSpec</code> variants of these
- routines are also supplied.
- </p>
-
- <p><em>Mac OS Version Compatibility</em></p>
-
- <p>&XercesCName; requires that several key components of the Mac OS
- be relatively up to date. It should be readily compatible with any system
- above Mac OS 9.0. Compatibility with earlier systems may perhaps be achieved
- if you can install appropriate components.
- </p>
-
- <p>Required components are:
- </p>
-
- <ul>
- <li>Unicode Converter and Text Encoding Converter. These provide the base
- transcoding service used to support &XercesCName; transcoding requirements.
- </li>
-
- </ul>
-
- <p>Optional components are:
- </p>
-
- <ul>
- <li>URLAccess. Provides NetAccessor support to &XercesCName; for use in
- fetching network referenced entities. If URLAccess is not installed, any
- such references will fail; the absence of URLAccess, however, will not
- in itself prevent &XercesCName; from running. If &XercesCName; is
- configured to use MacOSURLAccessCF, then URLAccess (and thus Carbon)
- is not required, but CoreServices.framework is required for Mac OS X.
- </li>
-
- <li>Multiprocessing library. Provides mutual exclusion support. Once again,
- the routines will back down gracefully if Multiprocessing support is not
- available.
- </li>
-
- <li>HFS+ APIs. If HFS+ APIs are available, all file access is performed
- using the HFS+ fork APIs to support long file access, and to support
- long Unicode compliant file names. In the absence of HFS+ APIs, classic
- HFS APIs are used instead.
- </li>
- </ul>
- </s3>
- </s2>
-</s1>
diff --git a/doc/build-winunix.xml b/doc/build-winunix.xml
deleted file mode 100644
index 151bb1644..000000000
--- a/doc/build-winunix.xml
+++ /dev/null
@@ -1,451 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!--
- * Licensed to the Apache Software Foundation (ASF) under one or more
- * contributor license agreements. See the NOTICE file distributed with
- * this work for additional information regarding copyright ownership.
- * The ASF licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
--->
-
-<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-
-<s1 title="Building on Windows and UNIX">
-
- <ul>
- <li><link anchor="WinNT">Building on Windows using Microsoft Visual C++</link></li>
- <li><link anchor="UNIX">Building on UNIX/Linux/Mac OS X platforms</link></li>
- <li><link anchor="CygWin">Building on Windows using Cygwin</link></li>
- <li><link anchor="MinGW">Building on Windows using MinGW-MSYS</link></li>
- <li><link anchor="WinBorlandCC">Building on Windows using Borland C++</link></li>
- <li><link anchor="WinBorlandBuilder">Building on Windows using Borland C++ Builder</link></li>
- <li><link anchor="WinIntel">Building 64 bit libraries on Windows using Intel C++</link></li>
- </ul>
-
- <anchor name="WinNT"/>
- <s2 title="Building on Windows using Microsoft Visual C++">
- <p>&XercesCName; source distribution comes with Microsoft Visual C++ projects and solutions to
- help you build &XercesCName;. The following describes the steps you need
- to build &XercesCName;.</p>
-
- <s3 title="Building &XercesCName; library">
- <p>To build &XercesCName; from the source distribution (using MSVC), you will
- need to open the solution containing the project. If you are
- building your application, you may want to add the &XercesCName;
- project inside your application's solution.</p>
- <p>The solutions containing the &XercesCName; project files and
- all other samples are in the following sub-directories in the
- &XercesC3SrcInstallDir; directory:</p>
-
-<source>
-(For VC6) projects\Win32\VC6\xerces-all\xerces-all.dsw
-(For VC7.1) projects\Win32\VC7.1\xerces-all\xerces-all.sln
-(For VC8) projects\Win32\VC8\xerces-all\xerces-all.sln
-(For VC9) projects\Win32\VC9\xerces-all\xerces-all.sln
-</source>
-
- <p>Once you have the solution open, you need to build the
- project marked <em>XercesLib</em>. You can select
- Debug/Release, Static/DLL, and, for VC8, 32/64 bit
- builds using the Configuration Manager dialog.</p>
-
- <p>If you want to include the &XercesCName; project into
- your own solution, you need to pick up:</p>
-<source>
-(For VC6) projects\Win32\VC6\xerces-all\XercesLib\XercesLib.dsp
-(For VC7.1) projects\Win32\VC7.1\xerces-all\XercesLib\XercesLib.vcproj
-(For VC8) projects\Win32\VC8\xerces-all\XercesLib\XercesLib.vcproj
-(For VC9) projects\Win32\VC9\xerces-all\XercesLib\XercesLib.vcproj
-</source>
-
- <p>You must make sure that you are linking your application with
- the &XercesC3WindowsLib;.lib library (or Debug/Static version of it
- and also make sure that the associated DLL is somewhere in your
- path.</p>
-
- <note>If you are linking your application to a static library,
- then you will need to compile your application with the
- XML_LIBRARY preprocessor define in order
- to turn off the DLL import/export mechanism. This is
- also the case for the Mingw-msys platform.</note>
-
- <note>If you are working on the AlphaWorks version which uses ICU,
- you must have the ICU data DLL named <code>icudata.dll</code>
- available from your path setting.</note>
-
- <note>If the library is built with the ICU message loader,
- or message catalog loader, then you need to make sure
- the XERCESC_NLS_HOME environment variable points to the
- $XERCESCROOT/msg directory where the message files reside.</note>
-
- </s3>
- <s3 title="Building samples">
- <p>If you are using the source package, inside the same solution
- (xerces-all.dsw or xerces-all.sln), you'll find several other
- projects. These are for the samples. Select all the samples
- and right click on the selection. Then choose "Build (selection
- only)" to build all the samples in one shot.</p>
- </s3>
- </s2>
-
- <anchor name="UNIX"/>
- <s2 title="Building on UNIX/Linux/Mac OS X platforms">
-
- <p>&XercesCName; uses
- <jump href="http://www.gnu.org/software/make/make.html">GNU make</jump>
- to build the libraries and samples. You must first make sure you
- have GNU make installed on your system before proceeding. On some
- platforms GNU make is called gmake instead of make.
- If you do not have GNU make, ask your system administrator
- to get it for you.</p>
-
- <p><em>Do not jump into the build directly before reading this.</em>
- Spending some time reading the following instructions will save
- you a lot of wasted time and support-related e-mail communication.</p>
-
- <p><em>Differences between the UNIX platforms:</em> The description below is
- generic, but as every programmer is aware, there are minor differences
- within the various UNIX flavors the world has been bestowed with.
- The one difference that you need to watch out in the discussion below,
- pertains to the system environment variable for finding libraries.
- On <em>Linux</em> and <em>Solaris</em>, the environment variable name is called
- <code>LD_LIBRARY_PATH</code>, on <em>AIX</em> it is <code>LIBPATH</code>,
- on <em>Mac OS X</em> it is <code>DYLD_LIBRARY_PATH</code>,
- while on <em>HP-UX</em> it is <code>SHLIB_PATH</code>. The following
- discussion assumes you are working on Linux, but it is with subtle
- understanding that you know how to interpret it for the other UNIX flavors.</p>
-
- <s3 title="Setting build environment variables">
- <p>Before doing the build, you must first set your environment variables
- to pick-up the compiler.
- While the first one is probably set for you by the system administrator, just
- make sure you can invoke the compiler. You may do so by typing the
- compiler invocation command without any parameters (e.g. xlc_r, or g++, or cc)
- and check if you get a proper response back.</p>
- </s3>
-
- <s3 title="Building &XercesCName; library">
- <p>As mentioned earlier, to build &XercesCName; from the source distribution,
- you must be ready with the GNU tools like
- <jump href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</jump> and
- <jump href="http://www.gnu.org/software/make/make.html">gmake</jump>
- before you attempt the build.</p>
-
- <p>The autoconf tool is required on only one platform and produces
- a set of portable scripts (configure) that you can run on all
- other platforms without actually having the autoconf tool installed
- everywhere. In all probability the autoconf-generated script
- (called <code>configure</code>) is already in your <code>src/xercesc</code>
- directory. If not, type:</p>
-
-<source>cd <full path to &XercesC3SrcInstallDir;>
-./reconf</source>
-
- <p>This generates a shell-script called <code>configure</code>. It is tempting to run
- this script directly as is normally the case, but wait a minute.
- Even if you are using the default compilers like
- <jump href="http://www.gnu.org/software/gcc/gcc.html">gcc</jump> and
- <jump href="http://www.gnu.org/software/gcc/gcc.html">g++</jump>
- you need to make some decisions about what components you want to
- build into the library.</p>
-
- <p>You need to specify one options from each category; not specifying one
- will instruct <code>configure</code> to pick the best choice available:</p>
-
-
- <p>Net Accessor (used to read data from HTTP sources):</p>
- <ol>
- <li><code>--enable-netaccessor-curl</code> Uses curl</li>
- <li><code>--enable-netaccessor-socket</code> Uses plain BSD sockets</li>
- <li><code>--enable-netaccessor-cfurl</code> Uses cfurl (Mac-only)</li>
- <li><code>--enable-netaccessor-winsock</code> Uses WinSock (Windows-only, either Cygwin or MinGW)</li>
- </ol>
- <p>Message Loader (used to store the strings of the error messages):</p>
- <ol>
- <li><code>--enable-msgloader-inmemory</code> Stores the messages in C++ arrays</li>
- <li><code>--enable-msgloader-icu</code> Stores the messages using ICU resource bundles</li>
- <li><code>--enable-msgloader-iconv</code> Stores the messages in a iconv message catalog</li>
- </ol>
- <p>Transcoder (used to convert strings between UTF-16 and any other supported encoding):</p>
- <ol>
- <li><code>--enable-transcoder-gnuiconv</code> Uses GNU iconv library</li>
- <li><code>--enable-transcoder-iconv</code> Uses iconv library</li>
- <li><code>--enable-transcoder-icu</code> Uses ICU library</li>
- <li><code>--enable-transcoder-macosunicodeconverter</code> Uses MacOS APIs (Mac-only)</li>
- <li><code>--enable-transcoder-windows</code> Uses Windows APIs (Windows-only, either Cygwin or MinGW)</li>
- </ol>
-
- <p>By default <code>configure</code> will build both shared and static libraries;
- you can use <code>--disable-shared</code> or <code>--disable-static</code> to
- suppress the version you don't need.</p>
-
- <p>Thread support is enabled by default too;
- you can use <code>--disable-threads</code> to remove it.</p>
-
- <p>If you need to specify a compiler (because more than one is found in the PATH,
- or because it has been renamed to a non-standard name), you should set the
- environment variables CXX and CC before invoking <code>configure</code>.<br/>
- If you need special compiler or linker options, define the environment variables
- CXXFLAGS and LDFLAGS.</p>
-
- <note>&XercesCName; can be built as either a standalone library or as a library
- dependent on International Components for Unicode (ICU). For simplicity,
- the following discussion only explains standalone builds.</note>
-
- <anchor name="configure-example"/>
- <p>The simplest way to build &XercesCName; is as follows:</p>
-
-<source>./configure</source>
-
- <p>This will instruct <code>configure</code> to find out the platform, the compiler
- and the libraries installed on the system. If more than one library is available
- for a category, the most powerful will be chosen (e.g. if ICU is available, it will
- be chosen over iconv).<br/>
- So it's recommended to examine the log to check if its choices are the correct ones.</p>
-
-<source>
-checking build system type... i686-pc-linux-gnu
-checking host system type... i686-pc-linux-gnu
-[..snip..]
-checking for g++... g++
-[..snip..]
-checking for gcc... gcc
-[..snip..]
-checking for libcurl...
-checking whether we can support the libcurl-based NetAccessor... no
-checking whether we can support the sockets-based NetAccessor... yes
-checking for which NetAccessor to use (choices: -socket-)... socket
-checking for icu... /usr/local
-checking iconv.h usability... yes
-checking iconv.h presence... yes
-checking for iconv.h... yes
-checking for wchar.h... (cached) yes
-checking for string.h... (cached) yes
-checking for stdlib.h... (cached) yes
-checking stdio.h usability... yes
-checking stdio.h presence... yes
-checking for stdio.h... yes
-checking ctype.h usability... yes
-checking ctype.h presence... yes
-checking for ctype.h... yes
-checking for locale.h... (cached) yes
-checking errno.h usability... yes
-checking errno.h presence... yes
-checking for errno.h... yes
-checking endian.h usability... yes
-checking endian.h presence... yes
-checking for endian.h... yes
-checking for iconv_open... yes
-checking for iconv_close... yes
-checking for iconv... yes
-checking whether we can support the GNU iconv Transcoder... yes
-checking for wchar.h... (cached) yes
-checking for mblen... (cached) yes
-checking for wcstombs... yes
-checking for mbstowcs... yes
-checking whether we can support the iconv Transcoder... yes
-checking whether we can support the ICU Transcoder... yes
-checking for which Transcoder to use (choices: -gnuiconv- -iconv- -icu-)... icu
-checking whether we support the InMemory MsgLoader... yes
-checking whether we support the ICU MsgLoader... yes
-checking for nl_types.h... (cached) yes
-checking for catopen... yes
-checking for catclose... yes
-checking for catgets... yes
-checking whether we can support the iconv MsgLoader... yes
-checking for which MsgLoader to use (choices: -inmemory- -icu- -iconv-)... icu
-checking for which File Manager to use... POSIX
-checking for which Mutex Manager to use... POSIX
-checking whether we are using SunPro 5.8 compiler... no
-configure: creating ./config.status
-config.status: creating Makefile
-config.status: creating lib/Makefile
-config.status: creating src/Makefile
-config.status: creating src/xercesc/util/MsgLoaders/ICU/resources/Makefile
-config.status: creating obj/Makefile
-config.status: creating tests/Makefile
-config.status: creating samples/Makefile
-config.status: creating config.h
-config.status: creating src/xercesc/util/Xerces_autoconf_config.hpp
-config.status: executing depfiles commands
-</source>
-
- <p>Now that the Makefiles are all created, you are ready to do the actual build.</p>
-
-<source>gmake</source>
-
- <p>Is that it? Yes, that's all you need to build &XercesCName; and the associated samples.</p>
-
- <p>If you need to build the tests, type</p>
-
-<source>gmake check</source>
-
- <p>To delete all the generated object files and executables, type:</p>
-
-<source>gmake clean</source>
-
- </s3>
- </s2>
-
- <anchor name="CygWin"/>
- <s2 title="Building on Windows using Cygwin">
- <p><em>Do not jump into the build directly before reading this.</em></p>
-
- <p>&XercesCName; may be built in the
- <jump href="http://www.cygwin.com">Cygwin</jump> environment for use
- by Cygwin applications. As with the <jump href="#UNIX">UNIX</jump>
- platforms, &XercesCName; on Cygwin uses
- <jump href="http://www.gnu.org">GNU</jump> tools. Therefore, with a
- couple of notable exceptions, &XercesCName; on Cygwin is built using
- the same instructions as the UNIX platforms. The build environment
- variable XERCESCROOT must be set to the proper path containing the
- &XercesCName; sources and <em>runConfigure</em> must be run with the
- "-p cygwin -c gcc -x g++" arguments.</p>
-
- <p>Cygwin's GCC also has the ability to build MinGW targeted binaries.
- This is supported via the -mno-cygwin compiler switch. In that case the
- arguments to runConfigure should be
- '-p mingw-msys -c gcc -x g++ -z -mno-cygwin -l -mno-cygwin -C --host=i686-mingw32'.
- Note that both the compiler and linker flags need to be set.</p>
-
- <p>Also note that Cygwin is different from the UNIX platforms in the way
- that it finds libraries at run time. While UNIX platforms may use the
- environment variable LD_LIBRARY_PATH, Cygwin uses the PATH environment
- variable.</p>
-
- <p>By default, autoconf on Cygwin and MinGW/MSYS doesn't build shared libraries,
- even if <code>configure</code> will detect it's possible; you will have to force
- it by specifying the <code>LDFLAGS=-no-undefined</code> option to <code>configure</code>
- </p>
-
- <p>There is an issue with the gcc/g++ compiler version 2.95, where C++
- exceptions thrown from a DLL will cause the application to crash, regardless
- of whether there is a "catch" statement. This bug doesn't occur in tests
- using gcc 3.1 or 3.2, so it is recommended that you use gcc 3.1 or higher.</p>
- </s2>
-
- <anchor name="MinGW"/>
- <s2 title="Building on Windows using MinGW">
- <p><em>Do not jump into the build directly before reading this.</em></p>
-
- <p>&XercesCName; may be built in the
- <jump href="http://www.mingw.org/msys.shtml">MinGW-MSYS</jump> environment for use
- by MinGW applications. As with the <jump href="#UNIX">UNIX</jump>
- platforms, &XercesCName; on MinGW uses
- <jump href="http://www.gnu.org">GNU</jump> tools. Therefore, with a
- couple of notable exceptions, &XercesCName; on MinGW is built using
- the same instructions as the UNIX platforms. The build environment
- variable XERCESCROOT must be set to the proper path containing the
- &XercesCName; sources and <em>runConfigure</em> must be run with the
- "-pmingw-msys -cgcc -xg++" arguments. It is also possible to build
- &XercesCName; libraries for MinGW using Cygwin. For more information
- on how to do this see the <jump href="#CygWin">Building on Windows
- using Cygwin</jump> section.</p>
-
- <p>Note that MinGW is different from the UNIX platforms in the way
- that it finds libraries at run time. While UNIX platforms may use the
- environment variable LD_LIBRARY_PATH, MinGW uses the PATH environment
- variable.</p>
-
- <p>When linking against the static version of &XercesCName;, be sure to
- use the '-DXML_LIBRARY' compiler flag. Otherwise the functions in the
- header files will be marked as to be imported from a DLL and the linker will fail.</p>
-
- <p>Also note that you can run into a bug found in older MinGW's dllwrap utility,
- which is used by &XercesCName; build system to link DLLs. For more information
- see the following <jump href="http://marc.info/?l=xerces-c-users&m=118891009725180&w=2">
- mailing list post</jump>.</p>
-
- <p>There is an issue with the gcc/g++ compiler version 2.95, where C++
- exceptions thrown from a DLL will cause the application to crash, regardless
- of whether there is a "catch" statement. This bug doesn't occur in tests
- using gcc 3.1 or 3.2, so it is recommended that you use gcc 3.1 or higher.</p>
- </s2>
-
- <anchor name="WinBorlandBuilder"/>
- <s2 title="Building on Windows using Borland C++ Builder">
- <p>&XercesCName; source distribution comes with Borland C++ Builder 6 projects to help you
- build &XercesCName;. The following describes the steps you need to build
- &XercesCName;.</p>
-
- <s3 title="Building &XercesCName; library">
- <p> The library and demo projects are all contained in the Xerces-all project group:
- </p>
-
- <ul>
- <li> &XercesC3SrcInstallDir;\projects\Win32\BCB6\Xerces-all\Xerces-all.bpg </li>
- </ul>
-
- <p> Each project in the group refers a directory below \Xerces-all.
- For example, the XercesLib project files are contained in the directory
- </p>
-
- <ul>
- <li> &XercesC3SrcInstallDir;\projects\Win32\BCB6\Xerces-all\XercesLib </li>
- </ul>
-
- <p> To build any project, open the project manager. Double click on the project
- name. Then select "Project|Build" from the menu. For example, double click
- on XercesLib.dll in the manager. Then select "Project|Build XercesLib" from
- the menu.
-
- Once the library has been built, include XercesLib.lib with in application's
- project and place XercesLib.dll somewhere in your path.
- </p>
-
- </s3>
- </s2>
-
- <anchor name="WinBorlandCC"/>
- <s2 title="Building on Windows using Borland C++">
- <p>&XercesCName; source distribution comes with Borland C++ Compiler make files to help you
- build &XercesCName;. The following describes the steps you need to build
- &XercesCName;.</p>
-
- <ol>
- <li>Change directory to <code> &XercesC3SrcInstallDir;\projects\Win32\BCC.551\Xerces-all</code></li>
- <li>Run <code>MakeBuildDirs.bat</code>.</li>
- <li>Then issue</li>
- <ul>
- <li><code>make -f Xerces-all.mak</code>
- <br/>to build the dll (without deprecated DOM API) and tests, or</li>
- <li><code>make -f Xerces-all.mak -DWITHDEPRDOM=Y</code>
- <br/>to build the dll with deprecated DOM API (approx. 300k larger) and tests</li>
- </ul>
- </ol>
- </s2>
-
- <anchor name="WinIntel"/>
- <s2 title="Building 64 bit libraries on Windows using Intel C++">
- <p>&XercesCName; source distribution comes with Microsoft Visual C++ NMake Files which
- work with Intel C++ Compiler. The following describes the steps you need
- to build &XercesCName; 64 bit binary using Intel C++ Compiler.</p>
-
- <s3 title="Building &XercesCName; library">
- <p>&XercesCName; source distribution provides a makefile <code>all.mak</code>
- which will build everything including samples, tests and the parser library.</p>
-<source>
-cd &XercesC3SrcInstallDir;\projects\Win32\VC6\xerces-all\all
-nmake -f all.mak "CFG=all - Win64 Release" CPP=ecl.exe
-</source>
-
- <p>If you want to just build the &XercesCName; parser library alone, then</p>
-<source>
-cd &XercesC3SrcInstallDir;\projects\Win32\VC6\xerces-all\XercesLib
-nmake -f XercesLib.mak "CFG=XercesLib - Win64 Release" CPP=ecl.exe
-</source>
-
- <p>You must make sure that you are linking your application with
- the &XercesC3WindowsLib;.lib library and also make sure that
- the associated DLL is somewhere in your path.</p>
- </s3>
- </s2>
-</s1>
diff --git a/doc/build.xml b/doc/build.xml
index 5b78706a7..1fee53965 100644
--- a/doc/build.xml
+++ b/doc/build.xml
@@ -19,42 +19,342 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Build Instructions">
+ <s2 title="Build Instructions">
- <s2 title="Building on Windows and UNIX">
- <p>Read the <jump href="build-winunix-&XercesC3Series;.html">Building on Windows and UNIX</jump> document
- or jump directly to:</p>
- <ul>
- <li><jump href="build-winunix-&XercesC3Series;.html#WinNT">Building on Windows using Microsoft Visual C++</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#UNIX">Building on UNIX/Linux/Mac OS X platforms</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#CygWin">Building on Windows using Cygwin</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#MinGW">Building on Windows using MinGW-MSYS</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#WinBorlandCC">Building on Windows using Borland C++</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#WinBorlandBuilder">Building on Windows using Borland C++ Builder</jump></li>
- <li><jump href="build-winunix-&XercesC3Series;.html#WinIntel">Building 64 bit libraries on Windows using Intel C++</jump></li>
- </ul>
- </s2>
+ <p>Build instructions are provided for the following platforms and
+ compilers:</p>
- <s2 title="Building on Other Platforms">
- <p>Read the <jump href="build-other-&XercesC3Series;.html">Building on Other Platforms</jump> document
- or jump directly to:</p>
<ul>
- <li><jump href="build-other-&XercesC3Series;.html#iSeries">Building &XercesCName; on iSeries (AS/400)</jump></li>
- <li><jump href="build-other-&XercesC3Series;.html#Mac">Building &XercesCName; on Macintosh</jump></li>
+ <li><link anchor="UNIX">UNIX/Linux/Mac OS X/Cygwin/MinGW</link></li>
+ <li><link anchor="Windows">Windows using Microsoft Visual C++</link></li>
+ <li><link anchor="BorlandCC">Windows using Borland C++</link></li>
+ <li><link anchor="BorlandBuilder">Windows using Borland C++ Builder</link></li>
</ul>
- </s2>
- <s2 title="Other Build Instructions">
- <p>Read the <jump href="build-misc-&XercesC3Series;.html">Other Build Instructions</jump> document
- or jump directly to:</p>
- <ul>
- <li><jump href="build-misc-&XercesC3Series;.html#ICUPerl">Building &XercesCName; with ICU</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#RPMLinux">Building &XercesCName; using RPM on Linux</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#WinCOM">Building &XercesCName; COM Wrapper on Windows</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#UserDoc">Building User Documentation</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#PortInfo">I wish to port &XercesCProjectName; to my favourite platform. Do you have any suggestions?</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#XMLChInfo">What should I define XMLCh to be?</jump></li>
- <li><jump href="build-misc-&XercesC3Series;.html#HelpInfo">Where can I look for more help?</jump></li>
- </ul>
- </s2>
+ <anchor name="UNIX"/>
+ <s3 title="Building on UNIX/Linux/Mac OS X/Cygwin/MinGW platforms">
+
+ <p>For building on UNIX and UNIX-like (GNU/Linux, Max OS X,
+ Cygwin, MinGW-MSYS) platforms &XercesCName; uses the
+ GNU automake-based build systems and requires that you
+ have <jump href="http://www.gnu.org/software/make/make.html">GNU
+ make</jump> installed. On some platforms GNU make is called gmake
+ instead of make.</p>
+
+ <p>As with all automake-based projects the build process is divided
+ into two parts: configuration and building. The configuration
+ part is performed using the <code>configure</code> script that
+ can be found in the <code>&XercesC3SrcInstallDir;</code> directory.
+ The build part is performed by invoking <code>make</code>.</p>
+
+ <p>Besides the standard <code>configure</code> options which
+ you can view by running <code>configure --help</code>,
+ &XercesCName; provides a number of project-specific options
+ that are worth mentioning. You can specify one option for
+ each category outlined below. If you do not specify anything
+ for a particular category then <code>configure</code> will
+ select the most appropriate default. At the end of its
+ execution <code>configure</code> prints the selected
+ values for each category.</p>
+
+
+ <p>Net Accessor (used to access network resources):</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>--enable-netaccessor-curl</code></td>
+ <td>use the libcurl library</td>
+ </tr>
+ <tr>
+ <td><code>--enable-netaccessor-socket</code></td>
+ <td>use plain sockets</td>
+ </tr>
+ <tr>
+ <td><code>--enable-netaccessor-cfurl</code></td>
+ <td>use the CFURL API (only on Mac OS X)</td>
+ </tr>
+ <tr>
+ <td><code>--enable-netaccessor-winsock</code></td>
+ <td>use WinSock (only on Windows, Cygwin, MinGW)</td>
+ </tr>
+ <tr>
+ <td><code>--disable-network</code></td>
+ <td>disable network support</td>
+ </tr>
+ </table>
+
+ <p>Transcoder (used to convert between internal UTF-16 and other encodings):</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>--enable-transcoder-gnuiconv</code></td>
+ <td>use the GNU iconv library</td>
+ </tr>
+ <tr>
+ <td><code>--enable-transcoder-iconv</code></td>
+ <td>use the iconv library</td>
+ </tr>
+ <tr>
+ <td><code>--enable-transcoder-icu</code></td>
+ <td>use the ICU library</td>
+ </tr>
+ <tr>
+ <td><code>--enable-transcoder-macosunicodeconverter</code></td>
+ <td>use Mac OS X APIs (only on Mac OS X)</td>
+ </tr>
+ <tr>
+ <td><code>--enable-transcoder-windows</code></td>
+ <td>use Windows APIs (only on Windows, Cygwin, MinGW)</td>
+ </tr>
+ </table>
+
+ <p>Message Loader (used to access diagnostics messages):</p>
+
+ <table>
+ <tr>
+ <th>Option</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>--enable-msgloader-inmemory</code></td>
+ <td>store the messages in memory</td>
+ </tr>
+ <tr>
+ <td><code>--enable-msgloader-icu</code></td>
+ <td>store the messages using the ICU resource bundles</td>
+ </tr>
+ <tr>
+ <td><code>--enable-msgloader-iconv</code></td>
+ <td>store the messages in the iconv message catalog</td>
+ </tr>
+ </table>
+
+ <p>Thread support is enabled by default and can be disabled with the
+ <code>--disable-threads</code> option.</p>
+
+ <p>By default <code>configure</code> selects both shared and static
+ libraries. You can use the <code>--disable-shared</code> and
+ <code>--disable-static</code> options to avoid building the
+ version you don't need.</p>
+
+ <p>Finally, to make the build process cleaner the &XercesCName;
+ build system hides actual compiler commands being executed
+ by <code>make</code>. If you would like to see those then you
+ can specify the <code>--disable-pretty-make</code> option.</p>
+ <p>If you need to specify compiler executables that should be
+ used to build &XercesCName;, you can set the CC and CXX
+ variables when invoking <code>configure</code>. Similarly,
+ if you need to specify additional compiler or linker options,
+ you can set the CFLAGS, CXXFLAGS, and LDFLAGS variables.
+ For example:</p>
+
+ <source>./configure --disable-static CC=gcc-4.3 CXX=g++-4.3 CFLAGS=-O3 CXXFLAGS=-O3</source>
+
+ <p>Once the configuration part is complete you can run
+ <code>make</code> (or <code>gmake</code>). Running
+ <code>make</code> from the <code>&XercesC3SrcInstallDir;</code>
+ directory builds &XercesCName; library and examples. If
+ you like to build only the library, you can run make from
+ <code>&XercesC3SrcInstallDir;/src</code>.</p>
+
+ <p>If you would like to build the tests and run the
+ automated test suite, run <code>make check</code>
+ from the <code>&XercesC3SrcInstallDir;</code>
+ directory. The automated test suite required
+ Perl and the <code>diff</code> command.</p>
+
+ <p>Some platforms and configurations require extra
+ <code>configure</code> and <code>make</code> options
+ which are shown in the following table.</p>
+
+ <table>
+ <tr>
+ <th>Platform</th>
+ <th>Compiler</th>
+ <th>Options</th>
+ </tr>
+ <tr>
+ <td>Solaris x86</td>
+ <td>Sun CC</td>
+ <td><code>./configure CXX=CC CC=cc</code></td>
+ </tr>
+ <tr>
+ <td>Solaris x86-64</td>
+ <td>Sun CC</td>
+ <td><code>./configure CXX=CC CC=cc CFLAGS=-xarch=amd64 CXXFLAGS=-xarch=amd64</code></td>
+ </tr>
+ <tr>
+ <td>Solaris SPARC</td>
+ <td>Sun CC</td>
+ <td><code>/configure CXX=CC CC=cc</code></td>
+ </tr>
+ <tr>
+ <td>Solaris SPARCv9</td>
+ <td>Sun CC</td>
+ <td><code>./configure CXX=CC CC=cc CFLAGS=-xarch=v9 CXXFLAGS=-xarch=v9</code></td>
+ </tr>
+ <tr>
+ <td>AIX PowerPC</td>
+ <td>IBM XL C++</td>
+ <td><code>./configure CXX=xlC_r CC=xlc_r</code><br/>
+ <code>gmake libxerces_c_la_LDFLAGS=-qmkshrobj</code></td>
+ </tr>
+ <tr>
+ <td>AIX PowerPC-64</td>
+ <td>IBM XL C++</td>
+ <td><code>export OBJECT_MODE=64</code><br/>
+ <code>./configure CXX=xlC_r CC=xlc_r CXXFLAGS=-q64 CFLAGS=-q64</code><br/>
+ <code>gmake libxerces_c_la_LDFLAGS=-qmkshrobj</code></td>
+ </tr>
+ <tr>
+ <td>HP-UX IA-64-32</td>
+ <td>HP aCC</td>
+ <td><code>./configure CXX=aCC CC=aCC CFLAGS=-mt CXXFLAGS=-mt LDFLAGS=-mt</code></td>
+ </tr>
+ <tr>
+ <td>HP-UX IA-64</td>
+ <td>HP aCC</td>
+ <td><code>./configure CXX=aCC CC=aCC CFLAGS="-mt +DD64" CXXFLAGS="-mt +DD64" LDFLAGS="-mt +DD64"</code></td>
+ </tr>
+ <tr>
+ <td>Mac OS X x86-64</td>
+ <td>GCC</td>
+ <td><code>/configure CFLAGS="-arch x86_64" CXXFLAGS="-arch x86_64" </code></td>
+ </tr>
+ <tr>
+ <td>Mac OS X PowerPC-64</td>
+ <td>GCC</td>
+ <td><code>./configure CFLAGS="-arch ppc64" CXXFLAGS="-arch ppc64"</code></td>
+ </tr>
+ <tr>
+ <td>Mac OS X x86/PowerPC</td>
+ <td>GCC</td>
+ <td><code>./configure --disable-dependency-tracking CFLAGS="-arch i386 -arch ppc" CXXFLAGS="-arch i386 -arch ppc"</code></td>
+ </tr>
+ <tr>
+ <td>Mingw x86</td>
+ <td>GCC</td>
+ <td><code>./configure LDFLAGS=-no-undefined</code></td>
+ </tr>
+ <tr>
+ <td>Cygwin x86</td>
+ <td>GCC</td>
+ <td><code>./configure LDFLAGS=-no-undefined</code></td>
+ </tr>
+ </table>
+ <p/>
+
+ <note>
+ Note that different UNIX platforms use different system
+ environment variable for finding libraries. On Linux
+ and Solaris, the environment variable name is
+ <code>LD_LIBRARY_PATH</code>, on AIX it is
+ <code>LIBPATH</code>, on Mac OS X it is
+ <code>DYLD_LIBRARY_PATH</code>, and on HP-UX
+ it is <code>SHLIB_PATH</code>.
+ </note>
+
+ <note>
+ Note that Cygwin and MinGW are different from the UNIX platforms
+ in the way they find libraries at run time. While UNIX platforms
+ may use the <code>LD_LIBRARY_PATH</code> environment variable,
+ Cygwin and MinGW use the <code>PATH</code> environment variable.
+ </note>
+
+ <note>
+ On the MinGW platform when linking against the static
+ &XercesCName; library, make sure you compile your application
+ with the <code>-DXML_LIBRARY</code> preprocessor flag. Otherwise
+ the functions in the header files will be marked as to be
+ imported from a DLL and the linker will be unable to resolve
+ the &XercesCName; symbols.
+ </note>
+ </s3>
+
+ <anchor name="Windows"/>
+ <s3 title="Building on Windows using Microsoft Visual C++">
+ <p>&XercesCName; source distribution comes with Microsoft Visual C++ projects and solutions.
+ The following describes the steps you need to build with this compiler.</p>
+
+ <p>To build &XercesCName; from the source distribution you will
+ need to open the solution containing the project. The solutions
+ containing the &XercesCName; project files are in the following
+ sub-directories in the <code>&XercesC3SrcInstallDir;</code>
+ directory:</p>
+
+<source>
+(For VC6) projects\Win32\VC6\xerces-all\xerces-all.dsw
+(For VC7.1) projects\Win32\VC7.1\xerces-all\xerces-all.sln
+(For VC8) projects\Win32\VC8\xerces-all\xerces-all.sln
+(For VC9) projects\Win32\VC9\xerces-all\xerces-all.sln
+</source>
+
+ <p>Once you have the solution open, you need to build the
+ project named <code>XercesLib</code>. You can select
+ Debug/Release, Static/DLL, and, for VC8 and VC9, 32/64 bit
+ builds using the Configuration Manager dialog. You
+ can also select whether the &XercesCName; library
+ should use ICU for transcoding.</p>
+
+ <p>When building your own applications you need to make sure
+ that you are linking your application with the
+ &XercesC3WindowsLib;.lib library (or Debug/Static version of it)
+ and also that the associated DLL is somewhere in the
+ executable/DLL search path (<code>PATH</code>).</p>
+
+ <note>If you are linking your application to a static library,
+ then you will need to compile your application with the
+ XML_LIBRARY preprocessor define in order
+ to turn off the DLL import/export mechanism. This is
+ also the case for the MinGW platform.</note>
+
+ <p>If you would also like to build tests and/or samples, inside
+ the solution files mentioned above (<code>xerces-all.dsw</code>
+ or <code>xerces-all.sln</code>), you'll find several other
+ projects which are for the tests and samples. Select all
+ the tests/samples that you would like to build and then
+ right click on the selection. Choose "Build (selection
+ only)" to build all the selected projects in one shot.</p>
+ </s3>
+
+ <anchor name="BorlandBuilder"/>
+ <s3 title="Building on Windows using Borland C++ Builder">
+ <p>&XercesCName; source distribution comes with the
+ Borland C++ Builder 6 projects. The following describes the steps you
+ need to build with this compiler.</p>
+
+ <p>The library and example projects are all contained in the
+ Xerces-all project group:
+ <code>&XercesC3SrcInstallDir;\projects\Win32\BCB6\Xerces-all\Xerces-all.bpg</code>.
+ Each project in the group refers a directory below <code>Xerces-all\</code>.
+ For example, the XercesLib project files are contained in the directory
+ <code>&XercesC3SrcInstallDir;\projects\Win32\BCB6\Xerces-all\XercesLib</code>.</p>
+
+ <p>To build a project, open the project manager, double click on the project
+ name, and select "Project -> Build" from the menu. For example, double click
+ on XercesLib.dll in the manager then select "Project -> Build XercesLib" from
+ the menu.
+ </p>
+ </s3>
+
+ <anchor name="BorlandCC"/>
+ <s3 title="Building on Windows using Borland C++">
+ <p>&XercesCName; source distribution comes with the Borland C++ makefiles. The
+ following describes the steps you need to build &XercesCName; with this compiler.</p>
+ <ol>
+ <li>Change to the <code>&XercesC3SrcInstallDir;\projects\Win32\BCC.551\Xerces-all</code> directory</li>
+ <li>Run <code>MakeBuildDirs.bat</code></li>
+ <li><code>make -f Xerces-all.mak</code> to build the library, examples, and tests.</li>
+ </ol>
+ </s3>
+ </s2>
</s1>
diff --git a/doc/createdoc.xml b/doc/createdoc.xml
index d3771d63a..b1eee68a1 100644
--- a/doc/createdoc.xml
+++ b/doc/createdoc.xml
@@ -21,8 +21,8 @@
<s1 title="Sample: CreateDOMDocument">
<s2 title="CreateDOMDocument">
- <p> CreateDOMDocument, illustrates how you can create a DOM tree in
- memory from scratch. It then reports the elements in the tree that
+ <p>The CreateDOMDocument example illustrates how you can create a DOM tree in
+ memory from scratch. It then reports the number of elements in the tree that
was just created.</p>
<s3 title="Running CreateDOMDocument">
diff --git a/doc/domcount.xml b/doc/domcount.xml
index 10f6881dd..fed279fb5 100644
--- a/doc/domcount.xml
+++ b/doc/domcount.xml
@@ -22,12 +22,12 @@
<s2 title="DOMCount">
<p>DOMCount uses the provided DOM API to parse an XML file,
- constructs the DOM tree and walks through the tree counting
+ construct the DOM tree and walk through the tree counting
the elements (using just one API call).</p>
<s3 title="Running DOMCount">
- <p>The DOMCount sample parses an XML file and prints out a count of the number of
+ <p>The DOMCount sample parses an XML file and prints out the number of
elements in the file. To run DOMCount, enter the following </p>
<source>DOMCount <XML file></source>
<p>The following parameters may be set from the command line </p>
@@ -45,7 +45,7 @@ Options:
-n Enable namespace processing. Defaults to off.
-s Enable schema processing. Defaults to off.
-f Enable full schema constraint checking. Defaults to off.
- -locale=ll_CC specify the locale, default: en_US
+ -locale=ll_CC specify the locale, default: en_US
-p Print out names of elements and attributes encountered.
-? Show this help.
@@ -55,12 +55,12 @@ Options:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from DOMCount</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
DOMCount -v=always personal.xml
personal.xml: 20 ms (37 elems)</source>
<note>The time reported by the system may be different, depending on your
- processor type.</note>
+ processor speed.</note>
</s3>
</s2>
</s1>
diff --git a/doc/domprint.xml b/doc/domprint.xml
index 9daf03211..55ad9b136 100644
--- a/doc/domprint.xml
+++ b/doc/domprint.xml
@@ -22,7 +22,7 @@
<s2 title="DOMPrint">
<p>DOMPrint parses an XML file, constructs the DOM tree, and
- invokes DOMLSSerializer::write() to serialize the resultant
+ invokes DOMLSSerializer::write() to serialize the resultant
DOM tree back to XML stream.
</p>
@@ -50,10 +50,10 @@ Options:
-wenc=XXX Use a particular encoding for output. Default is
the same encoding as the input XML file. UTF-8 if
input XML file has not XML declaration.
- -wfile=xxx Write to a file instead of stdout.
- -wscs=xxx Enable/Disable split-cdata-sections. Default on.
- -wddc=xxx Enable/Disable discard-default-content. Default on.
- -wflt=xxx Enable/Disable filtering. Default off.
+ -wfile=xxx Write to a file instead of stdout.
+ -wscs=xxx Enable/Disable split-cdata-sections. Default on.
+ -wddc=xxx Enable/Disable discard-default-content. Default on.
+ -wflt=xxx Enable/Disable filtering. Default off.
-wfpp=xxx Enable/Disable format-pretty-print. Default off.
-wbom=xxx Enable/Disable write Byte-Order-Mark Default off.
-? Show this help
@@ -67,7 +67,7 @@ The parser has intrinsic support for the following encodings:\n"
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from DOMPrint</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
DOMPrint -v=always personal.xml
<?xml version="1.0" encoding="iso-8859-1"?>
@@ -118,38 +118,38 @@ DOMPrint -v=always personal.xml
SAXPrint produce different results because of the way the two APIs store data
and capture events.</p>
- <p>Application needs to provide its own implementation of
- DOMErrorHandler (in this sample, the DOMPrintErrorHandler),
- if it would like to receive notification from the serializer
+ <p>Application needs to provide its own implementation of
+ DOMErrorHandler (in this sample, the DOMPrintErrorHandler),
+ if it would like to receive notification from the serializer
in the case any error occurs during the serialization.
</p>
- <p>Application needs to provide its own implementation of
- DOMLSSerializerFilter (in this sample, the DOMPrintFilter),
- if it would like to filter out certain part of the DOM
- representation, but must be aware that thus may render the
+ <p>Application needs to provide its own implementation of
+ DOMLSSerializerFilter (in this sample, the DOMPrintFilter),
+ if it would like to filter out certain part of the DOM
+ representation, but must be aware that thus may render the
resultant XML stream invalid.
</p>
- <p>Application may choose any combination of characters as the
- end of line sequence to be used in the resultant XML stream,
- but must be aware that thus may render the resultant XML
+ <p>Application may choose any combination of characters as the
+ end of line sequence to be used in the resultant XML stream,
+ but must be aware that this may render the resultant XML
stream ill formed.
</p>
- <p>Application may choose a particular encoding name in which
- the output XML stream would be, but must be aware that if
- characters, unrepresentable in the encoding specified, appearing
- in markups, may force the serializer to terminate serialization
+ <p>Application may choose a particular encoding name in which
+ the output XML stream should be, but must be aware that if
+ unrepresentable in the encoding specified characters appear
+ in the markup, it may force the serializer to terminate serialization
prematurely, and thus no complete serialization would be done.
</p>
- <p>Application shall query the serializer first, before set any
+ <p>Application shall query the serializer first, before set any
feature/mode(true, false), or be ready to catch exception if this
feature/mode is not supported by the serializer.
</p>
- <p>Application needs to clean up the filter, error handler and
+ <p>Application needs to release the filter, error handler and
format target objects created for the serialization.
</p>
diff --git a/doc/enumval.xml b/doc/enumval.xml
index f785085c0..7680b6c63 100644
--- a/doc/enumval.xml
+++ b/doc/enumval.xml
@@ -21,7 +21,7 @@
<s1 title="Sample: EnumVal">
<s2 title="EnumVal">
- <p>EnumVal shows how to enumerate the markup decls in a DTD Grammar.</p>
+ <p>EnumVal shows how to enumerate the markup declarations in a DTD Grammar.</p>
<s3 title="Running EnumVal">
<p>This program parses the specified XML file, then shows how to
@@ -36,7 +36,7 @@ shows how one can access the DTD information stored in internal
data structures.
</source>
<p>Here is a sample output from EnumVal</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
EnumVal personal.xml
ELEMENTS:
diff --git a/doc/faq-build.xml b/doc/faq-build.xml
index 58d08697d..85ed7b1ae 100644
--- a/doc/faq-build.xml
+++ b/doc/faq-build.xml
@@ -18,36 +18,13 @@
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
-<faqs title="Building / Running FAQs">
-
- <faq title="Why do I get compilation error saying undeclared identifier or class undefined?">
-
- <q>Why do I get compilation error saying undeclared identifier or class undefined?</q>
-
- <a>
-
- <p>&XercesCName; &XercesC3Version; now supports C++ Namespace.</p>
-
- <p>If C++ Namespace is ENABLED, users' applications must
- namespace qualify all the &XercesCName; classes, data, and
- variables with <code>XERCES_CPP_NAMESPACE_QUALIFIER </code>
- or add the <code>XERCES_CPP_NAMESPACE_USE</code> clause.
- Users also need to ensure all forward declarations are
- properly qualified or scoped.
- </p>
-
- <p>See the Programming Guide <jump href="program-others-&XercesC3Series;.html#CPPNamespace">
- Using C++ Namespace</jump> for details.
- </p>
-
- </a>
- </faq>
+<faqs title="Building / Running &XercesCName;">
<faq title="Why do I get compilation error saying DOMDocument was declared twice using
- Microsoft Visual C++.Net?">
+ Microsoft Visual C++?">
<q>Why do I get compilation error saying DOMDocument was declared twice using
- Microsoft Visual C++.Net?</q>
+ Microsoft Visual C++?</q>
<a>
@@ -56,39 +33,16 @@
with the &XercesCName; &XercesC3Version; <code>&XercesC3Namespace;::DOMDocument</code>
and thus lead to the compilation errors.</p>
- <p> Qualifier the use of DOMDocument in your application explicitly e.g.
- <br/><br/><code>XERCES_CPP_NAMESPACE_QUALIFIER DOMDocument * fDoc;</code><br/><br/>
- will eliminate these compilation problems.
+ <p>Qualifier the use of DOMDocument in your application explicitly e.g.,
+ <br/><br/><code>xercesc::DOMDocument* doc;</code><br/><br/>
+ will eliminate these compilation problems. Alternatively, you
+ may want to get rid of the <code>Msxml.h</code> header inclusion.
</p>
</a>
</faq>
- <faq title="Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?">
- <q>Why do I get Internal Compiler Error when compiling &XercesCName; for a 64bit target with gcc?</q>
- <a>
- <p>This is a compiler problem. Try turning off optimization to bypass the problem.</p>
- </a>
- </faq>
-
-
- <faq title="Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?">
-
- <q>Building &XercesCName; with compiler GCC 2.7.x or 2.8.x gives problem, what's wrong?</q>
-
- <a>
- <p>Users using GCC 2.7.x or 2.8.x may have unsuccessful compile/link/run experience with
- &XercesCName;. There were issues related to templates and multi threaded exception
- handling with this old version GCC compiler.
- </p>
-
- <p>Please upgrade to at least GCC 2.95.2.
- </p>
-
- </a>
- </faq>
-
- <faq title="Why does my application give unresolved linking errors?">
+ <faq title="Why does my application have unresolved linking errors?">
<q>Why does my application give unresolved linking errors?</q>
@@ -98,59 +52,22 @@
<ol>
<li>Verify that you have specified the appropriate option and library path in the linker
command line</li>
- <li>If you're using the binary build of &XercesCName;, make sure that the OS and compiler are
- the same version as the ones used to build the binary. Different OS and
+ <li>If you're using the binary build of &XercesCName;, make sure that the CPU architecture, OS,
+ and compiler are
+ the same as the ones used to build the application. Different OS and
compiler versions might cause unresolved linking problems or compilation
errors. If the versions are different, rebuild the &XercesCName; library on
- your system before building your application. If you're using ICU (which is
- packaged with XML4C) you need to rebuild the compatible version of ICU
- first.</li>
- <li>Check that the library path is set properly and that the correct
- versions of <code>gmake</code> and <code>autoconf</code> are on your system.</li>
- <li>If C++ Namespace support is ENABLED (all the binary distributions of &XercesCName;
- &XercesC3Version; are built with C++ Namespace enabled), users' applications
- must namespace qualify all the &XercesCName; classes, data and variables.
- See the Programming Guide <jump href="program-others-&XercesC3Series;.html#CPPNamespace">
- Using C++ Namespace</jump> for details.</li>
- <li>If you are using Microsoft Visual Studio .NET 2003, 2005, or 2008, check that the
- option "Treat wchar_t as a built-in type" has been set to the same value
- used to build Xerces.</li>
+ your system before building your application.</li>
+ <li>If you are using Microsoft Visual Studio 2003 (7.1), 2005 (8.0), or 2008 (9.0),
+ check that the
+ "Treat wchar_t as a built-in type" option has been set to the same value as
+ used to build &XercesCName;. The binary distribution for Visual Studio 7.1 is
+ built with this option turned off. The binary distributions for Visual Studio 8.0
+ and 9.0 are built with this option turned on.</li>
</ol>
</a>
</faq>
- <faq title="Why do I get link error saying icudata library not found when building with ICU?">
-
- <q>Why do I get link error saying icudata library not found when building with ICU?</q>
-
- <a>
- <p>There is a bug in the Makefile of ICU 1.7, 1.8 and 1.8.1. The link created during
- ICU installation in $ICUROOT is, for example,
- </p>
-
- <p>icudata.so@ -> icudt17l.so
- </p>
-
- <p>instead of
- </p>
-
- <p>libicudata.so@ -> libicudt17l.so <br/>
- </p>
-
- <p>Therefore the -licudata doesn't work. To bypass the problem, please manually create the
- following link:
- </p>
-
- <p>libicudata.so@ -> libicudt17l.so
- </p>
-
- <p>This problem has been fixed in ICU 2.0.
- </p>
-
-
- </a>
- </faq>
-
<faq title="I cannot run the sample applications. What is wrong?">
<q>I cannot run the sample applications. What is wrong?</q>
@@ -158,209 +75,13 @@
<a>
<p>In order to run an application built using &XercesCProjectName; you must
- set up your path and library search path properly. In the stand-alone version
- from Apache, you must have the &XercesCName; runtime library available from
- your path settings.
- </p>
- <p>On Windows this library is called <code>&XercesC3WindowsDLL;.dll</code>
- which must be available from your <code>PATH</code> settings. (Note that there are
- separate debug and release dlls for Windows. The release dll is named
- <code>&XercesC3WindowsDLL;.dll</code>, and the debug dll
- is named <code>&XercesC3WindowsDLL;d.dll)</code>.
- </p>
- <p>On UNIX platforms the library is called &XercesC3UnixLib;.so.&XercesC3UnixSoName; (or
- &XercesC3UnixLib;&XercesC3UnixSoName;.so or &XercesC3UnixLib;.sl.&XercesC3UnixSoName;)
- which must be available from your <code>LD_LIBRARY_PATH</code>
- (or <code>LIBPATH</code> or <code>SHLIB_PATH</code>) environment variable.</p>
-
- <p>Thus, if you installed your binaries under <code>$HOME/fastxmlparser</code>, you need to point your library path to that directory.</p>
-
-<source>export LIBPATH=$LIBPATH:$HOME/fastxmlparser/lib # (AIX)
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/fastxmlparser/lib # (Solaris, Linux)
-export SHLIB_PATH=$SHLIB_PATH:$HOME/fastxmlparser/lib # (HP-UX)</source>
-
- <p>If you are using the XML4C parser from IBM, you will
- need to put in two additional DLLs. In the Windows build these are <code>icuuc*.dll</code> and <code>icudt*.dll</code> which must be available from your PATH settings. On UNIX, these
- libraries are called <code>libicuuc*.so</code> and <code>libicudt*.so</code> (or <code>.sl</code> for HP-UX or <code>.a</code> for AIX) which must be available from your library search path.</p>
-
- <p>If the parser is built with icu message loader (as mentioned above), or message
- catalog loader, you need an environment variable, XERCESC_NLS_HOME to point to
- the directory, &XercesC3SrcInstallDir;/msg, where the message files reside.
+ set up your path and library search path properly. For more information
+ refer to the <link idref="install-&XercesC3Series;">Installation instructions</link>.
</p>
</a>
</faq>
- <faq title="Why does my application crash on AIX when I run it under a
- multi-threaded environment?">
-
- <q>Why does my application crash on AIX when I run it under a
- multi-threaded environment?</q>
-
- <a>
-
- <p>AIX maintains two kinds of libraries on the system, thread-safe and
- non-thread safe. Multi-threaded libraries on AIX follow a different naming
- convention, Usually the multi-threaded library names are followed with "_r".
- For example, libc.a is single threaded whereas libc_r.a is multi-threaded.</p>
-
- <p>To make your multi-threaded application run on AIX, you <em>must</em>
- ensure that you do not have a "system library path" in your <code>LIBPATH</code>
- environment variable when you run the application. The appropriate
- libraries (threaded or non-threaded) are automatically picked up at runtime. An
- application usually crashes when you build your application for multi-threaded
- operation but don't point to the thread-safe version of the system libraries.
- For example, LIBPATH can be simply set as:</p>
-
-<source>LIBPATH=$HOME/<&XercesCProjectName;>/lib</source>
-
- <p>Where <&XercesCProjectName;> points to the directory where the
- &XercesCProjectName; application resides.</p>
-
- <p>If, for any reason unrelated to &XercesCProjectName;, you need to keep a
- "system library path" in your LIBPATH environment variable, you must make sure
- that you have placed the thread-safe path before you specify the normal system
- path. For example, you must place <ref>/lib/threads</ref> before
- <ref>/lib</ref> in your LIBPATH variable. That is to say your LIBPATH may look
- like this:</p>
-
-<source>export LIBPATH=$HOME/<&XercesCProjectName;>/lib:/usr/lib/threads:/usr/lib</source>
-
- <p>Where /usr/lib is where your system libraries are.</p>
-
- </a>
- </faq>
-
- <faq title="Why does my multi-threaded application crash on Solaris 2.6?">
-
- <q>Why does my multi-threaded application crash on Solaris 2.6?</q>
-
- <a>
-
- <p>The problem appears because the throw call on Solaris 2.6 is not
- multi-thread safe. Sun Microsystems provides a patch to solve this problem. To
- get the latest patch for solving this problem, go to
- <jump href="http://sunsolve.sun.com">SunSolve.sun.com</jump> and get the
- appropriate patch for your operating system. For Intel machines running
- Solaris, you need to get Patch ID 104678. For SPARC machines you need to get
- Patch ID #105591.</p>
-
- </a>
- </faq>
-
- <faq title="I just built my own application using the &XercesCName; parser. Why does it crash?">
-
- <q>I just built my own application using the &XercesCName; parser. Why does
- it crash?</q>
-
- <a>
-
- <p>In order to work with the &XercesCName; parser, you have to first
- initialize the XML subsystem. The most common mistake is to forget this
- initialization. Before you make any calls to &XercesCName; APIs, you must
- call XMLPlatformUtils::Initialize(): </p>
-
-<source>
-try {
- XMLPlatformUtils::Initialize();
-}
-catch (const XMLException& toCatch) {
- // Do your failure processing here
-}</source>
-
- <p>This initializes the &XercesCProjectName; system and sets its internal
- variables. Note that you must the include <code>xercesc/util/PlatformUtils.hpp</code> file for this to work.</p>
-
- </a>
- </faq>
-
- <faq title="Why does deleting a transcoded string result in assertion on windows?">
- <q>Why does deleting a transcoded string result in assertion on windows?</q>
- <a>
- <p>Both your application program and the &XercesCName; DLL must use the same *DLL* version of the
- runtime library. If either statically links to the runtime library, the
- problem will still occur.</p>
-
- <p>For example, for a Win32/VC6 build, the runtime library build setting MUST
- be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for
- debug builds.</p>
-
- <p>Or for example for a Win32/BCB6 build, application need to switch to Multithreaded
- runtime to avoid such memory access violation.</p>
-
- <p>To bypass such problem, instead of calling operator delete[] directly, you can use the
- provided function XMLString::release to delete any string that was allocated by the parser.
- This will ensure the string is allocated and deleted by the same DLL and such assertion
- problem should be resolved.</p>
- </a>
- </faq>
-
- <faq title="Can't debug into the &XercesCName; DLL with the MSVC debugger">
-
- <q> The libs/dll's I downloaded keep me from using the debugger in VC6.0. I
- am using the 'D', debug versions of them. "no symbolic information found" is
- what it says. Do I have to compile everything from source to make it work?</q>
-
- <a>
-
- <p>Unless you have the .pdb files, all you are getting with the debug
- library is that it uses the debug heap manager, so that you can compile your
- stuff in debug mode and not be dangerous. If you want full symbolic info for
- the &XercesCName; library, you'll need the .pdb files, and to get those, you'll
- need to rebuild the &XercesCName; library.</p>
-
- </a>
- </faq>
-
- <faq title="First-chance exception in Microsoft debugger">
-
- <q>First-chance exception in DOMPrint.exe (KERNEL32.DLL): 0xE06D7363:
- Microsoft C++ Exception. I am always getting this message when I am using the
- parser. My programs are terminating abnormally. Even the samples are giving
- this exception. I am using Visual C++ 6.0 with latest service pack
- installed.</q>
-
- <a>
-
- <p>&XercesCName; uses C++ exceptions internally, as part of its normal
- operation. By default, the MSVC debugger will stop on each of these with the
- "First-chance exception ..." message.</p>
-
- <p>To stop this from happening do this:</p>
-
- <ul>
- <li>start debugging (so the debug menu appears)</li>
- <li>from the debug menu select "Exceptions"</li>
- <li>from the box that opens select "Microsoft C++ Exception" and set it
- to "Stop if not handled" instead of "stop always".</li>
- </ul>
-
- <p>You'll still land in the debugger if your program is terminating
- abnormally, but it will be at your problem, not from the internal &XercesCName;
- exceptions.</p>
-
- </a>
- </faq>
-
- <faq title="Cannot load message domain, Xerces Panic Error">
- <q>Cannot load message domain, Xerces Panic Error?</q>
- <a>
- <p>If the parser is built with icu message loader (like IBM XML4C binaries),
- you need to make sure that the message library (for the exact name see
- <jump href="faq-distrib-&XercesC3Series;.html#faq-2">FAQ: Which DLLs do I need to distribute
- with my application?</jump>) is located in a directory which is on the library search path.
- Or the message resource file, XercesMessages_en_US.res, is in the directory given at the call to
- XMLPlatformUtils::Initialize(), or is located in the directory pointed to by the environment variable
- XERCESC_NLS_HOME, or at &XercesC3SrcInstallDir;/msg.
- </p>
- <p>If the parser is built with iconv message loader, you need to make sure that the message
- catalog file, XercesMessages_en_US.cat, is in the directory given at the call to XMLPlatformUtils::Initialize(),
- or is located in the directory pointed to by the environment variable XERCESC_NLS_HOME, or
- at &XercesC3SrcInstallDir;/msg.
- </p>
-
- </a>
- </faq>
<faq title="Why my document is valid on some platforms while invalid on others">
<q>Why my document is valid on some platform while invalid on others?</q>
@@ -372,12 +93,12 @@ catch (const XMLException& toCatch) {
zero to the said data if underflow is found.
</p>
<p>The threshold, where the strtod() decides if an underflow occurs, varies on
- platforms. On windows, it is roughly the order of e-308, on Linux, e-325, and
- on AIX, HP and Solaris, e-324.
+ platforms. On Windows, it is roughly the order of e-308, on Linux, e-325, and
+ on AIX, HP-UX and Solaris, e-324.
</p>
<p>So in an instance document, a data of value 1.0e-310 from a type with minExclusive 0,
is considered invalid on windows (since it is converted to 0 and therefore violates
- the minExclusive constraint), but valid on other unix platforms (since it remains
+ the minExclusive constraint), but valid on other Unix platforms (since it remains
the original value).
</p>
<p>The discussion above applies to data in xsd file as well.
@@ -385,39 +106,4 @@ catch (const XMLException& toCatch) {
</a>
</faq>
- <faq title="How do I regenerate the documentation?">
- <q>How do I regenerate the documentation?</q>
- <a>
- <p>To use the internal XML based application that creates the
- documentation, you must have a Java Virtual machine installed
- on your system. The application itself, written in Java, is
- provided in the &XercesC3ToolsInstallDir; distribution. You
- should copy its contents into your <code>&XercesC3SrcInstallDir;</code>
- directory.</p>
-
- <p>To regenerate the documentation, go to the &XercesC3SrcInstallDir;/tools
- directory and start <code>createdocs.sh</code> (for Unix) or
- <code>createdocs.bat</code> (for Windows). The result can be
- found in directory <code>&XercesC3SrcInstallDir;/doc/html</code>.</p>
-
- <p>
- To regenerate the API documentation, you need to have at least
- <jump href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</jump>
- installed on your system.</p>
-
- <p>If you want the API documentation to
- contain dependency graphs, you also need to have <jump
- href="http://www.research.att.com/sw/tools/graphviz/">GraphViz</jump> installed on
- your system.</p>
-
- <p>If you do not have GraphViz, or do not want to use it, you
- have to edit file <code>&XercesC3SrcInstallDir;/doc/Doxyfile</code> and
- change <code>HAVE_DOT = YES</code> into <code>HAVE_DOT = NO</code>.</p>
-
- <p>To actually regenerate the API documentation, go to directory
- <code>&XercesC3SrcInstallDir;/doc/</code> and start Doxygen. The result can be
- found in directory <code>&XercesC3SrcInstallDir;/doc/html/apiDocs</code>.</p>
- </a>
- </faq>
-
</faqs>
diff --git a/doc/faq-contributing.xml b/doc/faq-contributing.xml
index f47c22ae7..59601f002 100644
--- a/doc/faq-contributing.xml
+++ b/doc/faq-contributing.xml
@@ -18,20 +18,20 @@
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
-<faqs title='FAQs for Contributors'>
+<faqs title='Contributing to &XercesCName;'>
<faq title="Submitting Patches">
<q>I have a problem and I think I know how to fix it. How can I
- communicate my ideas to the Xerces team?
+ communicate my ideas to the &XercesCName; team?
</q>
<a>
<p>To maximize the probability that your ideas will grab the
- attention of one of the Xerces developers who knows about the
+ attention of one of the &XercesCName; developers who knows about the
area of the parser you're concerned with, you should follow
these steps:
</p>
<ol>
- <li>Check out and build the most recent Xerces code. For
- instructions on how to do this, see <jump href="&RepURI;">Xerces-C++
+ <li>Check out and build the most recent &XercesCName; code. For
+ instructions on how to do this, see <jump href="&RepURI;">&XercesCName;
Repository Information</jump>. If you do this, you can confirm that your
bug still exists and has not been fixed since the last
release.
@@ -44,10 +44,10 @@
Describe why your solution works.
</li>
<li>
- Prepare a patch to fix Xerces code. To do this, when you
+ Prepare a patch to fix &XercesCName; code. To do this, when you
have applied your changes to a local copy of the most
- recent xerces source code, do <code>svn diff file</code>
- for each file you've changed.
+ recent &XercesCName; source code, do <code>svn diff file</code>
+ for each file you have changed.
Keep in mind the coding guidelines for &XercesCName; as
described below.
</li>
@@ -57,9 +57,9 @@
apply.
</li>
<li>
- Submit a bug report to the Xerces-C++ bug database as
+ Submit a bug report to the &XercesCName; bug database as
described on the <jump href="&BugURI;">Bug-Reporting</jump> page.
- Pick the product "Xerces-C++" (remembering to attach your patches
+ Pick the product "&XercesCName;" (remembering to attach your patches
and test code) or, if you think your patch might need some discussion,
post it to the <jump href="&MailURI;">developer mailing list</jump>.
</li>
@@ -80,11 +80,9 @@
<ul>
<li>We don't try to enforce binary compatibility between new versions and releases.</li>
<li>New versions and releases will be delivered when a certain number of bug fixes/new features have been added
- (as decided by the committers) or when a dependent product, such as XALAN, wants to ship a new release that uses new Xerces features.</li>
+ (as decided by the committers).</li>
<li>New modification levels will almost never be issued, the only exception is a showstopper bug encountered within
- a release. if no commit has been made on the trunk which would result in binary incompatibility, and no commit has been made that is not thought to
- be release-quality, then the modification release can be created by tagging the trunk; otherwise, a branch (new release) will need to be created and the show stopper
- fixed there.</li>
+ a release.</li>
<li>Any normal bug is fixed only in the HEAD branch (latest development code).</li>
</ul>
@@ -108,14 +106,14 @@
<li>Change the order of data members in the class declaration (other than STATIC members).</li>
<li>Change the class hierarchy (other than adding new classes).</li>
</ul>
- <li>Methods that are deprecated should be marked with the JavaDoc tag @deprecated in the header file.</li>
+ <li>Methods that are deprecated should be marked with the Doxygen tag @deprecated in the header file.</li>
</ul>
<li>x.x.x to x.y.z: the API is source code compatible but not binary compatible (a recompilation of an application that uses the public headers of &XercesCName; should work).</li>
<ul>
<li>This means that to maintain release to release source code compatibility the signature of public methods can only be
changed by adding default parameters.</li>
<li>Signatures of private and protected methods can be changed and/or removed.</li>
- <li>Methods that are deprecated should be marked with the JavaDoc tag @deprecated in the header file.</li>
+ <li>Methods that are deprecated should be marked with the Doxygen tag @deprecated in the header file.</li>
</ul>
<li>x.x.x to a.b.c: the API may not be source code compatible and is not binary compatible (a recompilation of an application using &XercesCName; may fail).</li>
<ul>
@@ -161,15 +159,15 @@
<li>Use a tab size of 4 and insert them as spaces instead of keeping tabs.</li>
<li>The code is written to be platform independent. Platform specific code should only be in the
- util/Platforms, util/Transcoders, util/MsgLoaders, and util/NetAccessors directories.</li>
+ util/FileManagers, util/MutexManagers, util/Transcoders, util/MsgLoaders, and util/NetAccessors directories.</li>
<li>The header file name and the source file name should both be named corresponding to the primary
class they contain. For example class StringPool should be in the header file StringPool.hpp and in
the source file StringPool.cpp.</li>
- <li>In general, code should be documented with comments. Use JavaDoc tags to describe methods.</li>
+ <li>In general, code should be documented with comments. Use Doxygen tags to describe methods.</li>
- <li>The naming convention for ENUMS should be choosen to be unique and descriptive
+ <li>The naming convention for enumerations should be chosen to be unique and descriptive
(i.e. INVALID or UNKNOWN) to avoid colliding with predefined macros in other
products. The current style of using ALL CAP enums should be phased out with
Mixed Case instead, except for names specified in standards (for example, TEXT_NODE
@@ -178,159 +176,4 @@
</ol>
</a>
</faq>
-
- <faq title="Release Preparation">
- <q>How does one do a Xerces-C release?
- </q>
- <a>
- <p>Just follow these steps:
- </p>
- <ol>
- <li>Update the release information in the following files:<br/>
-
- <code>projects/Win32/VC6/xerces-all/XercesLib/XercesLib.dsp</code>
- <code>projects/Win32/VC6/xerces-all/XercesLib/XercesLib.mak</code>
- <code>projects/Win32/VC7.1/xerces-all/XercesLib/XercesLib.vcproj</code>
- <code>projects/Win32/VC8/xerces-all/XercesLib/XercesLib.vcproj</code>
- <br/>
- <code>projects/MacOS/Xcode/XercesLib/Info-XercesLib.plist</code>
- <code>scripts/packageBinaries.pl</code>
- <br/>
- <code>src/xercesc/configure.in</code>
- <br/>
- <code>src/xercesc/com/xml4com.idl</code>
- <code>src/xercesc/util/Platforms/Win32/Version.rc</code>
- <code>src/xercesc/util/XercesVersion.hpp</code>
- <code>src/xercesc/util/MsgLoaders/ICU/ICUMsgLoader.cpp</code>
- <code>src/xercesc/util/MsgLoaders/ICU/resources/res-file-list-unix.txt</code>
- <code>src/xercesc/util/MsgLoaders/ICU/resources/res-file-list-wins.txt</code>
- <code>src/xercesc/util/MsgLoaders/ICU/resources/res-file-list.txt</code>
- <br/>
- <code>version.incl</code>
- <br/>
- <code>xerces-c.spec</code>
- <br/>
- <code>doc/Doxyfile</code>
- <br/>
- <code>doc/style/dtd/entities.ent</code>
-
- </li>
-
- <li>Update the release documentation in the following files:<br/>
- <code>doc/migration.xml</code>
- <br/>
- <code>doc/migration_archive.xml</code>
- <br/>
- <code>doc/releases.xml</code>
- <br/>
- <code>doc/releases_archive.xml</code>
- <br/>
- <code>doc/feedback.xml</code>
- <br/>
- <code>credits.txt</code>
- </li>
-
- <li>Build and test the release on the platforms that binaries are being produced for.
- <br/>The source packages should be named xerces-c-src_x_y_z.zip/tar.gz. In order for
- rpm to work correctly the actual directory containing the source that will be
- zipped/tarred up should be xerces-c-src_x_y_z.
- <br/>The binary packages should be named xerces-c_x_y_z.zip/tar.gz.
- </li>
-
- <li>
- Generate PGP/GNUPG signatures for dist binaries and source packages.<br/>
- That is, add public key to the SVN <code>KEYS</code> file if necessary
- and make sure public key is on a key server or two. You will also need
- to update the KEYS file on the website:
- <br/>
- <code>scp KEYS username@minotaur.apache.org:/www/www.apache.org/dist/xml/xerces-c</code>
- </li>
-
- <li>Upload the binaries and signatures to the dist section of
- the website, from the directory containing the binaries:
- <br/>
- <code>scp * username@minotaur.apache.org:/www/www.apache.org/dist/xml/xerces-c/binaries</code>
- </li>
-
- <li>Upload the source packages and signatures to the dist section of
- the website, from the directory containing the sources:
- <br/>
- <code>scp * username@minotaur.apache.org:/www/www.apache.org/dist/xml/xerces-c/source</code>
- </li>
-
- <li>Logon to minotaur.
- <br/>
- <code>ssh minotaur.apache.org</code>
- </li>
-
- <li>
- Generate md5 signatures for dist binaries and sources on minotaur using:
- <br/>
- <code>md5 -r xerces-c_x_y_z.tar.gz > xerces-c_x_y_z.tar.gz.md5</code>
- </li>
-
- <li>Make sure the packages have the correct permissions (chmod 664*).</li>
-
- <li>Remove the previous release source and binaries (double checked that they
- are archived) in the source and binaries directories. Remove the links in the
- /www/www.apache.org/dist/xml/xerces-c directory (*current* that were pointing
- at the old sources in the source directory).
- </li>
-
- <li>Create the new links for the source (do for each file including asc and md5):
- <br/>
- <code>ln -s ./source/xerces-c-src_x_y_z.zip xerces-c-current.zip</code>
- </li>
-
- <li>Go to the archive, /www/archive.apache.org/dist/xml/xerces-c and create a
- directory for the previous release (Xerces-C_x_y_a). Move over the contents of
- the source and binaries directories to this new directory. Remove the *current* links.
- </li>
-
- <li>Update the archive.
- <br/>
- <code>cd /www/www.apache.org/dist/xml/xerces-c</code>
- <br/>
- <code>cp -R * /www/archive.apache.org/dist/xml/xerces-c</code>
- </li>
-
- <li>Verify that the downloads are available. Note that it can take up to 24 hours
- to for the mirrors to be updated.
- </li>
-
- <li>Update the website by taking a binary package and extracting the doc/html directories.
- The web pages are stored in /www/xml.apache.org/xerces-c. You will also need to update
- the documentation pdf in the pdf directory (which has both a pdf and pdf.tar.gz). Recommend
- copying the new documentation over the existing files. Be sure to change the permissions
- on the files and directories:
- <br/>
- <code>find . -type f -exec chmod 664 {} ;</code>
- <br/>
- <code>find . -type d -exec chmod 775 {} ;</code>
- <br/>If the binaries are for different platforms you may also need to update the
- download.html file to point to the new binaries.
- <br/>Verify that the website is updated (may take a while to be refreshed on the
- real webserver).
- </li>
-
- <li>Send out an announcement e-mail to the c-dev@xerces.apache.org and c-users@xerces.apache.org mailing lists
- and cc the announcements@xml.apache.org and pmc@xerces.apache.org mailing lists.
- </li>
-
- <li>Update the list of versions in Jira for xerces-c.
- </li>
-
- <li>Tag the release in SVN
- (tags for releases usually have the form Xerces-C_x_y_z
- where x.y.z is the Xerces-C release number) by doing:
- <br/>
- <code>svn copy https://svn.apache.org/repos/asf/xerces/c \
- https://svn.apache.org/repos/asf/xerces/c/tags/Xerces-C_x_y_z \
- -m "Tagging the Xercesc x.y release" </code>
- <br/>For more information on tagging see http://svnbook.red-bean.com/nightly/en/svn.branchmerge.tags.html.
- </li>
- </ol>
- </a>
- </faq>
-
</faqs>
diff --git a/doc/faq-distrib.xml b/doc/faq-distrib.xml
index ed0cc5b05..b49b90bbe 100644
--- a/doc/faq-distrib.xml
+++ b/doc/faq-distrib.xml
@@ -20,125 +20,58 @@
<faqs title="Distributing &XercesCName;">
- <faq title="What are the differences between Xerces-C and XML4C?">
- <q>What are the differences between Xerces-C and XML4C?</q>
+ <faq title="Can I use &XercesCName; in my product?">
+ <q>Can I use &XercesCName; in my product?</q>
<a>
+ <p>Most likely yes. &XercesCName; is distributed under
+ the terms of the Apache Software License version 2.0
+ which is a fairly permissive license. In particular,
+ it allows you to distribute your application in
+ binary form without requiring you to also release
+ the source code. Read the license agreement for more
+ information and if you still have further questions,
+ then please address them to the
+ <jump href="&MailURI;">&XercesCName; user mailing list</jump>.</p>
- <p>By default &XercesCName; has intrinsic support for ASCII, UTF-8, UTF-16
- (Big/Small Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037, IBM1047 and
- IBM1140 encodings, ISO-8859-1 (aka Latin1) and Windows-1252. This means that it can parse
- input XML files in these above mentioned encodings.</p>
-
- <p>However, if you wish to parse XML files in any other
- encodings, say in Shift-JIS, Big5 etc., then you will
- need to build &XercesCName; with the <jump
- href="http://icu-project.org/">
- International Components for Unicode (ICU)</jump> library.</p>
-
-
- <p><jump href="http://alphaworks.ibm.com/tech/xml4c">XML4C</jump>
- is simply &XercesCName; built with ICU.</p>
</a>
</faq>
- <faq title="Which DLL's do I need to distribute with my application?">
- <q>Which DLL's do I need to distribute with my application?</q>
+ <faq title="Which files do I need to distribute with my application?">
+ <q>Which files do I need to distribute with my application?</q>
<a>
-
<p>You only need to distribute <em>one</em> file:<br></br>
- &XercesC3WindowsDLL;.dll for Windows, or<br/>
- &XercesC3UnixLib;&XercesC3UnixSoName;.a for AIX, or<br/>
- &XercesC3UnixLib;.so.&XercesC3UnixSoName; for Solaris/Linux, or<br/>
- &XercesC3UnixLib;.sl.&XercesC3UnixSoName; for HP-UX on PA-RISC, or<br/>
- &XercesC3UnixLib;.so.&XercesC3UnixSoName; for HP-UX on IA64, or<br/>
- &XercesC3UnixLib;.&XercesC3UnixSoName;.dylib for Mac OS X.
+ &XercesC3WindowsDLL;.dll for Windows<br/>
+ &XercesC3UnixLib;-&XercesC3UnixSoVersion;.a for AIX<br/>
+ &XercesC3UnixLib;-&XercesC3UnixSoVersion;so. for Solaris/Linux<br/>
+ &XercesC3UnixLib;-&XercesC3UnixSoVersion;.sl for HP-UX on PA-RISC<br/>
+ &XercesC3UnixLib;-&XercesC3UnixSoVersion;.so for HP-UX on IA64<br/>
+ &XercesC3UnixLib;-&XercesC3UnixSoVersion;.dylib for Mac OS X
</p>
- <p>However, if you are using the ICU transcoder then in
- <em>addition</em> to the library file
- mentioned above, you also need to ship:</p>
-
- <ol>
- <li><em>ICU shared library file</em>:<br></br>
- icuuc*.dll for Windows, or<br></br>
- libicuuc*.a for AIX, or<br></br>
- libicuuc*.so for Solaris/Linux, or<br></br>
- libicuuc*.sl for HP-UX on PA-RISC, or<br></br>
- libicuuc*.so for HP-UX on IA64, or<br></br>
- libicuuc*.dylib for Mac OS X.</li>
-
- <li><em>ICU converter data shared library file:</em><br></br>
- icudt*.dll for Windows, or<br></br>
- libicudt*.a for AIX, or<br></br>
- libicudt*.so for Solaris/Linux, or<br></br>
- libicudt*.sl for HP-UX on PA-RISC, or<br></br>
- libicudt*.so for HP-UX on IA-64, or<br></br>
- libicudt*.dylib for Mac OS X.</li>
-
- <li><em>The &XercesCName; Message file:</em><br></br>
- XercesMessages*.dll for Windows, or<br></br>
- libXercesMessages*.a for AIX, or<br></br>
- libXercesMessages*.so for Solaris/Linux, or<br></br>
- libXercesMessages*.sl for HP-UX on PA-RISC, or<br></br>
- libXercesMessages*.so for HP-UX on IA64, or<br></br>
- libXercesMessages*.dylib for Mac OS X.</li>
- </ol>
- </a>
- </faq>
-
- <faq title="How do I package the sources to create a binary drop?">
-
- <q>How do I package the sources to create a binary drop?</q>
+ <p>Note, however, that if you built &XercesCName; with dependencies
+ on other libraries (e.g., ICU for transcoder support or libcurl
+ for net accessor support) then you will need to ship those
+ libraries as well.</p>
- <a>
- <p>You have to first compile the sources inside your IDE to
- create the required DLLs and EXEs. Then you need to copy
- over the binaries to another directory for the binary
- drop. A perl script has been provided to give you a jump
- start. You need to install perl on your machine for the script to work.
- If you have changed your source tree, you have to modify the script to suit
- your current directory structure. To invoke the
- script, go to the \<&XercesCProjectName;>\scripts directory, and type:</p>
-<source>perl packageBinaries.pl</source>
-
- <p>You will get a message that somewhat looks like this (changes always happen,
- we are evolving you see!): </p>
-
-<source>Usage is: packageBinaries <options>
-options are: -s <source_directory>
- -o <target_directory>
- -c <C compiler name> (e.g. gcc or xlc_r)
- -x <C++ compiler name> (e.g. g++ or xlC_r)
- -m <message loader> can be 'inmem', 'icu' or 'iconv'
- -n <net accessor> can be 'fileonly' or 'libcurl'
- -t <transcoder> can be 'icu' or 'native'
- -r <thread option> can be 'pthread' or 'dce' (only used on HP-11)
- -h to get help on these commands
-Example: perl packageBinaries.pl -s$HOME/&XercesC3SrcInstallDir;
- -o$HOME/&XercesC3InstallDir;
- -cgcc -xg++ -minmem
- -nfileonly -tnative</source>
-
- <p>Make sure that your compiler can be invoked from the command line and
- follow the instructions to produce a binary drop.</p>
+ <p>You can also link your application to a static version
+ of the &XercesCName; library in which case you won't need
+ to distribute any extra libraries.</p>
</a>
</faq>
- <faq title="I do not see binaries for my platform. When will they be available?">
+ <faq title="I do not see a binary for my platform. When will it be available?">
- <q>I do not see binaries for my platform. When will they be available?</q>
+ <q>I do not see a binary for my platform. When will it be available?</q>
<a>
- <p>The reason why you see binaries only for some specific
+ <p>The reason why you see binaries only for some specific
platforms is that we have had the maximum requests for
them. Moreover, we have limited resources and hence cannot
publish binaries for every platform. If you wish to
contribute your time and effort in building binaries for a
specific platform/environment then please send a mail to the
- <jump href="&MailURI;">&XercesCName; developer mailing list</jump>.
- We can definitely use any extra help in this open source
- project</p>
+ <jump href="&MailURI;">&XercesCName; developer mailing list</jump>.</p>
</a>
</faq>
@@ -148,14 +81,13 @@ Example: perl packageBinaries.pl -s$HOME/&XercesC3SrcInstallDir;
<q>When will a port to my platform be available?</q>
<a>
- <p>We would like to see &XercesCProjectName; ported to as
- many platforms as there are. Again, due to limited resources
- we cannot do all the ports. We will help you make this port
- happen. Here are some <jump
+ <p>We would like to see &XercesCName; ported to as
+ many platforms as practical. However, due to limited resources
+ we cannot do all the ports. Here are the <jump
href="program-others-&XercesC3Series;.html#PortingGuidelines">Porting
Guidelines</jump>.</p>
- <p>We strongly encourage you to submit the changes that
+ <p>We encourage you to submit the changes that
are required to make it work on another platform. We will
incorporate these changes in the source code base and make
them available in the future releases.</p>
@@ -165,82 +97,4 @@ Example: perl packageBinaries.pl -s$HOME/&XercesC3SrcInstallDir;
.</p>
</a>
</faq>
-
-
- <faq title="How can I port &XercesCProjectName; to my favourite platform?">
- <q>How can I port &XercesCProjectName; to my favourite platform?</q>
- <a>
- <p>Here are some <jump
- href="program-others-&XercesC3Series;.html#PortingGuidelines">Porting
- Guidelines</jump>.</p>
- </a>
- </faq>
-
-
-
- <faq title="What application do you use to create the documentation?">
- <q>What application do you use to create the documentation?</q>
- <a>
- <p>We have used an internal XML based application to create the
- documentation. The documentation files are all written in XML and the
- application, internally codenamed StyleBook, makes use of XSL to transform
- it into an HTML document that you are seeing right now.
- It is currently available on the
- <jump href="http://xml.apache.org/">Apache</jump> open source website as
- <jump href="http://xml.apache.org/cocoon/index.html">Cocoon</jump>.</p>
-
- <p>The API documentation is generated using
- <jump href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</jump> and
- <jump href="http://www.research.att.com/sw/tools/graphviz/">GraphViz</jump>.</p>
-
- <p>See <jump href="faq-build-&XercesC3Series;.html#faq-18">
- FAQ: Regenerating (API) documentation?</jump></p>
-
- </a>
- </faq>
-
-
- <faq title="Can I use &XercesCProjectName; in my product?">
- <q>Can I use &XercesCProjectName; in my product?</q>
- <a>
- <p>Yes! Read the license agreement first and if you still
- have further questions, then please address them to the
- <jump href="&MailURI;">&XercesCName; user mailing list</jump>.</p>
-
- </a>
-</faq>
-
-
- <faq title="How do I uninstall &XercesCName;?">
- <q>How do I uninstall &XercesCName;?</q>
- <a>
- <p>&XercesCName; only installs itself in a single directory and does not
- set any registry entries. Thus, to uninstall, you only need to remove the
- directory where you installed it, and all &XercesCName; related files will be
- removed.</p>
- </a>
- </faq>
- <faq title="I am getting a tar checksum error on Solaris. What's the problem?">
- <q>I am getting a tar checksum error on Solaris. What's the problem?</q>
- <a>
- <p>The problem is caused by a limitation in the original tar spec, which
- prevented it from archiving files with long pathnames. Unfortunately,
- various current versions of tar use different extensions for eliminating
- this restriction which are incompatible with each other (or they do not
- remove the restriction at all). Rather than altering the pathnames for
- the &XercesCName; package, which would make them compatible with the original
- tar spec but make it more difficult to know what was where, it was
- decided to use GNU tar (gtar), which handles arbitrarily long pathnames
- and is freely available on every platform on which &XercesCName; is
- supported. If you don't already have GNU tar installed on your system,
- you can obtain it from the Free Software Foundation
- <jump href="http://www.gnu.org/software/tar/tar.html">
- http://www.gnu.org/software/tar/tar.html</jump>. For additional
- background information on this problem, see the online manual
- <jump href="http://www.gnu.org/manual/tar/html_node/tar_117.html#SEC112">
- GNU tar and POSIX tar </jump> for the utility.
- </p>
- </a>
- </faq>
</faqs>
-
diff --git a/doc/faq-other.xml b/doc/faq-other.xml
index c8160b752..449a9eafa 100644
--- a/doc/faq-other.xml
+++ b/doc/faq-other.xml
@@ -19,93 +19,23 @@
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
<faqs title="Other &XercesCName; Questions">
- <faq title="Are the Xerces parsers Year-2000-compliant?">
- <q>Are the Xerces parsers Year-2000-compliant?</q>
- <a>
- <p>Yes, Xerces-J and Xerces-C are Year 2000 compliant.
- They do not currently use any dates at all (at least until the XML
- Schema date datatypes are fully supported). However, you may still
- have Y2K problems if the underlying OS or Java implementation has
- problems with dates past year 2000 (e.g. OS calls which accept or
- return year numbers).</p>
- <p>Most (UNIX) systems store dates internally as signed 32-bit
- integers which contain the number of seconds since 1st January 1970,
- so the magic boundary to worry about is the year 2038 and not 2000.
- But modern operating systems shouldn't cause any trouble at all.</p>
-
- <p>The Apache Xerces project is an open-source software product
- of the Apache Software Foundation. The project and the Foundation
- cannot and does not offer legal assurances regarding any suitability
- of the software for your application. There are several commercial
- support organizations and derivative products available that may be
- able to certify the software and provide you with any assurances you
- may require (IBM's Websphere product is one of them).</p>
- <p>The Apache HTTP server software is distributed with the following
- disclaimer, found in the software license: </p>
-<source>THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
-ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
-USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
-OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGE.</source>
- </a>
- </faq>
-
<faq title="How do I determine the version of &XercesCName; I am using?">
<q>How do I determine the version of &XercesCName; I am using?</q>
<a>
-
<p>The version string for &XercesCName; is in one of the header files. Look
inside the file <code>src/xercesc/util/XercesVersion.hpp</code> or, in the binary distribution,
look in <code>include/xercesc/utils/XercesVersion.hpp</code>. </p>
<p>If you don't have the header files, you have to find the version
information from the shared library name. On Windows right click on
- the DLL name &XercesC3WindowsDLL;.dll in the bin directory and look up
- properties. The version information may be found on the Version tab.</p>
+ the DLL name in the bin directory and look up
+ properties. The version information can be found in the Version tab.</p>
- <p>On AIX, just look for the library name &XercesC3UnixLib;&XercesC3UnixSoName;.a (or
- &XercesC3UnixLib;.so.&XercesC3UnixSoName; on Solaris/Linux/IA64 HP-UX
- and &XercesC3UnixLib;.sl.&XercesC3UnixSoName; on PA-RISC HP-UX). The
- version number is indicated in the name of the library.</p>
+ <p>On UNIX/Linux/Mac OS X platforms the version is
+ embedded into the library name.</p>
</a>
</faq>
- <faq title="I can't use C++. Do you have a Java version?">
-
- <q>I can't use C++. Do you have a Java version?</q>
-
- <a>
-
- <p>Yes. The Xerces family of products also has a Java version. More
- information is available at:
- <jump href="http://xerces.apache.org/xerces2-j/index.html">
- http://xerces.apache.org/xerces2-j/index.html</jump></p>
-
- </a>
- </faq>
-
-
- <faq title="Where can I find additional information on XML?">
-
- <q>Where can I find additional information on XML?</q>
-
- <a>
-
- <p>The Web. <jump href="http://www.oasis-open.org/cover/xml.html">
- http://www.oasis-open.org/cover/xml.html</jump> is an excellent place to start,
- with links to overviews, FAQs, specifications, industry news, applications and
- other software, related standards, etc.</p>
-
- </a>
- </faq>
-
<faq title="Is there any kind of support available for &XercesCName;?">
<q>Is there any kind of support available for &XercesCName;?</q>
<a>
@@ -114,9 +44,7 @@ SUCH DAMAGE.</source>
<p>Every volunteer project obtains its strength from the people involved in
it. Mailing lists provide a simple and effective communication mechanism. You
are welcome to join any of these mailing lists (or all of them if you wish).
- You can choose to lurk, or to actively participate. It is up to you. Before you
- join these lists, you should look over the resources in the Reference Library
- section</p>
+ You can choose to lurk, or to actively participate. It is up to you.</p>
<p>Instructions for subscribing as well as archives are available at the
<jump href="&MailURI;">&XercesCName; mailing lists</jump> page.</p>
@@ -134,53 +62,4 @@ SUCH DAMAGE.</source>
</a>
</faq>
- <faq title="I have a patch to the &XercesCName; source code. How do I submit it?">
- <q>I have a patch to the &XercesCName; source code. How do I submit it?</q>
- <a>
- <p>Mail it to the <jump href="&MailURI;">&XercesCName;
- development mailing list</jump>. Its also a good idea to add a report to
- <jump href="&BugURI;">&XercesCName; bug database</jump> to track the issue.
- There are no set rules about
- how or what must be included -- if you have fixed a problem or enhanced the code
- in some way, we really would like to get your changes, and will take them in
- any reasonable form.</p>
-
- <p>Generally a diff of the changed files against the current sources from the
- <jump href="&RepURI;">&XercesCName; repository</jump> is good, along with some kind of
- description of what the change is. (Working with the current sources is important!)</p>
- </a>
- </faq>
-
- <faq title="Where can I get predefined character entity definitions?">
-
- <q>Where can I get predefined character entity definitions??</q>
-
- <a>
-
- <p> Download <jump href="http://www.w3.org/TR/xhtml1/xhtml1.zip">
- http://www.w3.org/TR/xhtml1/xhtml1.zip. </jump></p>
-
- </a>
- </faq>
-
- <faq title="Does &XercesCName; support XPath?">
-
- <q> Does &XercesCName; support XPath?</q>
-
- <a>
-
- <p>The &XercesCName; &XercesC3Version; only has partial XPath implementation
- for the purposes of handling Schema identity constraints.
- The same engine is made available through the DOMDocument::evaluate API to
- let the user perform simple XPath queries involving DOMElement nodes only,
- with no predicate testing and allowing the "//" operator only as the initial
- step; for full XPath support, you can refer to the
- <jump href="http://xqilla.sourceforge.net">XQilla</jump> and
- <jump href="http://xml.apache.org/xalan-c/overview.html">Apache Xalan C++</jump>
- Open Source projects.
- </p>
-
- </a>
- </faq>
-
</faqs>
diff --git a/doc/faq-parse.xml b/doc/faq-parse.xml
index dc7de24cf..cbf74d650 100644
--- a/doc/faq-parse.xml
+++ b/doc/faq-parse.xml
@@ -18,46 +18,41 @@
<!DOCTYPE faqs SYSTEM "sbk:/style/dtd/faqs.dtd">
-<faqs title="Programming/Parsing FAQs">
+<faqs title="Programming &XercesCName;">
- <faq title="Does &XercesCName; support Schema?">
+ <faq title="Does &XercesCName; support XML Schema?">
<q> Does &XercesCName; support Schema?</q>
<a>
-
- <p>Yes. The &XercesCName; &XercesC3Version; contains an implementation
+ <p>Yes, &XercesCName; &XercesC3Version; contains an implementation
of the W3C XML Schema Language, a recommendation of the Worldwide Web Consortium
available in three parts:
<jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump> and
<jump href="http://www.w3.org/TR/xmlschema-1/">XML Schema: Structures</jump> and
<jump href="http://www.w3.org/TR/xmlschema-2/">XML Schema: Datatypes</jump>.
- We consider this implementation complete. See
- <jump href="schema-&XercesC3Series;.html#limitation">the Schema page</jump> for limitations.</p>
+ We consider this implementation complete. See the
+ <jump href="schema-&XercesC3Series;.html#limitation">XML Schema Support</jump> page for limitations.</p>
</a>
</faq>
- <faq title="Why &XercesCName; does not support this particular Schema feature?">
+ <faq title="Does &XercesCName; support XPath?">
- <q> Why &XercesCName; does not support this particular Schema feature?</q>
+ <q> Does &XercesCName; support XPath?</q>
<a>
- <p>The &XercesCName; &XercesC3Version; contains an implementation
- of the W3C XML Schema Language, a recommendation of the Worldwide Web Consortium
- available in three parts:
- <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump> and
- <jump href="http://www.w3.org/TR/xmlschema-1/">XML Schema: Structures</jump> and
- <jump href="http://www.w3.org/TR/xmlschema-2/">XML Schema: Datatypes</jump>.
- We consider this implementation complete. See
- <jump href="schema-&XercesC3Series;.html#limitation">the Schema page</jump> for limitations.</p>
-
- <p>If you find any Schema feature which is specified in the W3C XML Schema Language
- Recommendation does not work with &XercesCName; &XercesC3Version;, we encourage
- the submission of bugs as described in
- <jump href="&BugURI;">Bug-Reporting</jump> page.
- </p>
+ <p>&XercesCName; &XercesC3Version; provides partial XPath 1 implementation
+ for the purposes of handling XML Schema identity constraints.
+ The same engine is made available through the DOMDocument::evaluate API to
+ let the user perform simple XPath queries involving DOMElement nodes only,
+ with no predicate testing and allowing the "//" operator only as the initial
+ step. For full XPath 1 and 2 support refer to the
+ <jump href="http://xqilla.sourceforge.net">XQilla</jump> and
+ <jump href="http://xml.apache.org/xalan-c/overview.html">Apache Xalan C++</jump>
+ open source projects.
+ </p>
</a>
</faq>
@@ -82,7 +77,7 @@ catch (const XMLException& toCatch) {
}</source>
<p>This initializes the &XercesCProjectName; system and sets its internal
- variables. Note that you must the include <code>xercesc/util/PlatformUtils.hpp</code> file for this to work.</p>
+ variables. Note that you must include the <code>xercesc/util/PlatformUtils.hpp</code> file for this to work.</p>
</a>
</faq>
@@ -90,99 +85,19 @@ catch (const XMLException& toCatch) {
<faq title="Is it OK to call the XMLPlatformUtils::Initialize/Terminate pair of routines multiple times in one program?">
<q>Is it OK to call the XMLPlatformUtils::Initialize/Terminate pair of routines multiple times in one program?</q>
<a>
- <p>Yes. Since &XercesCName; 1.5.2, the code has been enhanced so that
- calling XMLPlatformUtils::Initialize/Terminate pair of routines
- multiple times in one process is now allowed.
- </p>
-
- <p>But the application needs to guarantee that only one thread has entered either the
- method XMLPlatformUtils::Initialize() or the method XMLPlatformUtils::Terminate() at any
- one time.</p>
+ <p>Yes. Note, however, that the application needs to guarantee that the
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ methods are called from the same thread (usually the initial
+ thread executing main()) or proper synchronization is performed
+ by the application if multiple threads call
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ concurrently.</p>
<p>If you are calling XMLPlatformUtils::Initialize() a number of times, and then follow with
XMLPlatformUtils::Terminate() the same number of times, only the first XMLPlatformUtils::Initialize()
will do the initialization, and only the last XMLPlatformUtils::Terminate() will clean up
the memory. The other calls are ignored.
</p>
-
- <p>To ensure all the memory held by the parser are freed, the number of XMLPlatformUtils::Terminate() calls
- should match the number of XMLPlatformUtils::Initialize() calls.
- </p>
-
- <p>
- Consider the following code snippets (for illustration simplicity the following
- sample code is not coded in try/catch clause):
- </p>
-
-<source>
-// The XMLPlatformUtils::Initialize/Terminate calls are paired.
-{
- // Initialize the parser
- XMLPlatformUtils::Initialize();
-
- SAXParser* parser = new SAXParser;
- parser->parse(xmlFile);
- delete parser;
-
- // Free all memory that was being held by the parser
- XMLPlatformUtils::Terminate();
-
- // Initialize the parser
- XMLPlatformUtils::Initialize();
-
- parser = new SAXParser;
- parser->parse(xmlFile);
- delete parser;
-
- // Free all memory that was being held by the parser
- XMLPlatformUtils::Terminate();
-}
-</source>
-
-<source>
-// calls XMLPlatformUtils::Initialize() three times
-// then calls XMLPlatformUtils::Terminate() numerous times
-{
- // Initialize the parser
- XMLPlatformUtils::Initialize();
-
- // The next two calls are no-op
- XMLPlatformUtils::Initialize();
- XMLPlatformUtils::Initialize();
-
- SAXParser* parser = new SAXParser;
- parser->parse(xmlFile);
- delete parser;
-
- // The first two XMLPlatformUtils::Terminate() calls are no-op
- XMLPlatformUtils::Terminate();
- XMLPlatformUtils::Terminate();
-
- // This third XMLPlatformUtils::Terminate() will free all memory that was being held by the parser
- XMLPlatformUtils::Terminate();
-
- // This extra fourth XMLPlatformUtils::Terminate() call is no-op.
- // However calling XMLPlatformUtils::Terminate() without a matching XMLPlatformUtils::Initialize()
- // is dangerous and should be avoided.
- XMLPlatformUtils::Terminate();
-}
-</source>
- </a>
- </faq>
-
- <faq title="Why does my application crash or hang if XMLPlatformUtils::Initialize()/Terminate() pair is called more than once?">
-
- <q>Why does my application crash or hang if XMLPlatformUtils::Initialize()/Terminate() pair is called more than once?</q>
-
- <a>
-
- <p>Please make sure you are using the &XercesCName; 1.5.2 or up.
- </p>
-
- <p>Earlier version of &XercesCName; does not allow XMLPlatformUtils::Initialize()/Terminate()
- pair to be called more than once or has a problem.
- </p>
-
</a>
</faq>
@@ -197,8 +112,7 @@ catch (const XMLException& toCatch) {
destructed when going out of scope) should be called after XMLPlatformUtils::Terminate().
</p>
<p>
- For example consider the following code snippets which is incorrect
- (for illustration simplicity the following sample code is not coded in try/catch clause):
+ For example consider the following code snippet which is incorrect:
</p>
<source>
@@ -211,7 +125,7 @@ catch (const XMLException& toCatch) {
<p>The XercesDOMParser object "parser" is destructed when going out of scope at line 5 before the closing
brace. As a result, XercesDOMParser destructor is called at line 5 after
- XMLPlatformUtils::Terminate() which is wrong. Correct code should be:
+ XMLPlatformUtils::Terminate() which is incorrect. Correct code should be:
</p>
<source>
@@ -227,73 +141,14 @@ catch (const XMLException& toCatch) {
<p>The extra pair of braces (line 2a and 3a) ensures that all implicit destructors are called
before terminating &XercesCName;.</p>
- <p>In addition the application also needs to guarantee that only one thread has entered either the
- method XMLPlatformUtils::Initialize() or the method XMLPlatformUtils::Terminate() at any
- one time.
- </p>
- </a>
- </faq>
-
- <faq title="I'm suddenly getting segfaults with Xerces-C 2.3.0;
- why might this be?">
+ <p>Note also that the application needs to guarantee that the
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ methods are called from the same thread (usually the initial
+ thread executing main()) or proper synchronization is performed
+ by the application if multiple threads call
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ concurrently.</p>
- <q>I'm suddenly getting segfaults with Xerces-C 2.3.0;
- why might this be?</q>
- <a>
- <p>The introduction of pluggable memory management into
- Xerces-C, one of the main features of 2.3.0, means that
- application writers have to be more conscious about
- destructors being invoked implicitly after a call to
- XMLPlatformUtils::Terminate(). For example, the
- following code is guaranteed to produce a segmentation
- fault under Xerces-C 2.3.0, while it happened to work
- under previous versions (in fact, this was how our
- SAXPrint sample was formerly written;
- try-catch blocks removed for brevity):
- </p>
-<source>
-void myParsingFunction()
-{
- XMLPlatformUtils::Initialize();
- SAXParser parser;
- //parser.various method calls
- XMLPlatformUtils::Terminate();
-} // seg fault here!
-</source>
- <p>The reason this will produce a segmentation fault is
- that any dynamic memory the SAXParser (or any other of
- Xerces's parsers) needs to allocate is now allocated
- by default by a static object owned by XMLPlatformUtils.
- When the XMLPlatformUtils::Terminate() call is made, this
- object is destroyed--and, consequently, so are all the
- objects that it directly created. This includes all the
- objects dynamically allocated by the SAXParser. When the
- parser object goes out of scope, its destructor is
- invoked, and this attempts to destroy all the objects
- that it created--which have of course just been destroyed
- by the static MemoryManager in XMLPlatformUtils.
- </p>
- <p>
- To avoid this, one must either explicitly scope the
- parser object inside calls to
- XMLPlatformUtils::Initialize() and
- XMLPlatformUtils::Terminate(), or dynamically allocate
- the parser object and destroy it explicitly before the
- call to XMLPlatformUtils::Terminate() is made.
- </p>
- <p>Another way of producing segmentation faults--that again,
- unfortunately, was employed by some of our
- samples--is to have calls to XMLPlatformUtils::Terminate()
- in a catch block that catches any of Xerces's exceptions.
- Since the destructor of the exception will implicitly be
- invoked upon exit from the catch block, and since some of
- the exceptions' destructors call on Xerces's
- default memory manager to destroy dynamically-allocated
- objects, their destruction will provoke a segmentation
- fault even if a return statement is placed in the catch
- block since the default memory manager will no longer exist.
- This practice is now avoided in all our samples.
- </p>
</a>
</faq>
@@ -302,9 +157,8 @@ void myParsingFunction()
<q>Is &XercesCName; thread-safe?</q>
<a>
-
- <p>This is not a question that has a simple yes/no answer. Here are the
- rules for using &XercesCName; in a multi-threaded environment:</p>
+ <p>The answer is yes if you observe the following rules for using
+ &XercesCName; in a multi-threaded environment:</p>
<p>Within an address space, an instance of the parser may be used without
restriction from a single thread, or an instance of the parser can be accessed
@@ -321,10 +175,13 @@ void myParsingFunction()
instances may be concurrently accessed from different threads, but any given
document instance can only be accessed by one thread at a time.</p>
- <p>The application also needs to guarantee that only one thread has entered either the
- method XMLPlatformUtils::Initialize() or the method XMLPlatformUtils::Terminate() at any
- one time.</p>
-
+ <p>The application also needs to guarantee that the
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ methods are called from the same thread (usually the initial
+ thread executing main()) or proper synchronization is performed
+ by the application if multiple threads call
+ XMLPlatformUtils::Initialize() and XMLPlatformUtils::Terminate()
+ concurrently.</p>
</a>
</faq>
@@ -348,64 +205,36 @@ void myParsingFunction()
should match the number of XMLPlatformUtils::Initialize() calls.
</p>
- <p>If you are using XML4C where ICU is used, you may call ICU function u_cleanup() to clean up
- ICU static data. Please see <jump href="http://icu-project.org/">ICU documentation</jump>
- for details.
- </p>
- </a>
- </faq>
-
- <faq title="I find memory leaks in &XercesCName;. How do I eliminate it?">
-
- <q>I find memory leaks in &XercesCName;. How do I eliminate it?</q>
-
- <a>
-
- <p>The "leaks" that are reported through a leak-detector or heap-analysis
- tools aren't really leaks in most application, in that the memory usage does
- not grow over time as the XML parser is used and re-used.</p>
-
- <p>What you are seeing as leaks are actually lazily evaluated data
- allocated into static variables. This data gets released when the application
- ends. You can make a call to <code>XMLPlatformUtil::terminate()</code> to release all the lazily allocated variables before you exit your
- program.</p>
-
- <p>To ensure all the memory held by the parser are freed, the number of XMLPlatformUtils::Terminate() calls
- should match the number of XMLPlatformUtils::Initialize() calls.
- </p>
-
- <p>If you are using XML4C where ICU is used, you may call ICU function u_cleanup() to clean up
- ICU static data. Please see <jump href="http://icu-project.org/">ICU documentation</jump>
- for details.
+ <p>If you have built &XercesCName; with dependency on ICU then you may
+ want to call the u_cleanup() ICU function to clean up
+ ICU static data. Refer to the ICU documentation for details.
</p>
</a>
</faq>
<faq title="Can &XercesCName; create an XML skeleton based on a DTD">
- <q>Is there a function that I have totally missed that creates
- an XML file from a DTD, (obviously with the values missing, a skeleton, as it
- were)?</q>
-
+ <q>Is there a function that creates an XML file from a DTD (obviously
+ with the values missing, a skeleton)?</q>
<a>
- <p>No. This is not supported.</p>
+ <p>No, there is no such functionality.</p>
</a>
</faq>
<faq title="Can I use &XercesCName; to perform write validation">
- <q>Can I use &XercesCName; to perform "write validation" (which is having an
+ <q>Can I use &XercesCName; to perform "write validation"? That is, having an
appropriate Grammar and being able to add elements to the DOM whilst validating
- against the grammar)?</q>
+ against the grammar?</q>
<a>
- <p>No. This is not supported.</p>
+ <p>No, there is no such functionality.</p>
<p>The best you can do for now is to create the DOM document, write it back
- as XML and re-parse it.</p>
+ as XML and re-parse it with validation turned on.</p>
</a>
</faq>
@@ -416,9 +245,8 @@ void myParsingFunction()
DOM tree? That is, without saving and re-parsing the source document?</q>
<a>
-
- <p>No. The best option for now is to generate XML source from the DOM and feed that back
- into the parser.</p>
+ <p>No, there is no such functionality. The best you can do for now is to create the DOM document, write it back
+ as XML and re-parse it with validation turned on.</p>
</a>
</faq>
@@ -426,8 +254,6 @@ void myParsingFunction()
<faq title="How to write out a DOM tree into a string or an XML file?">
<q>How to write out a DOM tree into a string or an XML file?</q>
<a>
- <p>Please make sure you are using &XercesCName; &XercesC3Version; or up.</p>
-
<p>You can use
the DOMLSSerializer::writeToString, or DOMLSSerializer::writeNode to serialize a DOM tree.
Please refer to the sample DOMPrint or the API documentation for more details of
@@ -435,13 +261,13 @@ void myParsingFunction()
</a>
</faq>
- <faq title="Why does DOMNode::cloneNode() not clone the pointer assigned to a DOMNode via DOMNode::setUserData()?">
- <q>Why does DOMNode::cloneNode() not clone the pointer assigned to a DOMNode via DOMNode::setUserData()?</q>
+ <faq title="Why doesn't DOMNode::cloneNode() clone the pointer assigned to a DOMNode via DOMNode::setUserData()?">
+ <q>Why doesn't DOMNode::cloneNode() clone the pointer assigned to a DOMNode via DOMNode::setUserData()?</q>
<a>
<p>&XercesCName; supports the DOMNode::userData specified
in <jump href="http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#ID-3A0ED0A4">
the DOM level 3 Node interface</jump>. As
- is made clear in the description of the behaviour of
+ is made clear in the description of the behavior of
<code>cloneNode()</code>, userData that has been set on the
Node is not cloned. Thus, if the userData is to be copied
to the new Node, this copy must be effected manually.
@@ -472,47 +298,6 @@ void myParsingFunction()
</a>
</faq>
- <faq title="What kinds of URLs are currently supported in &XercesCName;?">
-
- <q>What kinds of URLs are currently supported in &XercesCName;?</q>
-
- <a>
-
- <p>The <code>XMLURL</code> class provides for limited URL support. It understands the <code>file://, http://</code>, and <code>ftp://</code> URL types, and is capable or parsing them into their constituent
- components, and normalizing them. It also supports the commonly required action
- of conglomerating a base and relative URL into a single URL. In other words, it
- performs the limited set of functions required by an XML parser.</p>
-
- <p>Another thing that URLs commonly do are to create an input stream that
- provides access to the entity referenced. The parser, as shipped, only supports
- this functionality on URLs in the form <code>file:///</code> and <code>file://localhost/</code>, i.e. only when the URL refers to a local file.</p>
-
- <p>You may enable support for HTTP and FTP URLs by implementing and
- installing a NetAccessor object. When a NetAccessor object is installed, the
- URL class will use it to create input streams for the remote entities referred
- to by such URLs.</p>
-
- </a>
- </faq>
-
- <faq title="How can I add support for URLs with HTTP/FTP protocols?">
-
- <q>How can I add support for URLs with HTTP/FTP protocols?</q>
-
- <a>
-
- <p>Support for the http: protocol is now included by default on all
- platforms.</p>
-
- <p>To address the need to make remote connections to resources specified
- using additional protocols, ftp for example, &XercesCName; provides the
- <code>NetAccessor</code> interface. The header file is <code>src/xercesc/util/XMLNetAccessor.hpp</code>.
- This interface allows you to plug in your own implementation of URL
- networking code into the &XercesCName; parser.</p>
-
- </a>
- </faq>
-
<faq title="Can I use &XercesCName; to parse HTML?">
<q>Can I use &XercesCName; to parse HTML?</q>
@@ -545,39 +330,32 @@ void myParsingFunction()
encoding for "plain" text files depends both on the operating system and the
locale (country and language) in use.</p>
- <p>Another common source of problems is that some characters are not
+ <p>Another common source of problems is characters that are not
allowed in XML documents, according to the XML spec. Typical disallowed
characters are control characters, even if you escape them using the Character
- Reference form. See the <jump href="http://www.w3.org/TR/REC-xml#charsets">XML
- spec</jump>, sections 2.2 and 4.1 for details. If the parser is generating an <code>Invalid character (Unicode: 0x???)</code> error, it is very likely that there's a character in there that you
+ Reference form. See the XML specification, sections 2.2 and 4.1 for details.
+ If the parser is generating an <code>Invalid character (Unicode: 0x???)</code> error, it is very likely that there's a character in there that you
can't see. You can generally use a UNIX command like "od -hc" to find it.</p>
</a>
</faq>
- <faq title="What encodings are supported by Xerces-C / XML4C?">
+ <faq title="What encodings are supported by &XercesCName;?">
- <q>What encodings are supported by Xerces-C / XML4C?</q>
+ <q>What encodings are supported by &XercesCName;?</q>
<a>
-
- <p>Xerces-C has intrinsic support for ASCII, UTF-8, UTF-16 (Big/Small
+ <p>&XercesCName; has intrinsic support for ASCII, UTF-8, UTF-16 (Big/Small
Endian), UCS4 (Big/Small Endian), EBCDIC code pages IBM037, IBM1047 and IBM1140
encodings, ISO-8859-1 (aka Latin1) and Windows-1252. This means that it can
- parse input XML files in these above mentioned encodings.</p>
-
- <p>XML4C -- the version of Xerces-C available from IBM -- combines Xerces-C
- and <jump href="http://icu-project.org/">
- International Components for Unicode (ICU)</jump> and
- extends the encoding support to over 100 different encodings that are allowed
- by ICU. In particular, all the encodings registered with the
- <jump href="http://www.iana.org/assignments/character-sets">
- Internet Assigned Numbers Authority (IANA) </jump> are supported in XML4C.</p>
-
- <p>Some implementations or ports of Xerces-C provide support for
- additional encodings. The exact set will depend on the supplier of the parser
- and on the character set transcoding services in use.</p>
+ always parse input XML files in these above mentioned encodings.</p>
+ <p>Furthermore, if you build &XercesCName; with the International Components
+ for Unicode (ICU) as a transcoder then the list of supported encodings
+ extends to over 100 different encodings that are supported by
+ ICU. In particular, all the encodings registered with the
+ Internet Assigned Numbers Authority (IANA) are supported
+ in this configuration.</p>
</a>
</faq>
@@ -604,8 +382,8 @@ void myParsingFunction()
</ul>
<p>The only drawback of utf-8 or utf-16 is that they are not the native
- text file format for most systems, meaning that common text file editors and
- viewers can not be directly used.</p>
+ text file format for most systems, meaning that some text file editors
+ and viewers can not be directly used.</p>
<p>A second choice of encoding would be any of the others listed in the
table above. This works best when the xml encoding is the same as the default
@@ -614,10 +392,6 @@ void myParsingFunction()
systems in countries speaking Western European languages, the encoding will
usually be iso-8859-1.</p>
- <p>The versions of Xerces distributed by IBM, both C and Java (known
- respectively as XML4C and XML4J), include all of the encodings listed in the
- above table, on all platforms.</p>
-
<p>A word of caution for Windows users: The default character set on
Windows systems is windows-1252, not iso-8859-1. While &XercesCName; does
recognize this Windows encoding, it is a poor choice for portable XML data
@@ -629,47 +403,16 @@ void myParsingFunction()
</a>
</faq>
- <faq title="Is EBCDIC supported?">
-
- <q>Is EBCDIC supported?</q>
-
- <a>
-
- <p>Yes, &XercesCName; supports EBCDIC with the ibm1140, ibm037 and ibm1047 encodings.
- When creating EBCDIC encoded XML data, the preferred encoding is ibm1140. The ibm037 encoding,
- and its alternate name, ebcdic-cp-us, is almost the same as ibm1140, but
- it lacks the Euro symbol.</p>
-
- <p>These three encodings, ibm1140, ibm037 and ibm1047, are available on both
- Xerces-C and IBM XML4C, on all platforms.</p>
-
- <p>On IBM System 390, XML4C also supports three alternative forms,
- ibm037-s390, ibm1140-s390, and ibm1047-s390. These are similar to the base ibm037, ibm1140, and ibm1047
- encodings, but with alternate mappings of the EBCDIC new-line character, which
- allows them to appear as normal text files on System 390. These encodings are
- not supported on other platforms, and should not be used for portable data.</p>
-
- <p>XML4C on System 390 and AS/400 also provides additional EBCDIC
- encodings, including those for the character sets of different countries. The
- exact set supported will be platform dependent, and these encodings are not
- recommended for portable XML data.</p>
-
- </a>
- </faq>
-
<faq title="Why does deleting a transcoded string result in assertion on windows?">
<q>Why does deleting a transcoded string result in assertion on windows?</q>
<a>
- <p>Both your application program and the &XercesCName; DLL must use the same *DLL* version of the
- runtime library. If either statically links to the runtime library, the
+ <p>Both your application program and the &XercesCName; DLL must use the same DLL version of the
+ runtime library. If either statically links to the runtime library, this
problem will still occur.</p>
- <p>For example, for a Win32/VC6 build, the runtime library build setting MUST
- be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for
- debug builds.</p>
-
- <p>Or for example for a Win32/BCB6 build, application need to switch to Multithreaded
- runtime to avoid such memory access violation.</p>
+ <p>For a Visual Studio build the runtime library setting MUST
+ be "Multithreaded DLL" for release builds and "Debug Multithreaded DLL" for
+ debug builds.</p>
<p>To bypass such problem, instead of calling operator delete[] directly, you can use the
provided function XMLString::release to delete any string that was allocated by the parser.
@@ -686,7 +429,7 @@ void myParsingFunction()
code page. If this is not true, you must transcode the text yourself. You
can do this using local transcoding support on your OS, such as Iconv on
Unix or IBM's ICU package. However, if your transcoding needs are simple,
- you can achieve some better portability by using the &XercesCName; parser's
+ you can achieve better portability by using the &XercesCName; parser's
transcoder wrappers. You get a transcoder like this:
</p>
<ul>
@@ -711,7 +454,7 @@ void myParsingFunction()
</li>
<li>
This object is really just a wrapper around the underlying transcoding
- system actually in use by your version of Xerces, and does whatever is
+ system actually in use by your version of &XercesCName;, and does whatever is
necessary to handle differences between the XMLCh representation and the
representation used by that underlying transcoding system.
</li>
@@ -745,62 +488,33 @@ void myParsingFunction()
</ul>
<p>Here is an example:</p>
<source>
-// create an XMLTranscoder that is able to transcode between Unicode and Big5
-// ASSUMPTION: assumes your underlying transcoding utility supports this encoding Big5
-XMLTranscoder* t =
- XMLPlatformUtils::fgTransService->makeNewTranscoderFor("Big5", failReason, 16*1024, MemoryManager);
-
-// source string is in Unicode, wanna to transcode to Big5
-t->transcodeTo(source_unicode, length, result_Big5, length, charsEaten, XMLTranscoder::UnRep_Throw );
-
-// source string in Big5, wanna to transcode to Unicode
-t->transcodeFrom(source_Big5, length, result_unicode, length, bytesEaten, (unsigned char*)charSz);
+// Create an XMLTranscoder that is able to transcode between
+// Unicode and UTF-8.
+//
+XMLTranscoder* t = XMLPlatformUtils::fgTransService->makeNewTranscoderFor(
+ "UTF-8", failReason, 16*1024);
+
+// Source string is in Unicode, want to transcode to UTF-8
+t->transcodeTo(source_unicode,
+ length,
+ result_utf8,
+ length,
+ charsEaten,
+ XMLTranscoder::UnRep_Throw);
+
+// Source string in UTF-8, want to transcode to Unicode.
+t->transcodeFrom(source_utf8,
+ length,
+ result_unicode,
+ length,
+ bytesEaten,
+ (unsigned char*)charSz);
</source>
- </a>
- </faq>
-
- <faq title="Why does setProperty not work?">
-
- <q>Why does setProperty not work?</q>
-
- <a>
-
- <p>The function <code>SAX2XMLReader::setProperty(const XMLCh* const name, void* value)</code>
- and <code>DOMLSParser::getDomConfig()->setParameter(const XMLCh* name, const void* value)</code>
- takes a void pointer for the property value. Application is required to initialize this void pointer
- to a correct type. See <jump href="program-sax2-&XercesC3Series;.html#SAX2Properties">SAX2 Programming Guide</jump>
- and <jump href="program-dom-&XercesC3Series;.html#DOMLSParserProperties">DOM Programming Guide</jump>
- to learn exactly what type of property value that each property expects for processing.
- Passing a void pointer that was initialized with a wrong type will lead to unexpected result.
- </p>
-
- </a>
- </faq>
-
- <faq title="Why does getProperty not work?">
-
- <q>Why does getProperty not work?</q>
-
- <a>
-
- <p>The function <code>void* SAX2XMLReader::getProperty(const XMLCh* const name)</code>
- and <code>void* DOMLSParser::getDomConfig()->getParameter(const XMLCh* name)</code>
- returns a void pointer for the property value. See
- <jump href="program-sax2-&XercesC3Series;.html#SAX2Properties">SAX2 Programming Guide</jump> and
- exactly what type of object each property returns.
- </p>
- <p>The parser owns the returned pointer. The memory allocated for
- the returned pointer will be destroyed when the parser is deleted.
- To ensure accessibility of the returned information after the parser
- is deleted, callers need to copy and store the returned information
- somewhere else; otherwise you may get unexpected result. Since the returned
- pointer is a generic void pointer, see
- <jump href="program-sax2-&XercesC3Series;.html#SAX2Properties">SAX2 Programming Guide</jump> and
- <jump href="program-dom-&XercesC3Series;.html#DOMLSParserProperties">DOM Programming Guide</jump> to learn
- exactly what type of property value each property returns for replication.
- </p>
-
+ <p>An even simpler way to transcode to a different encoding is
+ to use the TranscodeToStr and TranscodeFromStr wrapper classes
+ which represent a one-time transcoding and encapsulate all the
+ memory management. Refer to the API Reference for more information.</p>
</a>
</faq>
@@ -815,11 +529,11 @@ t->transcodeFrom(source_Big5, length, result_unicode, length, bytesEaten, (un
<p>When DTD is referenced, the parser will try to read it, because DTDs can
provide a lot more information than just validation. It defines entities and
notations, external unparsed entities, default attributes, character
- entities, etc... So it will always try to read it if present, even if
+ entities, etc. Therefore the parser will always try to read it if present, even if
validation is turned off.
</p>
- <p>To ignore the DTD, with &XercesCName; &XercesC3Version; or up, you can call
+ <p>To ignore external DTDs completely you can call
<code>setLoadExternalDTD(false)</code> (or
<code>setFeature(XMLUni::fgXercesLoadExternalDTD, false)</code>
to disable the loading of external DTD. The parser will then ignore
@@ -828,28 +542,6 @@ t->transcodeFrom(source_Big5, length, result_unicode, length, bytesEaten, (un
<p>Note: This flag is ignored if the validationScheme is set to Val_Always or Val_Auto.
</p>
-
- <p>To ignore the DTD in earlier version of &XercesCName;, the
- only way to get around this is to install an EntityResolver
- (see the Redirect sample for an example of how this is done), and reset the
- DTD file to "".
- </p>
-
- </a>
- </faq>
-
- <faq title="Why do I get segmentation fault when running on Redhat Linux?">
-
- <q>Why do I get segmentation fault when running on Redhat Linux?</q>
-
- <a>
-
- <p>There were some problems with Redhat Linux 7.x with C++ exception handling across shared
- libraries. More details can be found
- <jump href="http://rhn.redhat.com/errata/RHBA-2002-055.html">here</jump>.
- Please try to upgrade your Redhat Linux gcc to the latest patch level and see if it helps.
- </p>
-
</a>
</faq>
@@ -862,7 +554,7 @@ t->transcodeFrom(source_Big5, length, result_unicode, length, bytesEaten, (un
<p>If you parse an xml document using XercesDOMParser or DOMLSParser and pass such DOMNode
to DOMLSSerializer for serialization, you may not get something that is exactly the same
as the original XML data. The parser may have done normalization, end of line conversion,
- or has expanded the entity reference as per the XML 1.0 spec, 4.4 XML Processor Treatment of
+ or has expanded the entity reference as per the XML 1.0 specification, 4.4 XML Processor Treatment of
Entities and References. From DOMLSSerializer perspective, it does not know what the original
string was, all it sees is a processed DOMNode generated by the parser.
But since the DOMLSSerializer is supposed to generate something that is parsable if sent
@@ -892,7 +584,7 @@ XercesDOMParser *parser = new XercesDOMParser;
...
try
{
- parser->parse(gXmlFile);
+ parser->parse(xml_file);
}
catch ()
{
@@ -913,23 +605,4 @@ delete parser;
</a>
</faq>
- <faq title="Why do we have two versions of some XMLString methods (one with memory manager and one without)?">
-
- <q>Why do we have two versions of some XMLString methods (one with memory manager and one without)?</q>
-
- <a>
-
- <p>With the introduction of the configurable memory manager, we didn't want to break users by
- changing the signature of the existing methods (for example, transcode and replicate). Also,
- we did not want to provide a default memory
- manager as it would introduce a side effect with users experiencing some strange core dumps.
- The latter will occur when the scope of the string allocated is beyond that of
- XMLPlatformUtils::Terminate (i.e. a string is allocated using the default memory manager
- which is deleted when XMLPlatformUtils::Terminate is called, but the allocated string is
- deleted later). We plan to deprecate the methods without a memory manager in a later release.
- </p>
-
- </a>
- </faq>
-
</faqs>
diff --git a/doc/install.xml b/doc/install.xml
index 5bc8f24fc..913e51b31 100644
--- a/doc/install.xml
+++ b/doc/install.xml
@@ -20,10 +20,13 @@
<s1 title="Installation">
+ <p>Source and binary distributions installation instructions are
+ available for the following platforms:</p>
+
<ul>
- <li><link anchor="Windows">Installation Instructions for Windows</link></li>
- <li><link anchor="Unix">Installation Instructions for UNIX/Mac OS X/Linux</link></li>
- <li><link anchor="Cygwin">Installation Instructions for Cygwin</link></li>
+ <li><link anchor="Windows">Windows</link></li>
+ <li><link anchor="Unix">UNIX/Linux/Mac OS X</link></li>
+ <li><link anchor="Cygwin">Cygwin</link></li>
</ul>
<anchor name="Windows"/>
@@ -57,10 +60,10 @@ unzip &XercesC3SrcInstallDir;.zip
WinZip, or any other UnZip utility. For example:</p>
<source>
-unzip &XercesC3InstallDir;-x86-windows-vc_8_0.zip
+unzip &XercesC3InstallDir;-x86-windows-vc-8.0.zip
</source>
- <p>This creates a '&XercesC3InstallDir;-x86-windows-vc_8_0'
+ <p>This creates a '&XercesC3InstallDir;-x86-windows-vc-8.0'
sub-directory containing the &XercesCName; binary distribution.</p>
<p>You need to add the '&XercesC3InstallDir;-{arch}-windows-{compiler}\bin'
@@ -111,10 +114,10 @@ tar -xf &XercesC3SrcInstallDir;.tar
and {compiler} denotes the C++ compiler of your choice.
For example:</p>
<source>
-gzip -d &XercesC3InstallDir;-x86-linux-gcc_3_4.tar.gz
-tar -xf &XercesC3InstallDir;-x86-linux-gcc_3_4.tar
+gzip -d &XercesC3InstallDir;-x86-linux-gcc-3.4.tar.gz
+tar -xf &XercesC3InstallDir;-x86-linux-gcc-3.4.tar
</source>
- <p>This will create an '&XercesC3InstallDir;-x86-linux-gcc_3_4'
+ <p>This will create an '&XercesC3InstallDir;-x86-linux-gcc-3.4'
sub-directory containing the &XercesCName; binary distribution.</p>
<p>You will need to add the
@@ -190,28 +193,13 @@ tar -xfz &XercesC3SrcInstallDir;.tar.gz
</s3>
<s3 title="Binary distribution">
- <p>Install the binary distribution by running
- <jump href="http://www.cygwin.com">Cygwin</jump> setup.exe.
- When you reach the "Packages" step of the Cygwin Setup wizard,
- expand the "Devel" category, then click in the "New" column next
+ <p>Precompiled Xerces-C++ libraries for Cygwin are provide as
+ part of the Cygwin package repository. To install the binary
+ distribution run Cygwin setup.exe.
+ When you reach the Packages step of the Cygwin Setup wizard,
+ expand the Devel category, then click in the New column next
to "xerces-c-devel" until it reads "&XercesC3Version;-X".</p>
- <p>This will install the necessary libraries and include files
- for the &XercesCName; binary distribution.</p>
-
- <p>If you wish to run programs linked to &XercesCName; that were
- built in the Cygwin environment, you need to add your Cygwin
- "bin" directory to your Windows PATH environment variable.
- In typical Cygwin installations, the bin directory is in the
- Cygwin directory on the drive that windows is installed on.
- For instance, if windows is installed to "C:\Windows\System32",
- Your Cygwin bin directory may be "C:\cygwin\bin".</p>
-
- <p>The binary distribution contains the pre-built parser libraries.
- Sample executables may be available in a future release on the
- Cygwin platform. In the meantime, they may be built from the
- source distribution by following the
- <jump href="build-&XercesC3Series;.html">Build Instructions</jump>.</p>
</s3>
</s2>
</s1>
diff --git a/doc/memparse.xml b/doc/memparse.xml
index e6bc5f4db..afb2850c0 100644
--- a/doc/memparse.xml
+++ b/doc/memparse.xml
@@ -21,7 +21,7 @@
<s1 title="Sample: MemParse">
<s2 title="MemParse">
- <p>MemParse uses the Validating SAX Parser to parse a memory buffer containing
+ <p>MemParse uses the SAX Parser to parse a memory buffer containing
XML statements, and reports the number of elements and attributes found.</p>
<s3 title="Running MemParse">
@@ -102,7 +102,7 @@ Parsing took 10 ms (4 elements, 1 attributes, 0 spaces, 111 characters).</source
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the system may be different, depending on your
- processor type.</note>
+ processor speed.</note>
</s3>
</s2>
diff --git a/doc/migration.xml b/doc/migration.xml
index 83ef7ec85..dc657e892 100644
--- a/doc/migration.xml
+++ b/doc/migration.xml
@@ -21,59 +21,103 @@
<s1 title="Migration">
<s2 title="Migration Archive">
- <p>For migration information to &XercesCName; 2.7.0 or earlier,
- please refer to <jump href="migrate_archive-&XercesC3Series;.html">Migration Archive. </jump></p>
+ <p>For migration information to &XercesCName; 2 series or earlier,
+ please refer to <link idref="migrate-archive-&XercesC3Series;">Migration Archive</link>.</p>
</s2>
- <s2 title="Migrating from &XercesCName; 2.7.0 to &XercesCName; &XercesC3Version;">
+ <s2 title="Migrating from &XercesCName; 2 series to &XercesCName; &XercesC3Version;">
<p>The following section is a discussion of the technical differences between
- &XercesCName; 2.7.0 code base and the &XercesCName; &XercesC3Version;.</p>
+ &XercesCName; 2 series and &XercesCName; &XercesC3Version;.</p>
<p>Topics discussed are:</p>
<ul>
- <li><link anchor="NewFeatures280">New features in &XercesCName; &XercesC3Version;</link></li>
- <li><link anchor="API280">Public API Changes</link></li>
+ <li><link anchor="NewFeatures300">New features in &XercesCName; &XercesC3Version;</link></li>
+ <li><link anchor="API300">Public API Changes</link></li>
<ul>
- <li><link anchor="NewAPI280">New Public API</link></li>
- <li><link anchor="ModifiedAPI280">Modified Public API</link></li>
- <li><link anchor="DeprecatedAPI280">Deprecated/Removed Public API</link></li>
+ <li><link anchor="NewAPI300">New Public API</link></li>
+ <li><link anchor="ModifiedAPI300">Modified Public API</link></li>
+ <li><link anchor="DeprecatedAPI300">Deprecated/Removed Public API</link></li>
</ul>
</ul>
- <anchor name="NewFeatures280"/>
+ <anchor name="NewFeatures300"/>
<s3 title="New features in &XercesCName; &XercesC3Version;">
<ul>
- <li>Exponential growth of memory block (from 16KB to 128KB) that are allocated by the DOM heap.</li>
- <li>The NODE_CLONED notification is now sent to each node's user data handler when cloning the entire DOMDocument.</li>
- <li>On Windows extract the registry code page from MIME\Database\Charset\<encoding>\@InternetEncoding instead of MIME\Database\Charset\<encoding>\@Codepage.</li>
- <li>Allow whitespace-only nodes to be added as children of a DOMDocument.</li>
- <li>When a node is cloned or imported the type information (PSVI) is also copied.</li>
- <li>When using SAX2, including XMLReaderFactory to use createXMLReader doesn't include xercesc/parsers/SAX2XMLReaderImpl.hpp anymore. If you need to cast the SAX2XMLReader to SAX2XMLReaderImpl,
- you need to include this header yourself.</li>
+ <li>Autotools-based build system for the UNIX/Linux/Mac OS X platforms</li>
+ <li>Project files for VC++ 9</li>
+ <li>Support for the ICU transcoder in VC++ 7.1, 8, and 9 project files</li>
+ <li>libcurl-based net accessor</li>
+ <li>Support for XInclude in DOM</li>
+ <li>Support for both XPath 1 and XPath 2 models in the DOM XPath interface</li>
+ <li>Support for the XML Schema subset of XPath 1 in DOM</li>
+ <li>Conformance to the final DOM Level 3 interface specification</li>
+ <li>Ability to provide custom DOM memory manager as well as tune the global DOM heap parameters</li>
+ <li>All public and widely used interfaces as well as a large
+ portion of the implementation were converted to be 64-bit safe.</li>
+ <li>Various XML Schema fixes including the fix for the large
+ maxOccurs and minOccurs bug as well as for the changed ##other
+ interpretation</li>
+ <li>Reviewed and cleaned up diagnostics messages</li>
+ <li>Optimizations for SAX/SAX2 and DOM parsing as well as XML Schema
+ validation</li>
</ul>
</s3>
- <anchor name="API280"/>
+ <anchor name="API300"/>
<s3 title="Public API Changes">
- <p>The following lists the public API changes between the &XercesCName;
- 2.7.0; and the &XercesCName; &XercesC3Version; releases
- of the parser. </p>
+ <p>&XercesCName; &XercesC3Version; is a major release and includes
+ a number of application-breaking interface changes compared to
+ &XercesCName; 2 series.
+ The following sub-sections provide an overview of the public API
+ changes between &XercesCName; 2 series and this release.</p>
- <anchor name="NewAPI280"/>
- <s4 title="New Public API">
+ <anchor name="NewAPI300"/>
+ <s4 title="New Public APIs">
<ul>
- <li>XMLBufferMgr: getBufferCount and getAvailableBufferCount</li>
+ <li>XMLGrammarPoolImpl implementation has been moved to
+ framework/ and is now publicly accessible</li>
+
+ <li>DOM XPath interfaces now support XPath 2 model</li>
+
+ <li>A number of DOM interfaces (DOMLSInput, DOMLSOuput,
+ DOMLSParser, DOMLSSerializer, DOMConfiguration, etc.)
+ were added as part of the the final DOM Level 3
+ specification conformance work</li>
</ul>
</s4>
- <anchor name="ModifiedAPI280"/>
- <s4 title="Modified Public API">
+ <anchor name="ModifiedAPI300"/>
+ <s4 title="Modified Public APIs">
+
+ <p>A large number of public APIs have been modified. Consult
+ individual interface documentation for details. The following
+ list gives an overview of major changes:</p>
+
+ <ul>
+ <li>Several DOM interfaces have been adjusted to conform to the final
+ DOM Level 3 specification</li>
+
+ <li>DOM XPath interfaces have been adjusted to support both XPath 1
+ and XPath 2</li>
+
+ <li>Many public interfaces that used int/long types to represent
+ memory-related sizes, counts, indexes, etc., have been modified
+ to use the 64-bit safe XMLSize_t type instead</li>
+ </ul>
+
</s4>
- <anchor name="DeprecatedAPI280"/>
- <s4 title="Deprecated/Removed Public API">
+ <anchor name="DeprecatedAPI300"/>
+ <s4 title="Deprecated/Removed Public APIs">
+ <p>All APIs marked as deprecated in &XercesCName; 2 series have
+ been removed in this release. In particular deprecated DOM
+ (depdom) as well as COM support have been removed.</p>
+
+ <p>Furthermore, a number of DOM interfaces (DOMBuilder, DOMWriter,
+ DOMInputSource, etc.) were replaced as part of the the final
+ DOM Level 3 specification conformance work.</p>
</s4>
</s3>
diff --git a/doc/migration_archive.xml b/doc/migration_archive.xml
index 33203c70f..e33f77315 100644
--- a/doc/migration_archive.xml
+++ b/doc/migration_archive.xml
@@ -21,6 +21,7 @@
<s1 title="Migration Archive">
<s2 title="Migrating to earlier Releases">
<ul>
+ <li><link anchor="Migrateto280">Migrating from &XercesCName; 2.7.0 to 2.8.0</link></li>
<li><link anchor="Migrateto270">Migrating from &XercesCName; 2.6.0 to 2.7.0</link></li>
<li><link anchor="Migrateto260">Migrating from &XercesCName; 2.5.0 to 2.6.0</link></li>
<li><link anchor="Migrateto250">Migrating from &XercesCName; 2.4.0 to 2.5.0</link></li>
@@ -36,6 +37,35 @@
</ul>
</s2>
+ <anchor name="Migrateto280"/>
+ <s2 title="Migrating from &XercesCName; 2.7.0 to &XercesCName; 2.8.0">
+ <p>The following section is a discussion of the technical differences between
+ &XercesCName; 2.7.0 code base and the &XercesCName; 2.8.0.</p>
+
+ <p>Topics discussed are:</p>
+ <ul>
+ <li><link anchor="NewFeatures280">New features in &XercesCName; 2.8.0</link></li>
+ <li><link anchor="API280">Public API Changes</link></li>
+ <ul>
+ <li><link anchor="NewAPI280">New Public API</link></li>
+ <li><link anchor="ModifiedAPI280">Modified Public API</link></li>
+ <li><link anchor="DeprecatedAPI280">Deprecated/Removed Public API</link></li>
+ </ul>
+ </ul>
+
+ <anchor name="NewFeatures280"/>
+ <s3 title="New features in &XercesCName; 2.8.0">
+ <ul>
+ <li>Exponential growth of memory block (from 16KB to 128KB) that are allocated by the DOM heap.</li>
+ <li>The NODE_CLONED notification is now sent to each node's user data handler when cloning the entire DOMDocument.</li>
+ <li>On Windows extract the registry code page from MIME\Database\Charset\<encoding>\@InternetEncoding instead of MIME\Database\Charset\<encoding>\@Codepage.</li>
+ <li>Allow whitespace-only nodes to be added as children of a DOMDocument.</li>
+ <li>When a node is cloned or imported the type information (PSVI) is also copied.</li>
+ <li>When using SAX2, including XMLReaderFactory to use createXMLReader doesn't include xercesc/parsers/SAX2XMLReaderImpl.hpp anymore. If you need to cast the SAX2XMLReader to SAX2XMLReaderImpl,
+ you need to include this header yourself.</li>
+ </ul>
+ </s3>
+ </s2>
<anchor name="Migrateto270"/>
<s2 title="Migrating from &XercesCName; 2.6.0 to &XercesCName; 2.7.0">
@@ -641,28 +671,7 @@
<anchor name="LibraryChange200"/>
<s3 title="Unix Library Name Change">
- <p>The &XercesCName; UNIX Library now follows the Unix Shared Library Naming Convention (libname.so.soname).
- It is now called:</p>
- <ul>
- <li>AIX</li>
- <ul>
- <li>&XercesC3UnixLib;&XercesC3UnixSoName;.so</li>
- <li>symbolic link: &XercesC3UnixLib;.so ----> &XercesC3UnixLib;&XercesC3UnixVersion;.so</li>
- <li>symbolic link: &XercesC3UnixLib;&XercesC3UnixVersion;.so ----> &XercesC3UnixLib;&XercesC3UnixSoName;.so</li>
- </ul>
- <li>Solaris / Linux</li>
- <ul>
- <li>&XercesC3UnixLib;.so.&XercesC3UnixSoName;</li>
- <li>symbolic link: &XercesC3UnixLib;.so ----> &XercesC3UnixLib;.so.&XercesC3UnixVersion;</li>
- <li>symbolic link: &XercesC3UnixLib;.so.&XercesC3UnixVersion; ----> &XercesC3UnixLib;.so.&XercesC3UnixSoName;</li>
- </ul>
- <li>HP-UX</li>
- <ul>
- <li>&XercesC3UnixLib;.sl.&XercesC3UnixSoName;</li>
- <li>symbolic link: &XercesC3UnixLib;.sl ----> &XercesC3UnixLib;.sl.&XercesC3UnixVersion;</li>
- <li>symbolic link: &XercesC3UnixLib;.sl.&XercesC3UnixVersion; ----> &XercesC3UnixLib;.sl.&XercesC3UnixSoName;</li>
- </ul>
- </ul>
+ <p>The &XercesCName; UNIX Library now follows the Unix Shared Library Naming Convention (libname.so.soname).</p>
</s3>
<anchor name="DirChange200"/>
diff --git a/doc/pparse.xml b/doc/pparse.xml
index 31a557a30..b3f7c4351 100644
--- a/doc/pparse.xml
+++ b/doc/pparse.xml
@@ -22,12 +22,12 @@
<s2 title="PParse">
<p>PParse demonstrates progressive parsing.</p>
- <p>In this example, the programmer doesn't have to depend upon throwing
+ <p>In this example, the application doesn't have to depend upon throwing
an exception to terminate the parsing operation. Calling parseFirst() will
cause the DTD to be parsed (both internal and external subsets) and any
pre-content, i.e. everything up to but not including the root element.
Subsequent calls to parseNext() will cause one more piece of markup to
- be parsed, and spit out from the core scanning code to the parser. You
+ be parsed, and propagated from the core scanning code to the parser. You
can quit the parse any time by just not calling parseNext() anymore
and breaking out of the loop. When you call parseNext() and the end
of the root element is the next piece of markup, the parser will
@@ -35,8 +35,8 @@
know that the parse is done.</p>
<s3 title="Running PParse">
- <p>PParse parses an XML file and prints out a count of the number of
- elements in the file</p>
+ <p>PParse parses an XML file and prints out the number of
+ elements in the file.</p>
<source>Usage:
PParse [options] <XML file>
@@ -60,7 +60,7 @@ Options:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from PParse</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
PParse -v=always personal.xml
personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)</source>
<p>Running PParse with the validating parser gives a different result because
@@ -70,7 +70,7 @@ personal.xml: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
</s1>
diff --git a/doc/program-dom.xml b/doc/program-dom.xml
index 800984862..b91481d6f 100644
--- a/doc/program-dom.xml
+++ b/doc/program-dom.xml
@@ -316,13 +316,10 @@
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
@@ -833,13 +830,10 @@
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
@@ -917,7 +911,7 @@
provides some framework classes for specialized types of input source (i.e. LocalFileInputSource, etc.) that are
derived from the SAX InputSource. In DOM L3, to allow users implementing their own DOMLSResourceResolver(s), which return
a DOMLSInput, to utilize these framework classes, we need to provide a mechanism to map a SAX InputSource to a
- DOMInputSource. We are introducing to wrapper classes to interchange DOMLSInput and SAX InputSource.
+ DOMInputSource. Two wrapper classes are available to interchange DOMLSInput and SAX InputSource:
</p>
<s4 title="Wrapper4DOMLSInput">
@@ -1250,8 +1244,8 @@
</table>
<p/>
-
-
+
+
<anchor name="builder-load-schema"/>
<table>
<tr><th colspan="2"><em>http://apache.org/xml/features/validating/load-schema</em></th></tr>
@@ -1632,7 +1626,7 @@
<anchor name="ConstructDOMLSSerializer"/>
<s3 title="Constructing a DOMLSSerializer">
- <p>DOMWriter is a new interface introduced by the
+ <p>DOMLSSerializer is a new interface introduced by the
<jump href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/">
W3C DOM Level 3.0 Load and Save Specification</jump>.
DOMLSSerializer provides the "Save" interface for serializing (writing) a DOM document into
@@ -1646,13 +1640,11 @@
#include <xercesc/util/XMLString.hpp>
#include <xercesc/util/PlatformUtils.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
+
int serializeDOM(DOMNode* node) {
XMLCh tempStr[100];
@@ -1764,8 +1756,8 @@
<Test><![CDATA[< > & " ' &lt; &gt; &amp; &quot; &apos; ] ]></Test>
</root>
</source>
- <p>To summarize, here is the table that summarize how built-in entity reference are handled for
- different Node Type:</p>
+ <p>Below is the table that summarizes how built-in entity reference are handled for
+ different DOM node types:</p>
<table>
<tr>
<th><em>Input/Output</em></th>
diff --git a/doc/program-others.xml b/doc/program-others.xml
index 81e0d3922..d65af85cd 100644
--- a/doc/program-others.xml
+++ b/doc/program-others.xml
@@ -21,23 +21,23 @@
<s1 title="Programming Guide">
<anchor name="Macro"/>
<s2 title="Version Macro">
- <p>&XercesCName; has defined a numeric preprocessor macro, _XERCES_VERSION, for users to
+ <p>&XercesCName; defines a numeric preprocessor macro, _XERCES_VERSION, for users to
introduce into their code to perform conditional compilation where the
- version of Xerces is detected in order to enable or disable version
+ version of &XercesCName; is detected in order to enable or disable version
specific capabilities. For example,
</p>
<source>
-#if _XERCES_VERSION >= 20304
- // code specific to Xerces-C++ version 2.3.4
+#if _XERCES_VERSION >= 30102
+ // Code specific to Xerces-C++ version 3.1.2 and later.
#else
- // old code here...
+ // Old code.
#endif
</source>
<p>The minor and revision (patch level) numbers have two digits of resolution
- which means that '3' becomes '03' and '4' becomes '04' in this example.
+ which means that '1' becomes '01' and '2' becomes '02' in this example.
</p>
<p>There are also other string macros or constants to represent the Xerces-C++ version.
- Please refer to the header xercesc/util/XercesVersion.hpp for further details.
+ Please refer to the <code>xercesc/util/XercesVersion.hpp</code> header for details.
</p>
</s2>
@@ -45,32 +45,32 @@
<anchor name="Schema"/>
<s2 title="Schema Support">
<p>&XercesCName; contains an implementation of the W3C XML Schema
- Language. See <jump href="schema-&XercesC3Series;.html">the Schema page</jump> for details.
+ Language. See the <jump href="schema-&XercesC3Series;.html">XML Schema Support</jump> page for details.
</p>
</s2>
<anchor name="Progressive"/>
<s2 title="Progressive Parsing">
- <p>In addition to using the <ref>parse()</ref> method to parse an XML File.
- You can use the other two parsing methods, <ref>parseFirst()</ref> and <ref>parseNext()</ref>
- to do 'progressive parsing', so that you don't
- have to depend upon throwing an exception to terminate the
+ <p>In addition to using the <code>parse()</code> method to parse an XML File.
+ You can use the other two parsing methods, <code>parseFirst()</code> and <code>parseNext()</code>
+ to do the so called progressive parsing. This way you don't
+ have to depend on throwing an exception to terminate the
parsing operation.
</p>
<p>
- Calling parseFirst() will cause the DTD (both internal and
+ Calling <code>parseFirst()</code> will cause the DTD (both internal and
external subsets), and any pre-content, i.e. everything up to
but not including the root element, to be parsed. Subsequent calls to
- parseNext() will cause one more pieces of markup to be parsed,
- and spit out from the core scanning code to the parser (and
- hence either on to you if using SAX or into the DOM tree if
+ <code>parseNext()</code> will cause one more pieces of markup to be parsed,
+ and propagated from the core scanning code to the parser (and
+ hence either on to you if using SAX/SAX2 or into the DOM tree if
using DOM).
</p>
<p>
You can quit the parse any time by just not
- calling parseNext() anymore and breaking out of the loop. When
- you call parseNext() and the end of the root element is the
+ calling <code>parseNext()</code> anymore and breaking out of the loop. When
+ you call <code>parseNext()</code> and the end of the root element is the
next piece of markup, the parser will continue on to the end
of the file and return false, to let you know that the parse
is done. So a typical progressive parse loop will look like
@@ -93,9 +93,10 @@ bool gotMore = true;
while (gotMore && !handler.getDone())
gotMore = parser.parseNext(token);</source>
- <p>In this case, our event handler object (named 'handler'
- surprisingly enough) is watching for some criteria and will
- return a status from its getDone() method. Since the handler
+ <p>In this case, our event handler object (named 'handler')
+ is watching for some criteria and will
+ return a status from its <code>getDone()</code> method. Since
+ the handler
sees the SAX events coming out of the SAXParser, it can tell
when it finds what it wants. So we loop until we get no more
data or our handler indicates that it saw what it wanted to
@@ -120,25 +121,26 @@ while (gotMore && !handler.getDone())
<p>Also note that you must create a scan token and pass it
back in on each call. This insures that things don't get done
- out of sequence. When you call parseFirst() or parse(), any
+ out of sequence. When you call <code>parseFirst()</code> or
+ <code>parse()</code>, any
previous scan tokens are invalidated and will cause an error
if used again. This prevents incorrect mixed use of the two
different parsing schemes or incorrect calls to
- parseNext().</p>
+ <code>parseNext()</code>.</p>
</s2>
<anchor name="GrammarCache"/>
- <s2 title="Preparsing Grammar and Grammar Caching">
- <p>&XercesCName; &XercesC3Version; provides a new function to pre-parse the grammar so that users
- can check for any syntax or error before using the grammar. Users can also optionally
+ <s2 title="Pre-parsing Grammar and Grammar Caching">
+ <p>&XercesCName; provides a function to pre-parse the grammar so that users
+ can check for any syntax error before using the grammar. Users can also optionally
cache these pre-parsed grammars for later use during actual parsing.
</p>
<p>Here is an example:</p>
<source>
XercesDOMParser parser;
-// enbale schema processing
+// Enable schema processing.
parser.setDoSchema(true);
parser.setDONamespaces(true);
@@ -220,8 +222,9 @@ parser->parse(xmlFile2);
<ul>
<li>When caching/reusing DTD grammars, no internal subset is allowed.</li>
<li>When preparsing grammars with caching option enabled, if a grammar, in the
- result set, already exists in the pool (same NS for schema or same system
- id for DTD), the entire set will not be cached.</li>
+ result set, already exists in the pool (same namespace for schema or same system
+ id for DTD), the entire set will not be cached. This behavior is the default but can
+ be overridden for XML Schema caching. See the SAX/SAX2/DOM parser features for details.</li>
<li>When parsing an XML document with the grammar caching option enabled, the
reuse option is also automatically enabled. We will only parse a grammar if it
does not exist in the pool.</li>
@@ -232,7 +235,8 @@ parser->parse(xmlFile2);
<s2 title="Loadable Message Text">
<p>The &XercesCName; supports loadable message text. Although
- the current drop just supports English, it is capable to support other
+ the current distribution only supports English, it is capable of
+ supporting other
languages. Anyone interested in contributing any translations
should contact us. This would be an extremely useful
service.</p>
@@ -240,7 +244,7 @@ parser->parse(xmlFile2);
<p>In order to support the local message loading services, all the error messages
are captured in an XML file in the src/xercesc/NLS/ directory.
There is a simple program, in the tools/NLS/Xlat/ directory,
- which can spit out that text in various formats. It currently
+ which can translate that text in various formats. It currently
supports a simple 'in memory' format (i.e. an array of
strings), the Win32 resource format, and the message catalog
format. The 'in memory' format is intended for very simple
@@ -293,78 +297,23 @@ parser->parse(xmlFile2);
<anchor name="PortingGuidelines"/>
<s2 title="Porting Guidelines">
- <p>All platform dependent code in &XercesCProjectName; has been
+ <p>All platform dependent code in &XercesCName; has been
isolated to a couple of files, which should ease the porting
- effort. Here are the basic steps that should be followed to
- port &XercesCProjectName;.</p>
-
- <ol>
-
- <li>The directory <code>src/xercesc/util/Platforms</code> contains the
- platform sensitive files while <code>src/xercesc/util/Compilers</code> contains
- all development environment sensitive files. Each operating
- system has a file of its own and each development environment
- has another one of its own too.
-
- <br/>
-
- As an example, the Win32 platform as a <code>Win32Defs.hpp</code> file
- and the Visual C++ environment has a <code>VCPPDefs.hpp</code> file.
- These files set up certain define tokens, typedefs,
- constants, etc... that will drive the rest of the code to
- do the right thing for that platform and development
- environment. AIX/CSet have their own <code>AIXDefs.hpp</code> and
- <code>CSetDefs.hpp</code> files, and so on. You should create new
- versions of these files for your platform and environment
- and follow the comments in them to set up your own.
- Probably the comments in the Win32 and Visual C++ will be
- the best to follow, since that is where the main
- development is done.</li>
-
- <li>Next, edit the file <code>XercesDefs.hpp</code>, which is where all
- of the fundamental stuff comes into the system. You will
- see conditional sections in there where the above
- per-platform and per-environment headers are brought in.
- Add the new ones for your platform under the appropriate
- conditionals.</li>
-
- <li>Now edit <code>AutoSense.hpp</code>. Here we set canonical &XercesCProjectName;
- internal <code>#define</code> tokens which indicate the platform and
- compiler. These definitions are based on known platform
- and compiler defines.
- <br/>
- <code>AutoSense.hpp</code> is included in <code>XercesDefs.hpp</code> and the
- canonical platform and compiler settings thus defined will
- make the particular platform and compiler headers to be
- the included at compilation.
- <br/>
- It might be a little tricky to decipher this file so be
- careful. If you are using say another compiler on Win32,
- probably it will use similar tokens so that the platform
- will get picked up already using what is already there.</li>
-
- <li>Once this is done, you will then need to implement a
- version of the <ref>platform utilities</ref> for your platform.
- Each operating system has a file which implements some
- methods of the XMLPlatformUtils class, specific to that
- operating system. These are not terribly complex, so it
- should not be a lot of work. The Win32 version is called
- <code>Win32PlatformUtils.cpp</code>, the AIX version is
- <code>AIXPlatformUtils.cpp</code> and so on. Create one for your
- platform, with the correct name, and empty out all of the
- implementation so that just the empty shells of the
- methods are there (with dummy returns where needed to make
- the compiler happy.) Once you've done that, you can start
- to get it to build without any real implementation.</li>
-
- <li>Once you have the system building, then start
- implementing your own platform utilities methods. Follow
- the comments in the Win32 version as to what they do, the
- comments will be improved in subsequent versions, but they
- should be fairly obvious now. Once you have these
- implementations done, you should be able to start
- debugging the system using the demo programs.</li>
- </ol>
+ effort. The <code>src/xercesc/util</code> directory
+ contains all such files. In particular:</p>
+
+ <ul>
+ <li>The <code>src/xercesc/util/FileManagers</code> directory
+ contains implementations of file managers for various
+ platforms.</li>
+
+ <li>The <code>src/xercesc/util/MutexManagers</code> directory
+ contains implementations of mutex managers for various
+ platforms.</li>
+
+ <li>The <code>src/xercesc/util/Xerces_autoconf_const*</code> files
+ provide base definitions for various platforms.</li>
+ </ul>
<p>Other concerns are:</p>
@@ -382,87 +331,79 @@ parser->parse(xmlFile2);
further details.</li>
</ul>
- <p>That is the work required in a nutshell!</p>
- </s2>
+ <p>Finally, you need to decide about how to define XMLCh. Generally,
+ XMLCh should be defined to be a type suitable for holding a
+ utf-16 encoded (16 bit) value, usually an <code>unsigned short</code>. </p>
- <anchor name="CPPNamespace"/>
- <s2 title="Using C++ Namespace">
+ <p>All XML data is handled within &XercesCName; as strings of
+ XMLCh characters. Regardless of the size of the
+ type chosen, the data stored in variables of type XMLCh
+ will always be utf-16 encoded values. </p>
- <p>&XercesCName; &XercesC3Version; supports C++ Namespace as of Version 2.2.0.</p>
- <p>The macro <code>XERCES_HAS_CPP_NAMESPACE</code> is defined in each Compiler
- Definition file if C++ Namespace is supported.</p>
- <p>For example in header <code>xercesc/util/Compilers/GCCDefs.hpp</code>,
- the C++ Namespace is enabled:</p>
-<source>
-// -------------------------------------------------------------------------
-// Indicate that we support C++ namespace
-// Do not define it if the compile cannot handle C++ namespace
-// -------------------------------------------------------------------------
-#define XERCES_HAS_CPP_NAMESPACE
-</source>
+ <p>Unlike XMLCh, the encoding
+ of wchar_t is platform dependent. Sometimes it is utf-16
+ (AIX, Windows), sometimes ucs-4 (Solaris,
+ Linux), sometimes it is not based on Unicode at all
+ (HP/UX, AS/400, system 390). </p>
- <p>If C++ Namespace support is ENABLED (all the binary
- distributions of &XercesCName; &XercesC3Version; are built
- with C++ Namespace enabled), users' applications must
- namespace qualify all the &XercesCName; classes, data and
- variables with <code>XERCES_CPP_NAMESPACE_QUALIFIER </code>
- or add the <code>XERCES_CPP_NAMESPACE_USE</code>
- statement. Users also need to ensure all forward
- declarations are properly qualified or scoped.</p>
-
- <p>Note: If If C++ Namespace support is ENABLED,
- <code>XERCES_CPP_NAMESPACE_QUALIFIER</code> expands to the
- &XercesCName; namespace name followed by two colons, and
- <code>XERCES_CPP_NAMESPACE_USE</code> expands to the full
- <code>using namespace</code> statement, including the
- semicolon. Do NOT add colons or semicolons following these
- macros in your source.</p>
-
- <p>If C++ Namespace support is not enabled, both macros expand
- to an empty string. The same holds for macros
- <code>XERCES_CPP_NAMESPACE_BEGIN</code> and
- <code>XERCES_CPP_NAMESPACE_END</code>, introduced in the
- example below. You will also see all of these macros used
- throughout the &XercesCName; source code.</p>
-
- <p>For example:</p>
-
-<source>
-#include <stdio.h>
-#include <stdlib.h>
-#include <xercesc/sax/HandlerBase.hpp>
+ <p>Some earlier releases of &XercesCName; defined XMLCh to be the
+ same type as wchar_t on most platforms, with the goal of making
+ it possible to pass XMLCh strings to library or system functions
+ that were expecting wchar_t parameters. This approach has
+ been abandoned because of</p>
-// indicate using &XercesCName; namespace in general
-XERCES_CPP_NAMESPACE_USE
+ <ul>
+ <li>
+ Portability problems with any code that assumes that
+ the types of XMLCh and wchar_t are compatible
+ </li>
+
+ <li>Excessive memory usage, especially in the DOM, on
+ platforms with 32 bit wchar_t.
+ </li>
+
+ <li>utf-16 encoded XMLCh is not always compatible with
+ ucs-4 encoded wchar_t on Solaris and Linux. The
+ problem occurs with Unicode characters with values
+ greater than 64k; in ucs-4 the value is stored as
+ a single 32 bit quantity. With utf-16, the value
+ will be stored as a "surrogate pair" of two 16 bit
+ values. Even with XMLCh equated to wchar_t, xerces will
+ still create the utf-16 encoded surrogate pairs, which
+ are illegal in ucs-4 encoded wchar_t strings.
+ </li>
+ </ul>
-// need to properly scope any forward declarations
-XERCES_CPP_NAMESPACE_BEGIN
- class AttributeList;
-XERCES_CPP_NAMESPACE_END
-// or namespace qualifier the forward declarations
-class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
+ </s2>
-class MySAXHandlers : public HandlerBase
-{
-public:
- // -----------------------------------------------------------------------
- // Handlers for the SAX DocumentHandler interface
- // -----------------------------------------------------------------------
- void startElement(const XMLCh* const name, AttributeList& attributes);
- void characters(const XMLCh* const chars, const unsigned int length);
-:
-:
-};
-</source>
+ <anchor name="CPPNamespace"/>
+ <s2 title="Using C++ Namespace">
- <p>All macros used above are defined in header file <code>xercesc/util/XercesDefs.hpp</code>:</p>
+ <p>&XercesCName; makes use of C++ namespace to make sure its
+ definitions do not conflict with other libraries and
+ applications. As a result applications must
+ namespace-qualify all &XercesCName; classes, data and
+ variables using the <code>xercesc</code> name. Alternatively,
+ applications can use <code>using xercesc::<Name>;</code>
+ declarations
+ to make individual &XercesCName; names visible in the
+ current scope
+ or <code>using namespace xercesc;</code>
+ definition to make all &XercesCName; names visible in the
+ current scope.</p>
+
+ <p>While the above information should be sufficient for the majority
+ of applications, for cases where several versions of the &XercesCName;
+ library must be used in the same application, namespace versioning is
+ provided. The following convenience macros can be used to access the
+ &XercesCName; namespace names with versions embedded
+ (see <code>src/xercesc/util/XercesDefs.hpp</code>):</p>
<source>
-#if defined(XERCES_HAS_CPP_NAMESPACE)
#define XERCES_CPP_NAMESPACE_BEGIN namespace &XercesC3NSVersion; {
#define XERCES_CPP_NAMESPACE_END }
#define XERCES_CPP_NAMESPACE_USE using namespace &XercesC3NSVersion;;
@@ -470,111 +411,32 @@ public:
namespace &XercesC3NSVersion; { }
namespace &XercesC3Namespace; = &XercesC3NSVersion;;
-#else
- #define XERCES_CPP_NAMESPACE_BEGIN
- #define XERCES_CPP_NAMESPACE_END
- #define XERCES_CPP_NAMESPACE_USE
- #define XERCES_CPP_NAMESPACE_QUALIFIER
-#endif
-</source>
-
- <p>Users should make use of these pre-defined macro in their applications. For example:</p>
-<source>
-#include <stdio.h>
-#include <stdlib.h>
-#include <xercesc/sax/HandlerBase.hpp>
-
-// indicate using &XercesCName; namespace in general
-XERCES_CPP_NAMESPACE_USE
-
-// need to properly scope any forward declarations
-XERCES_CPP_NAMESPACE_BEGIN
-class AttributeList;
-XERCES_CPP_NAMESPACE_END
-
-// or namespace qualify the forward declarations
-class XERCES_CPP_NAMESPACE_QUALIFIER ErrorHandler;
-
-class MySAXHandlers : public HandlerBase
-{
-public:
- // -----------------------------------------------------------------------
- // Handlers for the SAX DocumentHandler interface
- // -----------------------------------------------------------------------
- void startElement(const XMLCh* const name, AttributeList& attributes);
- void characters(const XMLCh* const chars, const unsigned int length);
-:
-:
-};
</source>
-
- <p>For those users who want to selectively pick which version of API to use, they can do
- something like the code below (Note that this is not the best of examples, as the
- API is the same in all versions):</p>
-
-<source>
-#if _XERCES_VERSION == 20300
- // code specific to Xerces-C++ version 2.3.0
- new xercesc_2_3::SAXParser();
-#elif _XERCES_VERSION == 20200
- // code specific to Xerces-C++ version 2.2.0
- new xercesc_2_2::SAXParser();
-#else
- // old code here...
- new SAXParser();
-#endif
-</source>
-
- <p>But for those who just want to call the latest API, then they should use
- the macro <code>XERCES_CPP_NAMESPACE_QUALIFIER</code>
- for source compatibility:</p>
-
-<source>
-new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
-</source>
-
- <p>Header file <code>xercesc/util/XercesDefs.hpp</code> also
- declares <code>namespace &XercesC3Namespace;</code> as a
- generic namespace name which will be assigned to
- <code>xercesc_YY_ZZ</code> in each specific release, where
- "YY" is the Major Release Number and "ZZ" is the Minor
- Version Number. However, when you use
- <code>&XercesC3Namespace;::</code> instead of
- <code>XERCES_CPP_NAMESPACE_QUALIFIER </code> when your
- compiler does not support namespaces, your code will not
- work.</p>
-
-
-
</s2>
<anchor name="SpecifyLocaleForMessageLoader"/>
<s2 title="Specify Locale for Message Loader">
- <p>The &XercesCName; has implemented mechanism to support NLS, though
- the current drop has only English version message file, it is capable
- to support other languages once the translated version of the target
- language is available.</p>
+ <p>&XercesCName; provides mechanisms for Native Language Support (NLS).
+ Even though
+ the current distribution has only English message file, it is capable
+ of supporting other languages once the translated version of the
+ target language is available.</p>
- <p>Application can specify the locale for the message loader in their
+ <p>An application can specify the locale for the message loader in their
very first invocation to XMLPlatformUtils::Initialize() by supplying
a parameter for the target locale intended. The default locale is "en_US".
</p>
-
<source>
-
-...
// Initialize the parser system
try
{
XMLPlatformUtils::Initialize("fr_FR");
}
-
catch ()
{
}
-..
</source>
</s2>
@@ -582,64 +444,58 @@ new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
<anchor name="SpecifyLocationForMessageLoader"/>
<s2 title="Specify Location for Message Loader">
- <p>The &XercesCName; searches for message files at the default message directory, $XERCESCROOT/msg.
+ <p>&XercesCName; searches for message files at the location
+ specified in the <code>XERCESC_NLS_HOME</code> environment
+ variable and, if that is not set, at the default
+ message directory, <code>$XERCESCROOT/msg</code>.
</p>
<p>Application can specify an alternative location for the message files in their
very first invocation to XMLPlatformUtils::Initialize() by supplying
- a parameter for the alternative location intended.
+ a parameter for the alternative location.
</p>
<source>
-
-...
// Initialize the parser system
try
{
- XMLPlatformUtils::Initialize("en_US", "/usr/application_root/msg_home");
+ XMLPlatformUtils::Initialize("en_US", "/usr/nls");
}
-
catch ()
{
}
-..
</source>
</s2>
<anchor name="PluggablePanicHandler"/>
<s2 title="Pluggable Panic Handler">
- <p>The &XercesCName; reports, through the method panic(), any panic encountered,
- to the panic handler installed, which in turn takes whatever action appropriate,
- to handle the panic.
+ <p>&XercesCName; reports panic conditions encountered to the panic
+ handler installed. The panic handler can take whatever action
+ appropriate to handle the panic condition.
</p>
- <p>The &XercesCName; allows application plugging a customized panic handler
- (class implementing the interface PanicHandler), in its very first invocation to
- XMLPlatformUtils::Initialize() by supplying a parameter for the panic handler
- intended.
+ <p>&XercesCName; allows application to provide a customized panic handler
+ (class implementing the interface PanicHandler), in its very first invocation of
+ XMLPlatformUtils::Initialize().
</p>
- <p>In the absence of such a plugged panic handler, &XercesCName; default
+ <p>In the absence of an application-specific panic handler, &XercesCName; default
panic handler is installed and used, which aborts program whenever a panic
- is seen.
+ condition is encountered.
</p>
<source>
-
-...
// Initialize the parser system
try
{
PanicHandler* ph = new MyPanicHandler();
- XMLPlatformUtils::Initialize("en_US"
- , "/usr/application_root/msg_home"
- , ph);
+ XMLPlatformUtils::Initialize("en_US",
+ "/usr/nls",
+ ph);
}
-
catch ()
{
}
-..
</source>
</s2>
@@ -650,29 +506,18 @@ new XERCES_CPP_NAMESPACE_QUALIFIER SAXParser();
from crashes of individual components, as well as to allocate
memory more efficiently than a general-purpose OS-level
procedure with no knowledge of the characteristics of the
- program making the requests for memory. As of Xerces-C 2.3.0 this
+ program making the requests for memory. In &XercesCName; this
is supported via the Pluggable Memory Handler.
</p>
- <p>Users that have no particular memory management
- requirements (beyond that components don't leak memory or
- attempt to read from or write to areas of memory they haven't
- been assigned), should notice no behavioural changes in the
- parser, so long as their code conforms to Xerces-C best
- practices (e.g., avoids implicit destruction of objects
- related to the parser after XMLPlatformUtils::Terminate() has
- been called; see <jump href="faq-parse-&XercesC3Series;.html#faq-7">the FAQ
- entry describing a reason why applications may suddenly start
- segfaulting with Xerces-C 2.3.0</jump> for details.). Such users can ignore this subsection and
- continue using the parser as they always had.
- </p>
+
<p>Users who wish to implement their own MemoryManager,
- an interface found in xercesc/framework/MemoryManager.hpp, need
- implement only two methods:</p>
+ an interface found in <code>xercesc/framework/MemoryManager.hpp</code>,
+ need to implement only two methods:</p>
<source>
// This method allocates requested memory.
// the parameter is the requested memory size
// A pointer to the allocated memory is returned.
-virtual void* allocate(size_t size) = 0;
+virtual void* allocate(XMLSize_t size) = 0;
// This method deallocates memory
// The parameter is a pointer to the allocated memory to be deleted
@@ -707,48 +552,12 @@ XercesDOMParser *parser = new
delete parser;
XMLPlatformUtils::Terminate();
</source>
- <p>
- Notice that, to maintain backward compatibility, the
- MemoryManager parameter is positioned last in the list of
- parameters to XMLPlatformUtils::Initialize(); this means that
- all other parameters must be specified with their defaults as
- found in Xerces code if all other aspects of standard
- behaviour are to be preserved.
- </p>
<p>
If a user provides a MemoryManager object to the parser, then
the user owns that object. It is also important to note that
- Xerces default implementation simply uses the global new and
- delete.
+ &XercesCName; default implementation simply uses the global
+ new and delete operators.
</p>
- <p>
- Finally, there are two platform/compiler-related
- limitations of our memory handling facilities that
- certain users will need to be aware of:
- </p>
- <ul>
- <li>The compiler shipped with HPUX 11 does not understand
- "placement" delete operators. These versions of delete
- have the same signature as our "placement" new operators
- but will only be invoked when an exception is thrown
- during the construction of an object. Since the HP
- compiler does not permit delete to be overridden twice
- within a class, we cannot provide a placement delete;
- hence, in the few cases in which an exception may be
- thrown during object construction by Xerces, destructors of objects
- created during that construction will not be called.</li>
- <li>There is a bug in versions of GCC older than 2.96
- which makes it impossible to have the pluggable memory
- manager create elements in the
- <code>RefHash3KeysIdPool</code> template hashtable.
- Therefore, on this compiler, we must use global new for
- this purpose. These elements will be properly destroyed
- under this compiler; the limitation is that, since the
- pluggable memory manager cannot be used, these particular
- elements will not be destroyed if the user destroys their
- memory manager directly. Note that this hashtable is not
- used that often in Xerces.</li>
- </ul>
</s2>
<anchor name="SecurityManager"/>
@@ -778,11 +587,11 @@ XMLPlatformUtils::Terminate();
that should suit most applications.
</p>
<p>
- By default, Xerces-C is a wholly conformant XML parser; that
+ By default, &XercesCName; is a wholly conformant XML parser; that
is, no security-related considerations will be observed by
- default. An application must set an instance of the
- SecurityManager class on a Xerces parser in order to make that
- parser behave in a security-conscious manner. i.e.:
+ default. An application must provide an instance of the
+ SecurityManager class to a parser in order to make that
+ parser behave in a security-conscious manner. For example:
</p>
<source>
SAXParser *myParser = new SAXParser();
@@ -793,13 +602,13 @@ myParser->setSecurityManager(myManager);
</source>
<p>
Note that SecurityManager instances may be set on all kinds of
- Xerces parsers; please see the documentation for the
+ &XercesCName; parsers; please see the documentation for the
individual parsers for details.
</p>
<p>
Note also that the application always owns the SecurityManager
- instance. The default SecurityManager that Xerces provides is
- not thread-safe; although it only uses primitive operations at
+ instance. The default SecurityManager that &XercesCName; provides
+ is not thread-safe; although it only uses primitive operations at
the moment, users may need to extend the class with a
thread-safe implementation on some platforms.
</p>
@@ -807,10 +616,10 @@ myParser->setSecurityManager(myManager);
<anchor name="UseSpecificScanner"/>
<s2 title="Use Specific Scanner">
- <p>For performance and modularity, the &XercesCName; has implemented a mechanism
- to allow users to specify the scanner to use when scanning an XML document.
- Such mechanism will enable the creation of special purpose scanners that can be easily
- plugged in.</p>
+ <p>For performance and modularity &XercesCName; provides a mechanism
+ for specifying the scanner to be used when scanning an XML document.
+ Such mechanism will enable the creation of special purpose scanners
+ that can be easily plugged in.</p>
<p>&XercesCName; supports the following scanners:</p>
@@ -893,10 +702,12 @@ parser->setFeature(XMLUni::fgXercesSchemaFullChecking, false);
<source>
// Create a DOMLSParser parser
-DOMLSParser *parser = ((DOMImplementationLS*)impl)->createLSParser(DOMImplementationLS::MODE_SYNCHRONOUS, 0);
+DOMLSParser *parser = ((DOMImplementationLS*)impl)->createLSParser(
+ DOMImplementationLS::MODE_SYNCHRONOUS, 0);
// Specify scanner name - This is optional as IGXMLScanner is the default
-parser->getDomConfig()->setParameter(XMLUni::fgXercesScannerName, (void *)XMLUni::fgIGXMLScanner);
+parser->getDomConfig()->setParameter(
+ XMLUni::fgXercesScannerName, (void *)XMLUni::fgIGXMLScanner);
// Specify other parser features, e.g.
parser->getDomConfig()->setParameter(XMLUni::fgDOMNamespaces, doNamespaces);
diff --git a/doc/program-sax.xml b/doc/program-sax.xml
index 9cd0dad8d..e0b7ae251 100644
--- a/doc/program-sax.xml
+++ b/doc/program-sax.xml
@@ -18,7 +18,7 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="SAX1 Programming Guide">
+<s1 title="SAX Programming Guide">
<anchor name="UsingSAX1API"/>
<s2 title="Using the SAX API">
@@ -36,11 +36,11 @@
commonly used handler classes are DocumentHandler which is
called when XML constructs are recognized, and ErrorHandler
which is called when an error occurs. The header files for the
- various SAX handler classes are in
- '<&XercesC3InstallDir;>/include/xercesc/sax'</p>
+ various SAX handler classes are in the <code>xercesc/sax/</code>
+ directory.</p>
- <p>As a convenience, &XercesCName; provides the class
- HandlerBase, which is a single class which is publicly derived
+ <p>As a convenience, &XercesCName; provides
+ HandlerBase, a single class which is publicly derived
from all the Handler classes. HandlerBase's default
implementation of the handler callback methods is to do
nothing. A convenient way to get started with &XercesCName; is
@@ -63,7 +63,9 @@ public:
<p>This is the implementation file MySAXHandler.cpp:</p>
<source>#include "MySAXHandler.hpp"
-#include <iostream.h>
+#include <iostream>
+
+using namespace std;
MySAXHandler::MySAXHandler()
{
@@ -87,8 +89,8 @@ void MySAXHandler::fatalError(const SAXParseException& exception)
}</source>
<p>The XMLCh and AttributeList types are supplied by
- &XercesCName; and are documented in the include
- files. Examples of their usage appear in the source code to
+ &XercesCName; and are documented in the API reference.
+ Examples of their usage appear in the source code for
the sample applications.</p>
</s2>
@@ -96,7 +98,7 @@ void MySAXHandler::fatalError(const SAXParseException& exception)
<s2 title="SAXParser">
<anchor name="ConstructParser"/>
<s3 title="Constructing a SAXParser">
- <p>In order to use &XercesCName; to parse XML files, you will
+ <p>In order to use &XercesCName; SAX to parse XML files, you will
need to create an instance of the SAXParser class. The example
below shows the code you need in order to create an instance
of SAXParser. The DocumentHandler and ErrorHandler instances
@@ -108,13 +110,10 @@ void MySAXHandler::fatalError(const SAXParseException& exception)
#include <xercesc/sax/HandlerBase.hpp>
#include <xercesc/util/XMLString.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
diff --git a/doc/program-sax2.xml b/doc/program-sax2.xml
index 349c08a2e..6980baf63 100644
--- a/doc/program-sax2.xml
+++ b/doc/program-sax2.xml
@@ -36,11 +36,11 @@
commonly used handler classes are ContentHandler which is
called when XML constructs are recognized, and ErrorHandler
which is called when an error occurs. The header files for the
- various SAX2 handler classes are in
- '<&XercesC3InstallDir;>/include/xercesc/sax2'</p>
+ various SAX2 handler classes are in the <code>xercesc/sax2/</code>
+ directory.</p>
- <p>As a convenience, &XercesCName; provides the class
- DefaultHandler, which is a single class which is publicly derived
+ <p>As a convenience, &XercesCName; provides DefaultHandler,
+ a single class which is publicly derived
from all the Handler classes. DefaultHandler's default
implementation of the handler callback methods is to do
nothing. A convenient way to get started with &XercesCName; is
@@ -68,7 +68,9 @@ public:
<p>This is the implementation file MySAX2Handler.cpp:</p>
<source>#include "MySAX2Handler.hpp"
-#include <iostream.h>
+#include <iostream>
+
+using namespace std;
MySAX2Handler::MySAX2Handler()
{
@@ -94,8 +96,8 @@ void MySAX2Handler::fatalError(const SAXParseException& exception)
}</source>
<p>The XMLCh and Attributes types are supplied by
- &XercesCName; and are documented in the include
- files. Examples of their usage appear in the source code to
+ &XercesCName; and are documented in the API Reference.
+ Examples of their usage appear in the source code to
the sample applications.</p>
</s2>
@@ -103,11 +105,11 @@ void MySAX2Handler::fatalError(const SAXParseException& exception)
<s2 title="SAX2XMLReader">
<anchor name="ConstructParser2"/>
<s3 title="Constructing an XML Reader">
- <p>In order to use &XercesCName; to parse XML files, you will
+ <p>In order to use &XercesCName; SAX2 to parse XML files, you will
need to create an instance of the SAX2XMLReader class. The example
below shows the code you need in order to create an instance
of SAX2XMLReader. The ContentHandler and ErrorHandler instances
- required by the SAX API are provided using the DefaultHandler
+ required by the SAX2 API are provided using the DefaultHandler
class supplied with &XercesCName;.</p>
<source>
@@ -116,13 +118,10 @@ void MySAX2Handler::fatalError(const SAXParseException& exception)
#include <xercesc/sax2/DefaultHandler.hpp>
#include <xercesc/util/XMLString.hpp>
- #if defined(XERCES_NEW_IOSTREAMS)
#include <iostream>
- #else
- #include <iostream.h>
- #endif
- XERCES_CPP_NAMESPACE_USE
+ using namespace std;
+ using namespace xercesc;
int main (int argc, char* args[]) {
diff --git a/doc/program.xml b/doc/program.xml
index 51da26a2a..6c55d13aa 100644
--- a/doc/program.xml
+++ b/doc/program.xml
@@ -29,7 +29,8 @@
<source>
#include <xercesc/util/PlatformUtils.hpp>
// Other include files, declarations, and non-&XercesCName; initializations.
-XERCES_CPP_NAMESPACE_USE
+
+using namespace xercesc;
int main(int argc, char* argv[])
{
@@ -97,19 +98,6 @@ int main(int argc, char* argv[])
</ul>
</s2>
- <s2 title="SAX Programming Guide">
- <p>Read the <jump href="program-sax-&XercesC3Series;.html">SAX Programming Guide</jump> document
- or jump directly to:</p>
- <ul>
- <li><jump href="program-sax-&XercesC3Series;.html#UsingSAX1API">Using the SAX API</jump></li>
- <li><jump href="program-sax-&XercesC3Series;.html#SAXParser">SAXParser</jump></li>
- <ul>
- <li><jump href="program-sax-&XercesC3Series;.html#ConstructParser">Constructing a SAXParser</jump></li>
- <li><jump href="program-sax-&XercesC3Series;.html#SAXFeatures">Supported Features</jump></li>
- </ul>
- </ul>
- </s2>
-
<s2 title="SAX2 Programming Guide">
<p>Read the <jump href="program-sax2-&XercesC3Series;.html">SAX2 Programming Guide</jump> document
or jump directly to:</p>
@@ -124,6 +112,19 @@ int main(int argc, char* argv[])
</ul>
</s2>
+ <s2 title="SAX Programming Guide">
+ <p>Read the <jump href="program-sax-&XercesC3Series;.html">SAX Programming Guide</jump> document
+ or jump directly to:</p>
+ <ul>
+ <li><jump href="program-sax-&XercesC3Series;.html#UsingSAX1API">Using the SAX API</jump></li>
+ <li><jump href="program-sax-&XercesC3Series;.html#SAXParser">SAXParser</jump></li>
+ <ul>
+ <li><jump href="program-sax-&XercesC3Series;.html#ConstructParser">Constructing a SAXParser</jump></li>
+ <li><jump href="program-sax-&XercesC3Series;.html#SAXFeatures">Supported Features</jump></li>
+ </ul>
+ </ul>
+ </s2>
+
<s2 title="Other Features">
<p>Read the <jump href="program-others-&XercesC3Series;.html">&XercesCName; Programming Guide</jump> document
or jump directly to:</p>
@@ -131,7 +132,7 @@ int main(int argc, char* argv[])
<li><jump href="program-others-&XercesC3Series;.html#Macro">Version Macros</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#Schema">Schema Support</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#Progressive">Progressive Parsing</jump></li>
- <li><jump href="program-others-&XercesC3Series;.html#GrammarCache">Preparsing Grammar and Grammar Caching</jump></li>
+ <li><jump href="program-others-&XercesC3Series;.html#GrammarCache">Pre-parsing Grammar and Grammar Caching</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#LoadableMessageText">Loadable Message Text</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#PluggableTranscoders">Pluggable Transcoders</jump></li>
<li><jump href="program-others-&XercesC3Series;.html#PortingGuidelines">Porting Guidelines</jump></li>
diff --git a/doc/psviwriter.xml b/doc/psviwriter.xml
index a3458eb47..a8a43a80f 100644
--- a/doc/psviwriter.xml
+++ b/doc/psviwriter.xml
@@ -21,7 +21,7 @@
<s1 title="Sample: PSVIWriter">
<s2 title="PSVIWriter">
- <p>PSVIWriter shows how to access the PSVI and Schema Component Model
+ <p>PSVIWriter shows how to access the Post Schema Validation Infoset (PSVI) and Schema Component Model
information for the parsed document.</p>
<s3 title="Running PSVIWriter">
@@ -48,11 +48,11 @@ Options:
</source>
<p>Here is some sample output from PSVWriter (as the output is verbose
it has been truncated)</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
PSVIWriter personal.xml
-<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:psv="http://apache.org/xml/2001/PSVInfosetExtension"
+<document xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:psv="http://apache.org/xml/2001/PSVInfosetExtension"
xmlns="http://www.w3.org/2001/05/XMLInfoset">
<characterEncodingScheme>UTF8</characterEncodingScheme>
<standalone xsi:nil="true"/>
@@ -62,7 +62,7 @@ PSVIWriter personal.xml
<content> @version: </content>
</comment>
-...
+...
</source>
</s3>
</s2>
diff --git a/doc/redirect.xml b/doc/redirect.xml
index b0c380f84..63f67c3da 100644
--- a/doc/redirect.xml
+++ b/doc/redirect.xml
@@ -24,13 +24,13 @@
<p>Redirect uses the SAX EntityResolver handler to redirect the
input stream for external entities. It installs an entity
resolver, traps the call to the external DTD file and redirects
- it to another specific file which contains the actual DTD.</p>
+ it to another file which contains the actual DTD.</p>
<s3 title="Running Redirect">
- <p>This program illustrates how a XML application can use the SAX EntityResolver
+ <p>This program illustrates how an application can use the SAX EntityResolver
handler to redirect the input stream for external entities. It installs an entity
- resolver, traps the call to the external DTD file and redirects it to another specific
+ resolver, traps the call to the external DTD file and redirects it to another
file which contains the actual DTD.</p>
<p>The program then counts and reports the number of elements and attributes in
@@ -38,10 +38,10 @@
<source>Redirect <XML file></source>
<p>Redirect is invoked as follows:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
Redirect personal.xml</source>
<p>The output is the following:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
Redirect personal.xml
personal.xml: 30 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
@@ -58,7 +58,7 @@ personal.xml: 30 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
redirect all references to entities outside of its domain to local cached copies.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
diff --git a/doc/samples.xml b/doc/samples.xml
index 6095e16fb..2979c3d3c 100644
--- a/doc/samples.xml
+++ b/doc/samples.xml
@@ -21,10 +21,11 @@
<s1 title="&XercesCName; Samples">
<s2 title="Introduction">
- <p>&XercesCName; comes packaged with sample applications that
- demonstrate salient features of the parser using simple
+ <p>&XercesCName; comes with sample applications that
+ demonstrate salient features of the parser. They are simple
applications written on top of the SAX and DOM APIs provided by
- the parser. Sample XML data files are provided in the samples/data directory.</p>
+ the parser. Sample XML data files are provided in the
+ <code>samples/data</code> directory.</p>
</s2>
<s2 title="Running the Samples">
@@ -35,64 +36,54 @@
environment variable is set properly to pick up these shared libraries at
runtime.</p>
- <p>On UNIX platforms you must ensure that <ref>LIBPATH</ref>
+ <p>On UNIX platforms you must ensure that <code>LD_LIBRARY_PATH</code>
environment variable is set properly to pick up the shared libraries at
- runtime. (UNIX gurus will understand here that <ref>LIBPATH</ref> actually
- translates to <em>LD_LIBRARY_PATH</em> on Solaris and Linux, <em>SHLIB_PATH</em> on HP-UX,
- <em>DYLD_LIBRARY_PATH</em> on Mac OS X,
- and stays as <em>LIBPATH</em> on AIX).</p>
+ runtime. (UNIX gurus will understand here that <code>LD_LIBRARY_PATH</code>
+ actually translates to <code>LD_LIBRARY_PATH</code> on Solaris and Linux,
+ <code>SHLIB_PATH</code> on HP-UX, <code>DYLD_LIBRARY_PATH</code> on Mac OS X,
+ and <code>LIBPATH</code> on AIX).</p>
- <p>To set you LIBPATH (on AIX for example), you would type:</p>
-
- <source>export LIBPATH=&XercesC3InstallDir;/lib:$LIBPATH</source>
-
- <p>On both Windows and UNIX platforms, if the parser is built with icu message loader
- (like IBM XML4C binaries), or message catalog loader, then you need to set another environment
- variable, XERCESC_NLS_HOME to point to the directory, &XercesC3SrcInstallDir;/msg, where
- the message files reside.
+ <p>On both Windows and UNIX platforms, if the parser is built with the ICU
+ message loader or message catalog loader, then you may need to set another
+ environment variable, <code>XERCESC_NLS_HOME</code>, to point to the
+ &XercesC3SrcInstallDir;/msg directory, which is where the message
+ files reside.
</p>
-<source>
-set XERCESC_NLS_HOME=&XercesC3InstallDir;\msg
-or
-export XERCESC_NLS_HOME=&XercesC3InstallDir;/msg
-or
-setenv XERCESC_NLS_HOME=&XercesC3InstallDir;/msg
-</source>
<p>Once you have set up the environment variables, you can run the
samples by opening a command window (or your shell prompt for
UNIX environments).</p>
- <s3 title="&XercesCName; Samples">
+ <s3 title="&XercesCName; Samples">
<ul>
<li><link idref="saxcount-&XercesC3Series;">SAXCount</link>
<br/>SAXCount counts the elements, attributes, spaces and
characters in an XML file.</li>
<li><link idref="saxprint-&XercesC3Series;">SAXPrint</link>
<br/>SAXPrint parses an XML file and prints it out.</li>
+ <li><link idref="sax2count-&XercesC3Series;">SAX2Count</link>
+ <br/>SAX2Count counts the elements, attributes, spaces and
+ characters in an XML file.</li>
+ <li><link idref="sax2print-&XercesC3Series;">SAX2Print</link>
+ <br/>SAX2Print parses an XML file and prints it out.</li>
<li><link idref="domcount-&XercesC3Series;">DOMCount</link>
<br/>DOMCount counts the elements in a XML file.</li>
<li><link idref="domprint-&XercesC3Series;">DOMPrint</link>
<br/>DOMPrint parses an XML file and prints it out.</li>
+ <li><link idref="createdoc-&XercesC3Series;">CreateDOMDocument</link>
+ <br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
<li><link idref="memparse-&XercesC3Series;">MemParse</link>
- <br/>MemParse parses XML in a memory buffer, outputing the number of elements and attributes.</li>
+ <br/>MemParse parses XML in a memory buffer, printing the number of elements and attributes.</li>
<li><link idref="redirect-&XercesC3Series;">Redirect</link>
<br/>Redirect redirects the input stream for external entities.</li>
<li><link idref="pparse-&XercesC3Series;">PParse</link>
<br/>PParse demonstrates progressive parsing.</li>
<li><link idref="stdinparse-&XercesC3Series;">StdInParse</link>
<br/>StdInParse demonstrates streaming XML data from standard input.</li>
- <li><link idref="enumva-&XercesC3Series;">EnumVal</link>
- <br/>EnumVal shows how to enumerate the markup decls in a DTD Grammar.</li>
+ <li><link idref="enumval-&XercesC3Series;">EnumVal</link>
+ <br/>EnumVal shows how to enumerate the markup declarations in a DTD Grammar.</li>
<li><link idref="senumval-&XercesC3Series;">SEnumVal</link>
- <br/>SEnumVal shows how to enumerate the markup decls in a Schema Grammar.</li>
- <li><link idref="createdoc-&XercesC3Series;">CreateDOMDocument</link>
- <br/>CreateDOMDocument creates a DOM tree in memory from scratch.</li>
- <li><link idref="sax2count-&XercesC3Series;">SAX2Count</link>
- <br/>SAX2Count counts the elements, attributes, spaces and
- characters in an XML file.</li>
- <li><link idref="sax2print-&XercesC3Series;">SAX2Print</link>
- <br/>SAX2Print parses an XML file and prints it out.</li>
+ <br/>SEnumVal shows how to enumerate the markup declarations in a Schema Grammar.</li>
<li><link idref="psviwriter-&XercesC3Series;">PSVIWriter</link>
<br/>PSVIWriter exposes the underlying PSVI of the parsed XML file.</li>
<li><link idref="scmprint-&XercesC3Series;">SCMPrint</link>
diff --git a/doc/sax2count.xml b/doc/sax2count.xml
index fdeef4263..640e8a0fc 100644
--- a/doc/sax2count.xml
+++ b/doc/sax2count.xml
@@ -21,13 +21,13 @@
<s1 title="Sample: SAX2Count">
<s2 title="SAX2Count">
- <p>SAX2Count is the simplest application that counts the elements and characters of
+ <p>SAX2Count is a simple application that counts the elements and characters of
a given XML file using the (event based) SAX2 API.</p>
<s3 title="Running SAX2Count">
- <p>The SAX2Count sample parses an XML file and prints out a count of the number of
- elements in the file. To run SAX2Count, enter the following </p>
+ <p>The SAX2Count sample parses an XML file and prints out the number of
+ elements and characters in the file. To run SAX2Count, enter the following </p>
<source>SAX2Count <XML File></source>
<p>The following parameters may be set from the command line </p>
<source>
@@ -47,7 +47,7 @@ Options:
NOTE: THIS IS OPPOSITE FROM OTHER SAMPLES.
-s Disable schema processing. Defaults to on.
NOTE: THIS IS OPPOSITE FROM OTHER SAMPLES.
- -locale=ll_CC specify the locale, default: en_US
+ -locale=ll_CC specify the locale, default: en_US
-? Show this help.
* = Default if not provided explicitly.
@@ -56,7 +56,7 @@ Options:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAX2Count</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAX2Count -v=always personal.xml
personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)</source>
<p>Running SAX2Count with the validating parser gives a different result because
@@ -66,7 +66,7 @@ personal.xml: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
diff --git a/doc/sax2print.xml b/doc/sax2print.xml
index 7006e299a..befb38cca 100644
--- a/doc/sax2print.xml
+++ b/doc/sax2print.xml
@@ -70,7 +70,7 @@ The parser has intrinsic support for the following encodings:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAX2Print</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAX2Print -v=always personal.xml
<?xml version="1.0" encoding="LATIN1"?>
diff --git a/doc/saxcount.xml b/doc/saxcount.xml
index eacdc914b..46cf12962 100644
--- a/doc/saxcount.xml
+++ b/doc/saxcount.xml
@@ -26,7 +26,7 @@
<s3 title="Running SAXCount">
- <p>The SAXCount sample parses an XML file and prints out a count of the number of
+ <p>The SAXCount sample parses an XML file and prints out the number of
elements in the file. To run SAXCount, enter the following </p>
<source>SAXCount <XML File></source>
<p>The following parameters may be set from the command line </p>
@@ -45,7 +45,7 @@ Options:
-n Enable namespace processing. Defaults to off.
-s Enable schema processing. Defaults to off.
-f Enable full schema constraint checking. Defaults to off.
- -locale=ll_CC specify the locale, default: en_US
+ -locale=ll_CC specify the locale, default: en_US
-? Show this help.
* = Default if not provided explicitly.
@@ -54,7 +54,7 @@ Options:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAXCount</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAXCount -v=always personal.xml
personal.xml: 60 ms (37 elems, 12 attrs, 134 spaces, 134 chars)</source>
<p>Running SAXCount with the validating parser gives a different result because
@@ -64,7 +64,7 @@ personal.xml: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
diff --git a/doc/saxprint.xml b/doc/saxprint.xml
index b73c75257..1e1a3e611 100644
--- a/doc/saxprint.xml
+++ b/doc/saxprint.xml
@@ -66,7 +66,7 @@ The parser has intrinsic support for the following encodings:
<em>-v=never</em> will not use any validation<br/>
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Here is a sample output from SAXPrint</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SAXPrint -v=always personal.xml
<?xml version="1.0" encoding="LATIN1"?>
diff --git a/doc/schema.xml b/doc/schema.xml
index 8e7897b8d..1cdb03a93 100644
--- a/doc/schema.xml
+++ b/doc/schema.xml
@@ -17,35 +17,28 @@
-->
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="Schema">
+<s1 title="XML Schema Support">
<s2 title="Introduction">
- <p>This package contains an implementation of the W3C XML Schema
- Language, a recommendation of the Worldwide Web Consortium
+ <p>&XercesCName; includes an implementation of the W3C XML Schema
+ specification, a recommendation of the Worldwide Web Consortium
available in three parts:
- <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump> and
+ <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump>,
<jump href="http://www.w3.org/TR/xmlschema-1/">XML Schema: Structures</jump> and
<jump href="http://www.w3.org/TR/xmlschema-2/">XML Schema: Datatypes</jump>.
- We consider this implementation complete except for the limitations cited below.
- </p>
-
- <p>We would very much appreciate feedback on the package via the
- <jump href="&MailURI;">&XercesCName; mailing lists</jump>,
- and we encourage the submission of bugs as described on the
- <jump href="&BugURI;">Bug Reporting</jump> page. Please
- read this document before using this package.
+ We consider this implementation complete except for the limitations outlined below.
</p>
</s2>
<anchor name="limitation"/>
<s2 title="Limitations">
<ul>
- <li>Due to the way in which the parser constructs content
- models for elements with complex content, specifying large
+ <li>In certain complex content models specifying large
values for the <code>minOccurs</code> or <code>maxOccurs</code>
- attributes may cause a stack overflow or very poor performance
- in the parser. Large values for <code>minOccurs</code> should be
- avoided, and <code>unbounded</code> should be used instead of
- a large value for <code>maxOccurs</code>.</li>
+ attributes may result in poor performance and/or large amount
+ of memory being allocated by the parser. In such situations large values for
+ <code>minOccurs</code> should be avoided, and <code>unbounded</code>
+ should be used instead.</li>
+
<li>The parser treats local elements in the same scope with the
same name and namespace as one element declaration and does not
differentiate between them.</li>
@@ -66,8 +59,8 @@
<s3 title="out-of-bound float values">
<p>
- For float data, the specs does not explicitly specify how to deal with
- out-of-bound data. Xerces converts these values as below (the values
+ For float data, the specification does not explicitly prescribe how to deal with
+ out-of-bound data. &XercesCName; converts these values as shown below (the values
depend on the system specific values of FLT_MAX and FLT_MIN):
</p>
<table>
@@ -102,7 +95,7 @@
<s3 title="out-of-bound double values">
<p>
- Similarly, Xerces converts double values as below (the values
+ Similarly, &XercesCName; converts double values as shown below (the values
depend on the system specific values of DBL_MAX and DBL_MIN):
</p>
<table>
@@ -133,7 +126,7 @@
<anchor name="usage"/>
<s2 title="Usage">
- <p>Here is an example how to turn on schema processing in DOMParser
+ <p>Below is an example that shows how to turn on schema processing in DOMParser
(default is off). Note that you must also turn on namespace support
(default is off) for schema processing.
</p>
@@ -143,10 +136,10 @@ parser.setDoNamespaces(true);
parser.setDoSchema(true);
parser.parse(xmlFile);
</source>
- <p>Usage in SAXParser is similar, please refer to the
- sample program 'samples/SAXCount/SAXCount.cpp' for further reference.
+ <p>Usage in SAXParser is similar, please refer to the SAXCount
+ sample program for further reference.
</p>
- <p>Here is an example how to turn on schema processing in SAX2XMLReader
+ <p>Below is an example that shows how to turn on schema processing in SAX2XMLReader
(default is on). Note that namespace must be on (default is on) as well.
</p>
<source>SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
@@ -154,17 +147,41 @@ parser->setFeature(XMLUni::fgSAX2CoreNameSpaces, true);
parser->setFeature(XMLUni::fgXercesSchema, true);
parser->parse(xmlFile);
</source>
- <p>Review the sample file, 'samples/data/personal-schema.xml' and
- 'samples/data/personal.xsd' for an example of an XML Schema grammar.
- </p>
</s2>
<anchor name="associate"/>
<s2 title="Associating Schema Grammar with instance document">
- <p>Schema grammars can be associated with instance documents in two ways.
+ <p>Schema grammars can be associated with instance documents in three ways.
</p>
- <s3 title="Specifying Schema Grammar through method calls:">
+ <s3 title="Specifying Schema Grammar through attributes in the instance document">
+ <p>If schema grammar was not specified externally through methods,
+ then each instance document that uses XML Schema grammars must specify the location of
+ the grammars it uses by using an xsi:schemaLocation attribute if they use
+ namespaces, and xsi:noNamespaceSchemaLocation attribute otherwise.
+ </p>
+ <p>Here is an example with no target namespace:
+ </p>
+<source><?xml version="1.0" encoding="UTF-8"?>
+<personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation='personal.xsd'>
+...
+</personnel>
+</source>
+ <p>Here is an example with a target namespace. Note that it is an error to specify a
+ different namespace in xsi:schemaLocation attribute than the target namespace
+ defined in the Schema.
+ </p>
+<source><?xml version="1.0" encoding="UTF-8"?>
+<personnel xmlns="http://my.com"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://my.com personal.xsd http://my2.com test2.xsd">
+...
+</personnel>
+</source>
+ </s3>
+
+ <s3 title="Specifying Schema Grammar through method calls">
<p>An application developer may associate schemas with instance documents through
methods <code>setExternalSchemaLocation</code> if they use namespaces, and
<code>setExternalNoNamespaceSchemaLocation</code> otherwise.
@@ -202,12 +219,14 @@ parser.parse("test.xml");
DOMParser parser;
parser.setDoNamespaces(true);
parser.setDoSchema(true);
-parser.setExternalSchemaLocation("http://my.com personal.xsd http://my2.com test2.xsd");
+parser.setExternalSchemaLocation(
+ "http://my.com personal.xsd http://my2.com test2.xsd");
parser.parse("test.xml");
// Instantiate the SAX2 XMLReader.
SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
-XMLCh* propertyValue = XMLString::transcode("http://my.com personal.xsd http://my2.com test2.xsd");
+XMLCh* propertyValue = XMLString::transcode(
+ "http://my.com personal.xsd http://my2.com test2.xsd");
ArrayJanitor<XMLCh> janValue(propertyValue);
parser->setProperty(
@@ -216,31 +235,14 @@ parser->setProperty(
parser.parse("test.xml");
</source>
</s3>
- <s3 title="Specifying Schema Grammar through attributes in the instance document:">
- <p>If schema grammar was not specified externally through methods,
- then each instance document that uses XML Schema grammars must specify the location of
- the grammars it uses by using an xsi:schemaLocation attribute if they use
- namespaces, and xsi:noNamespaceSchemaLocation attribute otherwise.
- </p>
- <p>Here is an example with no target namespace:
- </p>
-<source><?xml version="1.0" encoding="UTF-8"?>
-<personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation='personal.xsd'>
-...
-</personnel>
-</source>
- <p>Here is an example with a target namespace. Note that it is an error to specify a
- different namespace in xsi:schemaLocation attribute than the target namespace
- defined in the Schema.
- </p>
-<source><?xml version="1.0" encoding="UTF-8"?>
-<personnel xmlns="http://my.com"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://my.com personal.xsd http://my2.com test2.xsd">
-...
-</personnel>
-</source>
+
+ <s3 title="Pre-parsing and Caching Schema Grammar">
+ <p>An application developer may also pre-parse and
+ cache the grammar corresponding to the XML document
+ namespace as described in the
+ <jump href="program-others-&XercesC3Series;.html#GrammarCache">Pre-parsing
+ Grammar and Grammar Caching</jump> section of the
+ &XercesCName; Programming Guide.</p>
</s3>
</s2>
</s1>
diff --git a/doc/scmprint.xml b/doc/scmprint.xml
index 867751234..06926a4ec 100644
--- a/doc/scmprint.xml
+++ b/doc/scmprint.xml
@@ -41,7 +41,7 @@ Options:
</source>
<p>Here is some sample output from SCMPrint (as the output is verbose
it has been truncated)</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SCMPrint personal.xsd
********** Printing out information from Schema **********
diff --git a/doc/senumval.xml b/doc/senumval.xml
index caa8d06b5..a48c4bfee 100644
--- a/doc/senumval.xml
+++ b/doc/senumval.xml
@@ -21,7 +21,7 @@
<s1 title="Sample: SEnumVal">
<s2 title="SEnumVal">
- <p>SEnumVal shows how to enumerate the markup decls in a Schema Grammar.</p>
+ <p>SEnumVal shows how to enumerate the markup declarations in a Schema Grammar.</p>
<s3 title="Running SEnumVal">
<p>This program parses the specified XML file, then shows how to
@@ -35,7 +35,7 @@ contents of the Schema Grammar. Essentially, shows how one can
access the Schema information stored in internal data structures.
</source>
<p>Here is a sample output from SEnumVal</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
SEnumVal personal-schema.xml
Name: personnel
@@ -73,7 +73,7 @@ Facets:
Default Type: #DEFAULT
Value: false
Base Datatype: string
-Enumeration:
+Enumeration:
true
false
diff --git a/doc/stdinparse.xml b/doc/stdinparse.xml
index 5f13cb088..77770edb7 100644
--- a/doc/stdinparse.xml
+++ b/doc/stdinparse.xml
@@ -24,8 +24,8 @@
<p>StdInParse demonstrates streaming XML data from standard input.</p>
<s3 title="Running StdInParse">
- <p>The StdInParse sample parses an XML file from standard input and prints out a
- count of the number of
+ <p>The StdInParse sample parses an XML file from standard input and prints out
+ the number of
elements in the file. To run StdInParse, enter the following: </p>
<source>StdInParse < <XML file></source>
<p>The following parameters may be set from the command line </p>
@@ -52,7 +52,7 @@ Options:
<em>-v=auto</em> will validate if a DOCTYPE declaration or a schema declaration is present in the XML document</p>
<p>Make sure that you run StdInParse in the samples/data directory.</p>
<p>Here is a sample output from StdInParse:</p>
-<source>cd &XercesC3InstallDir;-linux/samples/data
+<source>cd &XercesC3InstallDir;/samples/data
StdInParse -v=always < personal.xml
stdin: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Running StdInParse with the validating parser gives a different result because
@@ -62,7 +62,7 @@ stdin: 10 ms (37 elems, 12 attrs, 0 spaces, 268 chars)</source>
<p>Note that the sum of spaces and characters in both versions is the same.</p>
<note>The time reported by the program may be different depending on your
- machine processor.</note>
+ processor speed.</note>
</s3>
</s2>
</s1>
diff --git a/doc/style/dtd/entities.ent b/doc/style/dtd/entities.ent
index a366e9039..375d43dff 100644
--- a/doc/style/dtd/entities.ent
+++ b/doc/style/dtd/entities.ent
@@ -5,13 +5,12 @@
<!ENTITY XercesCName "Xerces-C++"> <!-- productname -->
<!ENTITY XercesC3Series "3"> <!-- release series -->
<!ENTITY XercesC3Version "3.0.0"> <!-- 3-series version number -->
-<!ENTITY XercesC3InstallDir "xerces-c_3_0_0"> <!-- installdirname -->
-<!ENTITY XercesC3SrcInstallDir "xerces-c-src_3_0_0"> <!-- sourcedirectory -->
-<!ENTITY XercesC3ToolsInstallDir "xerces-c-tools_3_0_0"> <!-- sourcedirectory -->
+<!ENTITY XercesC3InstallDir "xerces-c-3.0.0"> <!-- installdirname -->
+<!ENTITY XercesC3SrcInstallDir "xerces-c-3.0.0"> <!-- sourcedirectory -->
+<!ENTITY XercesC3ToolsInstallDir "xerces-c-tools-3.0.0"> <!-- sourcedirectory -->
<!ENTITY XercesC3WindowsLib "xerces-c_3"> <!-- windowslibname -->
<!ENTITY XercesC3WindowsDLL "xerces-c_3_0"> <!-- windowsDLLname -->
-<!ENTITY XercesC3UnixSoName "30.0"> <!-- unixlibname -->
-<!ENTITY XercesC3UnixVersion "30"> <!-- unixlibname -->
+<!ENTITY XercesC3UnixSoVersion "3.0"> <!-- unixlibversion -->
<!ENTITY XercesC3UnixLib "libxerces-c"> <!-- unixlibname -->
<!ENTITY XercesC3Namespace "xercesc"> <!-- C++ namespace name -->
<!ENTITY XercesC3NSVersion "xercesc_3_0"> <!-- C++ namespace name with Version -->
diff --git a/doc/xerces-c_book.xml b/doc/xerces-c_book.xml
index 9451fe0b4..9d4007195 100644
--- a/doc/xerces-c_book.xml
+++ b/doc/xerces-c_book.xml
@@ -25,9 +25,6 @@
<document id="index" label="Readme" source="readme.xml"/>
<document id="install-&XercesC3Series;" label="Installation" source="install.xml"/>
<document id="build-&XercesC3Series;" label="Build Instructions" source="build.xml"/>
- <hidden id="build-winunix-&XercesC3Series;" source="build-winunix.xml"/>
- <hidden id="build-other-&XercesC3Series;" source="build-other.xml"/>
- <hidden id="build-misc-&XercesC3Series;" source="build-misc.xml"/>
<separator-space/>
@@ -54,6 +51,7 @@
<hidden id="senumval-&XercesC3Series;" source="senumval.xml"/>
<hidden id="psviwriter-&XercesC3Series;" source="psviwriter.xml"/>
<hidden id="scmprint-&XercesC3Series;" source="scmprint.xml"/>
+ <hidden id="xinclude-&XercesC3Series;" source="xinclude.xml"/>
<group id="faqs-&XercesC3Series;" label="FAQs">
<entry id="faq-distrib-&XercesC3Series;" source="faq-distrib.xml"/>
diff --git a/doc/xinclude.xml b/doc/xinclude.xml
index 87b14199a..54122d76f 100644
--- a/doc/xinclude.xml
+++ b/doc/xinclude.xml
@@ -21,9 +21,9 @@
<s1 title="Sample: XInclude">
<s2 title="XInclude">
- <p>XInclude uses the provided DOM API to parse an XML file,
- constructs the DOM tree, expands the xi:include elements
- and writes the resulting tree to a file.</p>
+ <p>The XInclude example uses the provided DOM API to parse an XML file
+ while expanding the xi:include elements. It then writes
+ the resulting DOM tree in the expanded form.</p>
<s3 title="Running XInclude">
--
GitLab