[XPath] editorial document structure

In Xpath 1, a reader does not have to read far in to the document (5
pages out of 35 in my "print preview") before seeing examples of the
fundamental "path" nature of Xpath:

child::para selects the para element children of the context node

In the Xpath 2 document, I fear the majority of readers will have given
up in despair before ever seeing a Path. The description of steps comes
after mountains of dense only marginally interesting on facts on typing
syntax, diagrams of possible processing models, etc. Error handling
(2.5) and Optional features (2.6) come before the reader has even seen
any basic expression syntax. This all seems to be backwards.

I now have to wait until page 47 of 89 (ie over half way in) before
seeing the example 

child::para selects the para element children of the context node

I suspect that you are not going to want to completely re-structure the
document this late in the process (although that would be worthwhile I
think) but if you don't do that, could you at least expand section 2
Basics to have some usable (to an end-user) description of what a simple
Xpath expression looks like?

Sorry that this isn't a particularly constructive comment, but it's hard
to suggest specific re-organisation without following the details of
your document build process, whether reordering sections for example
could be purely a stylesheet matter or would require re-writing the
source xml, also I realise that the sources are shared with the Xquery
doc, although probably these comments apply equally to that.

David


________________________________________________________________________
This e-mail has been scanned for all viruses by Star Internet. The
service is powered by MessageLabs. For more information on a proactive
anti-virus service working around the clock, around the globe, visit:
http://www.star.net.uk
________________________________________________________________________

Received on Tuesday, 18 November 2003 11:58:48 UTC