Re: Some suggestions for documentation

[Nigel S. <nig...@us...>]

> 1. It's useful that the intro defines things like absolutexpath and
> xpathquery, but the function list doesn't use these consistently, using
other
> terms like xpath expression or xpath string. I feel this is likely to
confuse
> newbies.

Well spotted.   Hopefully I've caught all of these now.  If not please send
the section reference.

> 2. an example of evaluate/match in the sample code, and when it would be
> used. Am I right in thinking this is the only function that uses an
> xpathquery, i.e. that works with a node set and not an absolute address?
This
> was something I misunderstood when I first used the class, as I thought
you
> always had to do an evaluate before using any of the other functions. If
you
> only want one node, don't use evaluate, as it just slows things down.

Actually as of V3, if the parameter is an $xPathQuery, then you can pass in
an xpath expression, so you don't have to call evaluate() all the time!  So
all these functions can now be called using things like /A/B/C rather than
/A[1]/B[2]/C[2].  This was such a common problem that it really had to be
addressed.

function evaluate($xPathQuery, $baseXPath='') {
function nodeName($xPathQuery) {
function removeChild($xPathQuery, $autoReindex=TRUE) {
function replaceChildByData($xPathQuery, $data, $autoReindex=TRUE) {
function &replaceChild($xPathQuery, $node, $autoReindex=TRUE) {
function insertChild($xPathQuery, $node, $shiftRight=TRUE, $afterText=TRUE,
$autoReindex=TRUE) {
function appendChild($xPathQuery, $node, $afterText=FALSE,
$autoReindex=TRUE) {
function insertBefore($xPathQuery, $node, $afterText=TRUE,
$autoReindex=TRUE) {
function setAttribute($xPathQuery, $name, $value, $overwrite=TRUE) {
function setAttributes($xPathQuery, $attributes, $overwrite=TRUE) {
function removeAttribute($xPathQuery, $attrList=NULL) {
function getDataParts($xPathQuery) {
function replaceData($xPathQuery, $replacement, $offset = 0, $count = 0,
$textPartNr=1) {
function insertData($xPathQuery, $data, $offset=0) {
function appendData($xPathQuery, $data, $textPartNr=1) {
function deleteData($xPathQuery, $offset=0, $count=0, $textPartNr=1) {

See the setModMatch() function to change the behaviour for when the query
matches more than one node.  These are the options.
   *                        - XPATH_QUERYHIT_ALL (default)
   *                        - XPATH_QUERYHIT_FIRST
   *                        - XPATH_QUERYHIT_UNIQUE

But clearly, passing in an absolute XPath will mean it doesn't have to call
evaluate.

> 3. it would be helpful if the functions were grouped together more, e.g.
if
> getNode and getNodePath were together. In fact, a list of functions by
> category would be useful, so that, for example, wholeText appears with the
> other content retrieval functions, and it's explained how they differ.

The functions are grouped as they appear in the source file, so by class and
then in the order that they are defined in the class.  I had some debate
with Sam over the ordering in the file and we decided that the ordering of
the functions in the source files should assist coding, and the doc will
just have to live with it.  I know it's not ideal, but I don't see an easy
solution to re-doing the order for the doc, so I don't plan to do anything
about this.

> 4. equalNodes should read "compare two nodes" !

Fixed thanks.

> 5. perhaps worth stressing with decodeEntities that it uses PHP functions,
> limited to 8859-1.

Ok have added:

   * It makes use of the get_html_translation_table(HTML_ENTITIES) php
library
   * call, so is limited in the same ways.  At the time of writing this
seemed
   * be restricted to iso-8859-1

How does that sound?

> 6. I think you mean 'relational database' - it may also be rational :-)

Heh, changed.

Thanks for the input Peter :o)

Nigel