From d09ab089457ae3c20cc98f9afa03379c6ebf9598 Mon Sep 17 00:00:00 2001 From: Mike Hommey Date: Thu, 25 Mar 2004 06:59:32 +0000 Subject: [svn-inject] Installing original source version --- doc/FAQ.html | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 doc/FAQ.html (limited to 'doc/FAQ.html') diff --git a/doc/FAQ.html b/doc/FAQ.html new file mode 100644 index 0000000..472863f --- /dev/null +++ b/doc/FAQ.html @@ -0,0 +1,244 @@ + + +FAQ

The XML C parser and toolkit of Gnome

FAQ

Main Menu

Related links

Table of Contents:

License(s)

Licensing Terms for libxml +
libxml2 is released under the MIT + License; see the file Copyright in the distribution for the precise + wording
+
Can I embed libxml2 in a proprietary application ? +
Yes. The MIT License allows you to keep proprietary the changes you + made to libxml, but it would be graceful to send-back bug fixes and + improvements as patches for possible incorporation in the main + development tree.
+

Installation

Do Not Use + libxml1, use libxml2
Where can I get libxml ? +
The original distribution comes from rpmfind.net or gnome.org
+
Most Linux and BSD distributions include libxml, this is probably the + safer way for end-users to use libxml.
+
David Doolin provides precompiled Windows versions at http://www.ce.berkeley.edu/~doolin/code/libxmlwin32/
+
I see libxml and libxml2 releases, which one should I install ? +
- If you are not constrained by backward compatibility issues with + existing applications, install libxml2 only
- If you are not doing development, you can safely install both. + Usually the packages libxml and libxml2 are + compatible (this is not the case for development packages).
- If you are a developer and your system provides separate packaging + for shared libraries and the development components, it is possible + to install libxml and libxml2, and also libxml-devel + and libxml2-devel + too for libxml2 >= 2.3.0
- If you are developing a new application, please develop against + libxml2(-devel)
I can't install the libxml package, it conflicts with libxml0 +
You probably have an old libxml0 package used to provide the shared + library for libxml.so.0, you can probably safely remove it. The libxml + packages provided on rpmfind.net provide + libxml.so.0
+
I can't install the libxml(2) RPM package due to failed + dependencies +
The most generic solution is to re-fetch the latest src.rpm , and + rebuild it locally with
+
rpm --rebuild libxml(2)-xxx.src.rpm.
+
If everything goes well it will generate two binary rpm packages (one + providing the shared libs and xmllint, and the other one, the -devel + package, providing includes, static libraries and scripts needed to build + applications with libxml(2)) that you can install locally.
+

Compilation

What is the process to compile libxml2 ? +
As most UNIX libraries libxml2 follows the "standard":
+
gunzip -c xxx.tar.gz | tar xvf -
+
cd libxml-xxxx
+
./configure --help
+
to see the options, then the compilation/installation proper
+
./configure [possible options]
+
make
+
make install
+
At that point you may have to rerun ldconfig or a similar utility to + update your list of installed shared libs.
+
What other libraries are needed to compile/install libxml2 ? +
Libxml2 does not require any other library, the normal C ANSI API + should be sufficient (please report any violation to this rule you may + find).
+
However if found at configuration time libxml2 will detect and use the + following libs:
+
- libz : a + highly portable and available widely compression library.
- iconv: a powerful character encoding conversion library. It is + included by default in recent glibc libraries, so it doesn't need to + be installed specifically on Linux. It now seems a part + of the official UNIX specification. Here is one implementation of the + library which source can be found here.
Make check fails on some platforms +
Sometimes the regression tests' results don't completely match the + value produced by the parser, and the makefile uses diff to print the + delta. On some platforms the diff return breaks the compilation process; + if the diff is small this is probably not a serious problem.
+
Sometimes (especially on Solaris) make checks fail due to limitations + in make. Try using GNU-make instead.
+
I use the CVS version and there is no configure script +
The configure script (and other Makefiles) are generated. Use the + autogen.sh script to regenerate the configure script and Makefiles, + like:
+
./autogen.sh --prefix=/usr --disable-shared
+
I have troubles when running make tests with gcc-3.0 +
It seems the initial release of gcc-3.0 has a problem with the + optimizer which miscompiles the URI module. Please use another + compiler.
+

Developer corner

Troubles compiling or linking programs using libxml2 +
Usually the problem comes from the fact that the compiler doesn't get + the right compilation or linking flags. There is a small shell script + xml2-config which is installed as part of libxml2 usual + install process which provides those flags. Use
+
xml2-config --cflags
+
to get the compilation flags and
+
xml2-config --libs
+
to get the linker flags. Usually this is done directly from the + Makefile as:
+
CFLAGS=`xml2-config --cflags`
+
LIBS=`xml2-config --libs`
+
xmlDocDump() generates output on one line. +
Libxml2 will not invent spaces in the content of a + document since all spaces in the content of a document are + significant. If you build a tree from the API and want + indentation:
+
1. the correct way is to generate those yourself too.
2. the dangerous way is to ask libxml2 to add those blanks to your + content modifying the content of your document in the + process. The result may not be what you expect. There is + NO way to guarantee that such a modification won't + affect other parts of the content of your document. See xmlKeepBlanksDefault + () and xmlSaveFormatFile + ()
Extra nodes in the document: +
For a XML file as below:
+
```
<?xml version="1.0"?>
+<PLAN xmlns="http://www.argus.ca/autotest/1.0/">
+<NODE CommFlag="0"/>
+<NODE CommFlag="1"/>
+</PLAN>
```
+
after parsing it with the function + pxmlDoc=xmlParseFile(...);
+
I want to the get the content of the first node (node with the + CommFlag="0")
+
so I did it as following;
+
```
xmlNodePtr pnode;
+pnode=pxmlDoc->children->children;
```
+
but it does not work. If I change it to
+
```
pnode=pxmlDoc->children->children->next;
```
+
then it works. Can someone explain it to me.
+
+
In XML all characters in the content of the document are significant + including blanks and formatting line breaks.
+
The extra nodes you are wondering about are just that, text nodes with + the formatting spaces which are part of the document but that people tend + to forget. There is a function xmlKeepBlanksDefault + () to remove those at parse time, but that's an heuristic, and its + use should be limited to cases where you are certain there is no + mixed-content in the document.
+
I get compilation errors of existing code like when accessing + root or child fields of nodes. +
You are compiling code developed for libxml version 1 and using a + libxml2 development environment. Either switch back to libxml v1 devel or + even better fix the code to compile with libxml2 (or both) by following the instructions.
+
I get compilation errors about non existing + xmlRootNode or xmlChildrenNode + fields. +
The source code you are using has been upgraded to be able to compile with both libxml + and libxml2, but you need to install a more recent version: + libxml(-devel) >= 1.8.8 or libxml2(-devel) >= 2.1.0
+
XPath implementation looks seriously broken +
XPath implementation prior to 2.3.0 was really incomplete. Upgrade to + a recent version, there are no known bugs in the current version.
+
The example provided in the web page does not compile. +
It's hard to maintain the documentation in sync with the code + <grin/> ...
+
Check the previous points 1/ and 2/ raised before, and please send + patches.
+
Where can I get more examples and information than provided on the + web page? +
Ideally a libxml2 book would be nice. I have no such plan ... But you + can:
+
- check more deeply the existing + generated doc
- have a look at the set of + examples.
- look for examples of use for libxml2 function using the Gnome code. + For example the following will query the full Gnome CVS base for the + use of the xmlAddChild() function: +
  http://cvs.gnome.org/lxr/search?string=xmlAddChild
  +
  This may be slow, a large hardware donation to the gnome project + could cure this :-)
  +
- Browse + the libxml2 source , I try to write code as clean and documented + as possible, so looking at it may be helpful. In particular the code + of xmllint.c and of the various testXXX.c test programs should + provide good examples of how to do things with the library.
What about C++ ? +
libxml2 is written in pure C in order to allow easy reuse on a number + of platforms, including embedded systems. I don't intend to convert to + C++.
+
There is however a C++ wrapper which may fulfill your needs:
+
- by Ari Johnson <ari@btigate.com>: +
  Website: http://libxmlplusplus.sourceforge.net/
  +
  Download: http://sourceforge.net/project/showfiles.php?group_id=12999
  +

How to validate a document a posteriori ? +

It is possible to validate documents which had not been validated at + initial parsing time or documents which have been built from scratch + using the API. Use the xmlValidateDtd() + function. It is also possible to simply add a DTD to an existing + document:

xmlDocPtr doc; /* your existing document */
+xmlDtdPtr dtd = xmlParseDTD(NULL, filename_of_dtd); /* parse the DTD */
+
+        dtd->name = xmlStrDup((xmlChar*)"root_name"); /* use the given root */
+
+        doc->intSubset = dtd;
+        if (doc->children == NULL) xmlAddChild((xmlNodePtr)doc, (xmlNodePtr)dtd);
+        else xmlAddPrevSibling(doc->children, (xmlNodePtr)dtd);
+

So what is this funky "xmlChar" used all the time? +
It is a null terminated sequence of utf-8 characters. And only utf-8! + You need to convert strings encoded in different ways to utf-8 before + passing them to the API. This can be accomplished with the iconv library + for instance.
+
etc ...

Daniel Veillard

-- cgit v1.2.3