There are the following main functions invoking the parser (in Pxp_yacc):
parse_document_entity: You want to parse a complete and closed document consisting of a DTD and the document body; the body is validated against the DTD. This mode is interesting if you have a file
<!DOCTYPE root ... [ ... ] > <root> ... </root>and you can accept any DTD that is included in the file (e.g. because the file is under your control).
parse_wfdocument_entity: You want to parse a complete and closed document consisting of a DTD and the document body; but the body is not validated, only checked for well-formedness. This mode is preferred if validation costs too much time or if the DTD is missing.
parse_dtd_entity: You want only to parse an entity (file) containing the external subset of a DTD. Sometimes it is interesting to read such a DTD, for example to compare it with the DTD included in a document, or to apply the next mode:
parse_content_entity: You want only to parse an entity (file) containing a fragment of a document body; this fragment is validated against the DTD you pass to the function. Especially, the fragment must not have a <!DOCTYPE> clause, and must directly begin with an element. The element is validated against the DTD. This mode is interesting if you want to check documents against a fixed, immutable DTD.
parse_wfcontent_entity: This function also parses a single element without DTD, but does not validate it.
extract_dtd_from_document_entity: This function extracts the DTD from a closed document consisting of a DTD and a document body. Both the internal and the external subsets are extracted.
In many cases, parse_document_entity is the preferred mode to parse a document in a validating way, and parse_wfdocument_entity is the mode of choice to parse a file while only checking for well-formedness.
There are a number of variations of these modes. One important application of a parser is to check documents of an untrusted source against a fixed DTD. One solution is to not allow the <!DOCTYPE> clause in these documents, and treat the document like a fragment (using mode parse_content_entity). This is very simple, but inflexible; users of such a system cannot even define additional entities to abbreviate frequent phrases of their text.
It may be necessary to have a more intelligent checker. For example, it is also possible to parse the document to check fully, i.e. with DTD, and to compare this DTD with the prescribed one. In order to fully parse the document, mode parse_document_entity is applied, and to get the DTD to compare with mode parse_dtd_entity can be used.
There is another very important configurable aspect of the parser: the so-called resolver. The task of the resolver is to locate the contents of an (external) entity for a given entity name, and to make the contents accessible as a character stream. (Furthermore, it also normalizes the character set; but this is a detail we can ignore here.) Consider you have a file called "main.xml" containing
<!ENTITY % sub SYSTEM "sub/sub.xml"> %sub;and a file stored in the subdirectory "sub" with name "sub.xml" containing
<!ENTITY % subsub SYSTEM "subsub/subsub.xml"> %subsub;and a file stored in the subdirectory "subsub" of "sub" with name "subsub.xml" (the contents of this file do not matter). Here, the resolver must track that the second entity subsub is located in the directory "sub/subsub", i.e. the difficulty is to interpret the system (file) names of entities relative to the entities containing them, even if the entities are deeply nested.
There is not a fixed resolver already doing everything right - resolving entity names is a task that highly depends on the environment. The XML specification only demands that SYSTEM entities are interpreted like URLs (which is not very precise, as there are lots of URL schemes in use), hoping that this helps overcoming the local peculiarities of the environment; the idea is that if you do not know your environment you can refer to other entities by denoting URLs for them. I think that this interpretation of SYSTEM names may have some applications in the internet, but it is not the first choice in general. Because of this, the resolver is a separate module of the parser that can be exchanged by another one if necessary; more precisely, the parser already defines several resolvers.
The following resolvers do already exist:
Resolvers reading from arbitrary input channels. These can be configured such that a certain ID is associated with the channel; in this case inner references to external entities can be resolved. There is also a special resolver that interprets SYSTEM IDs as URLs; this resolver can process relative SYSTEM names and determine the corresponding absolute URL.
A resolver that reads always from a given O'Caml string. This resolver is not able to resolve further names unless the string is not associated with any name, i.e. if the document contained in the string refers to an external entity, this reference cannot be followed in this case.
A resolver for file names. The SYSTEM name is interpreted as file URL with the slash "/" as separator for directories. - This resolver is derived from the generic URL resolver.
Note that the existing resolvers only interpret SYSTEM names, not PUBLIC names. If it helps you, it is possible to define resolvers for PUBLIC names, too; for example, such a resolver could look up the public name in a hash table, and map it to a system name which is passed over to the existing resolver for system names. It is relatively simple to provide such a resolver.