+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE readme SYSTEM "readme.dtd" [
-
-<!--
-<!ENTITY url.ocaml "http://caml.inria.fr/">
-<!ENTITY url.xml-spec "http://www.w3.org/TR/1998/REC-xml-19980210.html">
-<!ENTITY url.jclark-xmltdata "ftp://ftp.jclark.com/pub/xml/xmltest.zip">
-<!ENTITY url.gps-ocaml-download "http://people.darmstadt.netsurf.de/ocaml">
-<!ENTITY url.markup-download "&url.gps-ocaml-download;/markup-0.1.tar.gz">
-<!ENTITY person.gps '<a
- href="mailto:Gerd.Stolpmann@darmstadt.netsurf.de">Gerd Stolpmann</a>'>
--->
-
-<!ENTITY % common SYSTEM "common.xml">
-%common;
-
-<!-- Special HTML config: -->
-<!ENTITY % readme:html:up '<a href="../..">up</a>'>
-
-<!ENTITY % config SYSTEM "config.xml">
-%config;
-
-]>
-
-<readme title="README - PXP, the XML parser for O'Caml">
- <sect1>
- <title>Abstract</title>
- <p>
-<em>PXP</em> is a validating parser for XML-1.0 which has been written
-entirely in Objective Caml.
-</p>
-
- <p>PXP is the new name of the parser formerly known as "Markup".
-PXP means "Polymorphic XML parser" and emphasizes its most useful
-property: that the API is polymorphic and can be configured such that
-different objects are used to store different types of elements.</p>
- </sect1>
-
- <sect1>
- <title>Download</title>
- <p>
-You can download <em>PXP</em> as gzip'ed <a
-href="&url.pxp-download;">tarball</a>. The parser needs the <a
-href="&url.netstring-project;">Netstring</a> package (0.9.3). Note that PXP
-requires O'Caml 3.00.
-</p>
- </sect1>
-
- <sect1>
- <title>User's Manual</title>
- <p>
-The manual is included in the distribution both as Postscript document and
-bunch of HTML files. An online version can be found <a
- href="&url.pxp-manual;">here</a>.
-</p>
- </sect1>
-
- <sect1>
- <title>Author, Credits, Copying</title>
- <p>
-<em>PXP</em> has been written by &person.gps;; it contains contributions by
-Claudio Sacerdoti Coen. You may copy it as you like,
-you may use it even for commercial purposes as long as the license conditions
-are respected, see the file LICENSE coming with the distribution. It allows
-almost everything.
-</p>
-
- <p>Thanks also to Alain Frisch and Haruo Hosoya for discussions and bug
-reports.</p>
- </sect1>
-
- <sect1>
- <title>Description</title>
- <p>
-<em>PXP</em> is a validating XML parser for <a
-href="&url.ocaml;">O'Caml</a>. It strictly complies to the
-<a href="&url.xml-spec;">XML-1.0</a> standard.
-</p>
-
- <p>The parser is simple to call, usually only one statement (function
-call) is sufficient to parse an XML document and to represent it as object
-tree.</p>
-
- <p>
-Once the document is parsed, it can be accessed using a class interface.
-The interface allows arbitrary access including transformations. One of
-the features of the document representation is its polymorphic nature;
-it is simple to add custom methods to the document classes. Furthermore,
-the parser can be configured such that different XML elements are represented
-by objects created from different classes. This is a very powerful feature,
-because it simplifies the structure of programs processing XML documents.
-</p>
-
- <p>
-Note that the class interface does not comply to the DOM standard. It was not a
-development goal to realize a standard API (industrial developers can this much
-better than I); however, the API is powerful enough to be considered as
-equivalent with DOM. More important, the interface is compatible with the
-XML information model required by many XML-related standards.
-</p>
-
- <sect2>
- <title>Detailed feature list</title>
-
- <ul>
- <li><p>The XML instance is validated against the DTD; any violation of
-a validation constraint leads to the rejection of the instance. The validator
-has been carefully implemented, and conforms strictly to the standard. If
-needed, it is also possible to run the parser in a well-formedness mode.</p>
- </li>
- <li><p>If possible, the validator applies a deterministic finite
-automaton to validate the content models. This ensures that validation can
-always be performed in linear time. However, in the case that the content
-models are not deterministic, the parser uses a backtracking algorithm which
-can be much slower. - It is also possible to reject non-deterministic content
-models.</p>
- </li>
- <li><p>In particular, the validator also checks the complicated rules
-whether parentheses are properly nested with respect to entities, and whether
-the standalone declaration is satisfied. On demand, it is checked whether the
-IDREF attributes only refer to existing nodes.</p>
- </li>
- <li><p>Entity references are automatically resolved while the XML text
-is being scanned. It is not possible to recognize in the object tree where a
-referenced entity begins or ends; the object tree only represents the logical structure.</p>
- </li>
- <li><p>External entities are loaded using a configurable resolver
-infrastructure. It is possible to connect the parser with an arbitrary XML source.</p>
- </li>
- <li><p>The parser can read XML text encoded in a variety of character
-sets. Independent of this, it is possible to choose the encoding of the
-internal representation of the tree nodes; the parser automatically converts
-the input text to this encoding. Currently, the parser supports UTF-8 and
-ISO-8859-1 as internal encodings.</p>
- </li>
- <li><p>The interface of the parser has been designed such that it is
-best integrated into the language O'Caml. The first goal was simplicity of
-usage which is achieved by many convenience methods and functions, and by
-allowing the user to select which parts of the XML text are actually
-represented in the tree. For example, it is possible to store processing
-instructions as tree nodes, but the parser can also be configured such that
-these instructions are put into hashtables. The information model is compatible
-with the requirements of XML-related standards such as XPath.</p>
- </li>
- <li><p>In particular, the node tree can optionally contain or leave out
-processing instructions and comments. It is also possible to generate a "super
-root" object which is the parent of the root element. The attributes of
-elements are normally not stored as nodes, but it is possible to get them
-wrapped into nodes.</p>
- </li>
- <li><p>There is also an interface for DTDs; you can parse and access
-sequences of declarations. The declarations are fully represented as recursive
-O'Caml values.
-</p>
- </li>
- </ul>
- </sect2>
-
-
- <sect2>
- <title>Code examples</title>
- <p>
-This distribution contains several examples:</p>
- <ul>
- <li><p>
-<em>validate:</em> simply parses a
-document and prints all error messages
-</p></li>
-
- <li><p>
-<em>readme:</em> Defines a DTD for simple "README"-like documents, and offers
-conversion to HTML and text files<footnote>This particular document is an
-example of this DTD!</footnote>.
-</p></li>
-
- <li><p>
-<em>xmlforms:</em> This is already a
-sophisticated application that uses XML as style sheet language and data
-storage format. It shows how a Tk user interface can be configured by an
-XML style, and how data records can be stored using XML.
-</p></li>
- </ul>
- </sect2>
-
- <sect2>
- <title>Restrictions and missing features</title>
- <p>
-The following restrictions apply that are not violations of the standard:
-</p>
- <ul>
- <li><p>
-The attributes "xml:space", and "xml:lang" are not supported specially.
- (The application can do this.)</p></li>
-
- <li><p>
-The built-in support for SYSTEM and PUBLIC identifiers is limited to
- local file access. There is no support for catalogs. The parser offers
- a hook to add missing features.</p></li>
-
- <li><p>
-It is currently not possible to check for interoperatibility with SGML.
-</p></li>
- </ul>
-
-<p>The following features are also missing:</p>
- <ul>
- <li><p>There is no special support for namespaces. (Perhaps in the next release?)</p>
- </li>
- <li><p>There is no support for XPATH or XSLT.</p>
- </li>
- </ul>
-<p>However, I hope that these features will be implemented soon, either by
-myself or by contributors (who are invited to do so).</p>
- </sect2>
-
- <sect2>
- <title>Recent Changes</title>
- <ul>
- <li>
- <p>Changed in 1.0:</p>
- <p>Support for document order.</p>
- </li>
- <li>
- <p>Changed in 0.99.8:</p>
- <p>Several fixes of bugs reported by Haruo Hosoya and Alain
-Frisch.</p>
- <p>The class type "node" has been extended: you can go directly to
-the next and previous nodes in the list; you can refer to nodes by
-position.</p>
- <p>There are now some iterators for nodes: find, find_all,
-find_element, find_all_elements, map_tree, iter_tree.</p>
- <p>Experimental support for viewing attributes as nodes; I hope that
-helps Alain writing his XPath evaluator.</p>
- <p>The user's manual has been revised and is almost up to date.</p>
- </li>
- <li>
- <p>Changed in 0.99.7:</p>
- <p>There are now additional node types T_super_root, T_pinstr and
-T_comment, and the parser is able to create the corresponding nodes.</p>
- <p>The functions for character set conversion have been moved to
-the Netstring package; they are not specific for XML.</p>
- </li>
- <li>
- <p>Changed in 0.99.6:</p>
- <p>Implemented a check on deterministic content models. Added
-an alternate validator basing on a DFA. - This means that now all mandatory
-features for an XML-1.0 parser are implemented! The parser is now substantially
-complete.</p>
- </li>
- <li>
- <p>Changed in 0.99.5:</p>
- <p>The handling of ID and IDREF attributes has changed. The
-index of nodes containing an ID attribute is now separated from the document.
-Optionally the parser now checks whether the IDREF attributes refer to
-existing elements.</p>
- <p>The element nodes can optionally store the location in the
-source XML code.</p>
- <p>The method 'write' writes the XML tree in every supported
-encoding. (Successor of 'write_compact_as_latin1'.)</p>
- <p>Several smaller changes and fixes.</p>
- </li>
- <li>
- <p>Changed in 0.99.4:</p>
- <p>The module Pxp_reader has been modernized. The resolver classes
-are simpler to use. There is now support for URLs.</p>
- <p>The interface of Pxp_yacc has been improved: The type 'source'
-is now simpler. The type 'domspec' has gone; the new 'spec' is opaque and
-performs better. There are some new parsing modes.</p>
- <p>Many smaller changes.</p>
- </li>
- <li>
- <p>Changed in 0.99.3:</p>
- <p>The markup_* modules have been renamed to pxp_*. There is a new
-compatibility API that tries to be compatible with markup-0.2.10.</p>
- <p>The type "encoding" is now a polymorphic variant.</p>
- </li>
- <li>
- <p>Changed in 0.99.2:</p>
- <p>Added checks for the constraints about the standalone
-declaration.</p>
- <p>Added regression tests about attribute normalization,
-attribute checks, standalone checks.</p>
- <p>Fixed some minor errors of the attribute normalization
-function.</p>
- <p>The bytecode/native archives are now separated in
-a general part, in a ISO-8859-1-relevant part, and a UTF-8-relevant
-part. The parser can again be compiled with ocamlopt.</p>
- </li>
- <li>
- <p>Changed in 0.99.1:</p>
- <p>In general, this release is an early pre-release of the
-next stable version 1.00. I do not recommend to use it for serious
-work; it is still very experimental!</p>
- <p>The core of the parser has been rewritten using a self-written
-parser generator.</p>
- <p>The lexer has been restructured, and can now handle UTF-8
-encoded files.</p>
- <p>Numerous other changes.</p>
- </li>
-
-<!--
- <li>
- <p>Changed in 0.2.10:</p>
- <p>Bugfix: in the "allow_undeclared_attributes" feature.</p>
- <p>Bugfix: in the methods write_compact_as_latin1.</p>
- <p>Improvement: The code produced by the codewriter module can be
-faster compiled and with less memory usage.</p>
- </li>
-
- <li>
- <p>Changed in 0.2.9:</p>
- <p>New: The module Markup_codewriter generates for a given XML
-tree O'Caml code that creates the same XML tree. This is useful for
-applications which use large, constant XML trees.</p>
- <p>New: Documents and DTDs have a method write_compact_as_latin1
-that writes an XML tree to a buffer or to a channel. (But it is not a pretty
-printer...)</p>
- <p>Enhancement: If a DTD contains the processing instruction
-<code>
-<?xml:allow_undeclared_attributes x?></code>
-where "x" is the name of an already declared element it is allowed that
-instances of this element type have attributes that have not been declared.
-</p>
- <p>New function Markup_types.string_of_exn that converts an
-exception from Markup into a readable string.</p>
- <p>Change: The module Markup_reader contains all resolvers.
-The resolver API is now stable.</p>
- <p>New parser modes processing_instructions_inline and
-virtual_root that help locating processing instructions exactly (if needed).
-</p>
- <p>Many bugs regarding CRLF handling have been fixed.</p>
- <p>The distributed tarball contains now the regression test suite.
-</p>
- <p>The manual has been extended (but it is still incomplete and
-still behind the code).</p>
- </li>
- <li>
- <p>Changed in 0.2.8:</p>
- <p>A bit more documentation (Markup_yacc).</p>
- <p>Bugfix: In previous versions, the second trial to refer to
-an entity caused a Bad_character_stream exception. The reason was improper
-re-initialization of the resolver object.</p>
- </li>
- <li>
- <p>Changed in 0.2.7:</p>
- <p>Added some methods in Markup_document.</p>
- <p>Bugfix: in method orphaned_clone</p>
- </li>
- <li>
- <p>Changed in 0.2.6:</p>
- <p>Enhancement: The config parameter has a new component
-"errors_with_line_numbers". If "true", error exceptions come with line numbers
-(the default; and the only option in the previous versions); if "false"
-the line numbers are left out (only character positions). The parser is 10 to
-20 percent faster if the lines are not tracked.</p>
- <p>Enhancement: If a DTD contains the processing instruction
-<code>
-<?xml:allow_undeclared_elements_and_notations?></code>
-it is allowed that
-elements and notations are undeclared. However, the elements for which
-declarations exist are still validated. The main effect is that the
-keyword ALL in element declarations means that also undeclared elements
-are permitted at this location.</p>
- <p>Bugfix in method "set_nodes" of class Markup_document.node_impl.
-</p>
- </li>
- <li>
- <p>Changed in 0.2.5:</p>
- <p>If the XML source is a string (i.e. Latin1 some_string is passed
-to the parser functions as source), resolving did not work properly in
-previous releases. This is now fixed.
-</p>
- </li>
- <li>
- <p>Changed in 0.2.4:</p>
- <p>A problem with some kind of DTD that does not specify the name
-of the root element was fixed. As a result, the "xmlforms" application works
-again. Again thanks to Haruo.</p>
- <p>Due to the XML specs it is forbidden that parameter entities are
-referenced within the internal subset if the referenced text is not a
-complete declaration itself. This is checked, but the check was too hard;
-even in external entities referenced from the internal subset this rule
-was enforced. This has been corrected; in external entities it is now possible
-to use parameter entities in an unrestricted way.
-</p>
- </li>
- <li>
- <p>Changed in 0.2.3:</p>
- <p>A fix for a problem when installing Markup on Solaris.
-Haruo detected the problem.</p>
- </li>
- <li>
- <p>Changed in 0.2.2:</p>
- <p>A single bugfix: The parser did not reject documents where the
-root element was not the element declared as root element. Again thanks
-to Claudio.</p>
- </li>
- <li>
- <p>Changed in 0.2.1:</p>
- <p>A single bugfix which reduces the number of warnings. Thanks
-to Claudio for detecting the bug.</p>
- </li>
- <li>
- <p>Changed in 0.2:</p>
- <p>
-Much more constraints are checked in the 0.2 release than in 0.1. Especially
-that entities are properly nested is now guaranteed; parsed entities now always
-match the corresponding production of the grammar.</p>
- <p>
-Many weak checks have been turned into strong checks. For example, it is now
-detected if the "version", "encoding", and "standalone" attributes of an XML
-declaration are ordered in the right way.
-</p>
- <p>
-The error messages have been improved.
-</p>
- </li>
--->
- </ul>
- </sect2>
- </sect1>
-</readme>
-
projects / helm.git / blobdiff