Re: Some suggestions for documentation

[Peter R. <php...@pe...>]

On Thursday 16 May 2002 2:20, Nigel Swinson wrote:
>
> > 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) {

hm, I can see that being able to update all the nodes in a set with one 
instruction is useful, but why getDataParts and not any of the other get 
functions? Documentation for getDataParts doesn't mention this!

Surely the main reason it was 'such a common problem' was because the 
documentation wasn't clear. To get a particular node, use a get function; to 
get a list of nodes meeting an xpathquery criterion, use evaluate/match, and 
then loop through the resulting array. Seems clear to me!

> 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.

perhaps what's needed is a separate FAQ: 'how do I ...' 

> > 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?

it doesn't 'seem to be restricted', it is!

On a related issue, could you add the ability to set the source encoding. 
Though you have the options, which enable setting of target encoding, it 
looks like source definition isn't in phpxpath at present, meaning it uses 
the default, which in PHP for some reason is 8859-1. I would have thought 
PHP's default should be whatever is given in the xml file or, failing that, 
the xml default, which is utf8 - but ... 
I am currently using non-Latin1 charsets only in a database, but intend to 
expand this into xml. I can foresee problems if it assumes everything is in 
8859-1 !