1 files changed, 261 insertions, 0 deletions
diff --git a/lib/querypath/src/documentation.php b/lib/querypath/src/documentation.php
new file mode 100644
index 0000000..3649a5b
--- /dev/null
+++ b/lib/querypath/src/documentation.php
@@ -0,0 +1,261 @@
+<?php
+/** @mainpage QueryPath: Find Your Way
+ * @image html querypath-200x333.png
+ * QueryPath is a PHP library for working with XML and HTML. It is a PHP implementation of jQuery's
+ * traversal and modification libraries.
+ *
+ * @section getting_started Getting Started
+ *
+ * To being using QueryPath, you will probably want to take a look at these three pieces of 
+ * documentation:
+ *  - qp(): The main QueryPath function (like jQuery's $ function.)
+ *  - htmlqp(): A specialized version of qp() for dealing with poorly formatted HTML.
+ *  - QueryPath: The QueryPath class, which has all of the main functions.
+ *
+ * One substantial difference from jQuery is that QueryPath does not return a new object for 
+ * each call (for performance reasons). Instead, the same object is mutated from call to call.
+ * A chain, then, typically performs all methods on the same object.
+ * When you need multiple objects, QueryPath has a {@link QueryPath::branch()} function that 
+ * will return a cloned QueryPath object.
+ *
+ * QueryPath also has numerous functions that jQuery does not. Some (like QueryPath::top() and 
+ * QueryPath::dataURL()) are extensions we find useful.
+ * Most, however, are to either emphasize PHP features (QueryPath::filterPreg()) or adapt to 
+ * server-side needs (QueryPathEntities::replaceAllEntities()).
+ *
+ * @subsection basic_example A Few Basic Examples
+ *
+ * Here is a basic example of QueryPath usage:
+ *
+ * @code
+ * require 'QueryPath/QueryPath.php';
+ * 
+ * qp('<?xml version="1.0"?><root><foo/></root>', 'foo')->append('<bar>baz</bar>')->writeXML();
+ * @endcode
+ *
+ * The above will create a new document from the XML string, find the <code>foo</code> element, and then 
+ * append the <code>bar</code> element (complete with its text). Finally, the call to QueryPath::writeXML() will
+ * print the entire finished XML document to standard out (usually the web browser).
+ *
+ * Here's an example using htmlqp():
+ *
+ * @code
+ * require 'QueryPath/QueryPath.php';
+ * 
+ * // URL to fetch:
+ * $url = 'http://technosophos.com';
+ *
+ * print htmlqp($url, 'title')->text();
+ * @endcode
+ *
+ * The above will fetch the HTML from the given URL and then find the <code>title</code> tag. It will extract
+ * the text (QueryPath::text()) from the title and print it.
+ *
+ * For more examples, check out the #Examples namespace (start with {@link examples/html.php}). Also, read about the 
+ * qp() and htmlqp() functions.
+ *
+ * @subsection online_sources Online Sources
+ *
+ *   - The official QueryPath site http://querypath.org
+ *   - The latest API docs http://api.querypath.org
+ *   - IBM DeveloperWorks Intro to QueryPath http://www.ibm.com/developerworks/web/library/os-php-querypath/index.html 
+ *   - QueryPath articles at TechnoSophos.Com http://technosophos.com/qp/articles
+ *   - The QueryPath GitHub repository http://github.com/technosophos/querypath
+ *
+ * If you find a good online resource, please submit it as an issue in GitHub, and we will 
+ * most likely add it here.
+ *
+ * @subsection more_examples A Larger Example
+ *
+ * @include examples/html.php
+ * 
+ * @page extensions Using and Writing Extensions
+ *
+ * Using an extension is as easy as including it in your code:
+ * 
+ * @code
+ * <?php
+ * require 'QueryPath/QueryPath.php';
+ * require 'QueryPath/Extension/QPXML.php';
+ *
+ * // Now I have the QPXML methods available:
+ * qp(QueryPath::HTML_STUB)->comment('This is an HTML comment.');
+ * ?>
+ * @endcode
+ *
+ * Like jQuery, QueryPath provides a simple mechanism for writing extensions.
+ *
+ * Check out QPXSL and QPXML for a few easy-to-read extensions. QPDB provides an example of
+ * a more complex extension.
+ *
+ * QueryPathExtension is the master interface for all extensions.
+ *
+ */
+ 
+
+/** @page CSSReference CSS Selector Reference
+ * QueryPath provides two query 'languages' that you can use to search through XML and HTML 
+ * documents. The main query language is an implementation of the CSS3 Selectors specification. This
+ * is the query language that jQuery and CSS use -- and more recently, FireFox itself supports it
+ * via its JavaScript API. CSS3 should be familiar to developers and designers who have worked with
+ * HTML and stylesheets.
+ *
+ * QueryPath also allows XPath selectors, which can be executed using QueryPath::xpath(). While 
+ * fewer functions take XPath expressions, it is noless a powerful tool for querying DOM objects.
+ *
+ * @code
+ * <?php
+ * qp($xml)->xpath('//foo');
+ * ?>
+ * @endcode
+ * 
+ * QueryPath provides a full CSS3 selector implementation, including all of the specified operators,
+ * robost not() and has() support, pseudo-class/elements, and XML namespace support.
+ *
+ * Selectors can be passed into a number of QueryPath functions including qp(), htmlqp(), 
+ * QueryPath::find(), QueryPath::top(), QueryPath::children() and others.
+ * @code
+ * <?php
+ * $qp = qp($html, 'body'); // Find the body
+ * $another_qp = $qp->branch('p'); // Create another QP object that searches BODY for P tags.
+ * $qp->find('strong>a'); // Find all of the A elements directly inside of STRONG elements.
+ * $qp->top('head'); // Start over at the top of the document, and find the HEAD tag.
+ * ?>
+ * @endcode
+ *
+ * In all of the examples above, CSS selectors are used to locate specific things inside of the 
+ * document.
+ *
+ * @section selector_examples Example Selectors
+ * Example selectors:
+ * - <code>p</code>: Select all P elements in a document.
+ * - <code>strong a</code>: Select any A elements that are inside (children or descendants of) a STRONG 
+ *    element.
+ * - <code>strong>a</code>: Select only A elements that are directly beneath STRONG elements.
+ * - <code>:root>head</code> select HEAD elements that are directly beneath the document root.
+ * - <code>h1, h2</code>: Select all H1's and H2's.
+ * - <code>a:link</code>: Select all A tags that have hrefs
+ * - <code>div.content</code>: Select all DIV elements that have the class=content set.
+ * - <code>#my-id</code>: Select the element that has id=my-id.
+ * - <code>p:contains(Hello World)</code>: Select any P elements that have the text Hello World.
+ * - <code>p:not(.nav)</code>: Select any elements in P that do not have the nav class.
+ *
+ * @section pseudo_reference Pseudo-class and pseudo-element selectors
+ * QueryPath provides an implementation of the CSS3 spec, including the CSS3 pseudo-classes and 
+ * pseudo-elements defined in the spec. Some of the CSS3 pseudo-classes require a user agent, and
+ * so cannot be adequately captured on the server side, but all others have been implemented.
+ *
+ * Additionally, jQuery has added its own pseudo-classes, and jQuery users have come to expect those
+ * to work. So for the sake of convenience, we have implemented those as well. These include the 
+ * form pseudo-classes, along with several others.
+ *
+ * Finally, QueryPath has added a couple of useful pseudo-classes, namely :x-root and 
+ * :contains-exactly.
+ *
+ * @subsection pseudoelement_ref Pseudo-Elements
+ *
+ * Pseudo-elements are new in CSS3, and are syntactically similar to pseudo-classes. To use a
+ * pseudo-element in a selector, use the double-colon syntax: <code>::begins</code>. The following pseudo-
+ * elements are defined in QueryPath:
+ *
+ * - first-line: Selects the first line -- everything up to the first LF character (\ n).
+ * - first-letter: Slects the first letter of the element.
+ *
+ * These throw exceptions because they cannot be implemented without a user agent:
+ * - before
+ * - after
+ * - selection
+ *
+ * Pseudo-elements should be used with care, as they act like elements, but are not.
+ *
+ * @code
+ * <?php
+ * $textNode = qp($xml, 'p::first-letter')->get();
+ * ?>
+ * @endcode
+ *
+ * @subsection pseudoclass_reference Pseudo-Classes
+ *
+ * Pseudo-classes are more familiar to CSS and jQuery users. They use a single-colon syntax, and
+ * are used to narrow the set of selected elements.
+ *
+ * The following pseudo-classes are supported:
+ * - link: Matches anything with the href attribute.
+ * - root: The root element of the document
+ * - x-root: The root element that was passed into QueryPath's constructor
+ * - x-reset: Same as above.
+ * - even: All even elements in a set. First element is odd.
+ * - odd: Odd elements in a set. First element is odd.
+ * - nth-child: Every nth child in a set.
+ * - nth-last-child: Every nth child in a set, counting from the end.
+ * - nth-of-type: Every nth tag in a set.
+ * - nth-last-of-type: Every nth tag in a set, counting from the end.
+ * - first-child: The first child in a set.
+ * - last-child: The last child in a set.
+ * - first-of-type: The first child of the specified tag in a set.
+ * - last-of-type: The last child of the specified tag in a set.
+ * - only-child: Matches only if this is the only child in a set.
+ * - only-of-type: Matches only if it is the only child of the given tag in a set.
+ * - empty: Selects only empty elements.
+ * - not: The negation operator, takes a CSS3 selector, e.g. <code>:not(strong>a)</code>.
+ * - lt: Items in a set whose index is less than the given integer, e.g. <code>lt(3)</code>
+ * - gt: Items in a set whose index is greater than the given integer, e.g. <code>gt(3)</code>
+ * - nth: The nth item in a set, e.g. <code>nth(3)</code>
+ * - eq: The nth item in a set, e.g. <code>eq(3)</code>
+ * - first: The first item in a set.
+ * - last: The last item in a set.
+ * - parent: Matches if the item is a parent of child elements.
+ * - enabled: Matches (form) items that are enabled
+ * - disabled: Matches form items that are disabled
+ * - checked: Matches form items that are checked
+ * - text: Matches form items that are text fields
+ * - radio: Matches form items that are radio fields
+ * - checkbox: Matches form items that are checkboxes.
+ * - file: Matches form items that are file upload widgets.
+ * - password: Mathces form items that are password entry boxes.
+ * - submit: Matches submit buttons
+ * - image: Matches image buttons
+ * - reset: Matches reset buttons
+ * - button: Matches buttons
+ * - header: Matches header fields (h1-h6)
+ * - has: Matches any items that have children that match the given selector, e.g. <code>:has(strong>a)</code>
+ * - contains: Contains *text* that matches. This is a substring match.
+ * - contains-exactly: Contains *exactly* the given text. This is NOT a substring match.
+ * 
+ * These generate errors because they are not implemented:
+ * - indeterminate
+ * - lang
+ *
+ * These are quietly ignored because they require a user agent to be meaningful.
+ * - visited
+ * - hover
+ * - active
+ * - focus
+ * - animated
+ * - visible
+ * - hidden
+ * - target
+ *
+ * Examples:
+ * @code
+ * <?php
+ * qp($html, 'form input:text'); // Get all text input elements in a form.
+ * ?>
+ * @endcode
+ * @section xml_namespaces XML Namespaces
+ * QueryPath also supports the CSS3 namespace selection syntax. <b>This is syntactically different
+ * than the XML namespace tag format</b>. To select a tag whose namespaced name is foo:bar, the 
+ * CSS element selector would be <code>foo|bar</code> (note the vertical bar instead of a colon). While 
+ * QueryPath does its best to resolve namespaces to short names, there is a possibility that a 
+ * malformed namespace will prevent specific namespace queries.
+ *
+ * You can also query across namespaces with <code>*|tagname</code>.
+ *
+ * @code
+ * <?php
+ * qp($xml, 'atom|entry'); // Find all <atom:entry> elements.
+ * qp($xml, 'atom|entry > xmedia|video'); // Find all <xmedia:video> elements directly inside <atom:entry> elements.
+ * qp($xml, '*|entry'); // Find any namespaced tag that has `entry` as the tag name.
+ * ?>
+ * @endcode
+ */