Updated #2

Author: dantleech

Diff for: book/conclusion.rst

@@ -1,7 +1,7 @@
 Conclusion and further reading
 ==============================
 
-We hope this tutorial helps to get you started. If you miss anything, have suggestions or questions, please contact us on [email protected] or #jackalope on irc.freenode.net
+We hope this guide helps to get you started. If you miss anything, have suggestions or questions, please contact us on [email protected] or #jackalope on irc.freenode.net
 
 Further reading
 ---------------

Diff for: book/getting_started.rst

@@ -3,7 +3,7 @@ Getting Stated
 
 This aims to provide a rounded general reference to PHPCR. You will mostly see
 code examples. It should work with any PHPCR implementation. We propose using
-[Jackalope Jackrabbit](https://github.com/jackalope/jackalope-jackrabbit) to
+`Jackalope Jackrabbit <https://github.com/jackalope/jackalope-jackrabbit>`_ to
 get started as it supports all features described here.
 
 Installing Jackalope
@@ -76,7 +76,8 @@ Still with us? Good, lets get in a bit deeper...
 Get some data into the repository
 ---------------------------------
 
-We will discuss the import feature in more detail later, but to have some data, we just import something here. Create an XML file called `test.xml`:
+We will discuss the import feature in more detail later, but to have some
+data, we just import something here. Create an XML file called `test.xml``:
 
 .. code-block:: xml
 
@@ -104,4 +105,4 @@ You may also use the PHPCR Shell to import data:
 
 .. code-block:: bash
 
-   $ phpcrsh -pmyprofile -c "session:import-xml test.xml"
+   phpcrsh -pmyprofile -c "session:import-xml test.xml"

Diff for: book/import_export.rst

@@ -11,11 +11,12 @@ are two formats:
     of the repository with all type information. However, it is more verbose.
 
 As an analogy, think about an SQL dump file with SQL statements and the dump of
-an SQL table into a csv file. You can restore the data from both, but the SQL
+an SQL table into a ``csv`` file. You can restore the data from both, but the SQL
 dump knows every detail about your field types and so on while the CSV just
 knows the data.
 
-When exporting, you tell explicitly to which format you want to export:
+When exporting, you explictly call a method corresponding to the desired
+format:
 
 .. code-block:: php
 
@@ -60,7 +61,7 @@ valid XML document it is imported as document:
 
 When importing nodes with a uuid, a couple of different behaviors can be used:
 
-* `IMPORT_UUID_CREATE_NEW`: Create new UUIDs for nodes that are imported, so you never get collisions.
-* `IMPORT_UUID_COLLISION_THROW`: Throw an exception if a node with the same UUID already exists.
-* `IMPORT_UUID_COLLISION_REMOVE_EXISTING`: Remove an existing node if an imported node has the same UUID.
-* `IMPORT_UUID_COLLISION_REPLACE_EXISTING`: Replace existing node with the imported node. This can lead to the imported data being put in various places.
+* ``IMPORT_UUID_CREATE_NEW``: Create new UUIDs for nodes that are imported, so you never get collisions.
+* ``IMPORT_UUID_COLLISION_THROW``: Throw an exception if a node with the same UUID already exists.
+* ``IMPORT_UUID_COLLISION_REMOVE_EXISTING``: Remove an existing node if an imported node has the same UUID.
+* ``IMPORT_UUID_COLLISION_REPLACE_EXISTING``: Replace existing node with the imported node. This can lead to the imported data being put in various places.

Diff for: book/introduction.rst

@@ -3,7 +3,7 @@ Introduction
 
 In the following chapters, we will show how to use the API. But first, you
 need a very brief overview of the core elements of PHPCR. After reading this
-tutorial, you should browse through the API documentation to get an idea what
+guide, you should browse through the API documentation to get an idea what
 operations you can do on each of those elements. See the conclusions for links
 if you want to have more background.
 

Diff for: book/locking.rst

@@ -1,12 +1,12 @@
 Locking
 =======
 
-In PHPCR, you can lock nodes to prevent concurrency issues. There is two basic types of locks:
+In PHPCR, you can lock nodes to prevent concurrency issues. There are two basic types of locks:
 
 * Session based locks are only kept until your session ends and released automatically on logout.
 * If a lock is not session based, it is identified by a lock token and stays in place until it times out
 
-Note that jackalope currently only implements session based locks:
+Note that Jackalope currently only implements session based locks:
 
 .. code-block:: php
 

Diff for: book/node_types.rst

@@ -5,10 +5,10 @@ PHPCR supports node types. Node types define what properties and children a node
 
 In a nutshell:
 
-* `nt:unstructured` does not define any required properties but allows any property or child.
-* `nt:file` and `nt:folder` are built-in node types useful to map a file structure in the repository. (With jackalope-jackrabbit, files and folders are exposed over webdav)
+* ``nt:unstructured`` does not define any required properties but allows any property or child.
+* ``nt:file`` and ``nt:folder`` are built-in node types useful to map a file structure in the repository. (With jackalope-jackrabbit, files and folders are exposed over webdav)
 * If you **do not** want to enforce a schema on your node, use
-  `nt:unstructured`.
+  ``nt:unstructured``.
 * If you need to store additional properties or children on existing node types like files, note that while a node can have only one primary type, every node can have any mixin types. Define a mixin type declaring your additional properties, register it with PHPCR and addMixin it to the nodes that need it.
 
 You can define your own node types if you want the equivalent of a strictly defined database structure. See `JCR 2.0: 3.7 Node Types <http://www.day.com/specs/jcr/2.0/3_Repository_Model.html#3.7%20Node%20Types>`_ and `JCR 2.0: 19 Node Type Management <http://www.day.com/specs/jcr/2.0/19_Node_Type_Management.html>`_ / `PHPCR Node Type Namespace <http://phpcr.github.io/doc/html/index.html>`_.

Diff for: book/performance.rst

@@ -1,27 +1,49 @@
 Performance considerations
 ==========================
 
-While PHPCR can perform reasonably well, you should be careful. You are working with an object model mapping interlinked data. Implementations are supposed to lazy load data only when necessary. But you should take care to only request what you actually need.
+While PHPCR can perform reasonably well, you should be careful. You are
+working with an object model mapping interlinked data. Implementations are
+supposed to lazy load data only when necessary. But you should take care to
+only request what you actually need.
 
-The implementations will also use some sort of storage backend (Jackrabbit, (no)SQL database, ...). There might be a huge performance impact in configuring that storage backend optimally. Look into your implementation documentation if there are recommendations how to optimize storage.
-
-One thing *not* to worry about is requesting the same node with Session::getNode or Node::getNode/s several times. You always get the same object instance back without overhead.
+The implementations will also use some sort of storage backend (Jackrabbit,
+(no)SQL database, ...). There might be a huge performance impact in
+configuring that storage backend optimally. Look into your implementation
+documentation if there are recommendations how to optimize storage.
 
+One thing *not* to worry about is requesting the same node with
+Session::getNode or Node::getNode/s several times. You always get the same
+object instance back without overhead.
 
 Only request what you need
 --------------------------
 
-emember that you can filter nodes on Node::getNodes if you only need a list of specific nodes or all nodes in some namespace.
-
-The values of binary properties can potentially have a huge size and should only loaded when really needed. If you just need the size, you can get the property instance and do a $property->getSize() instead of filesize($node->getPropertyValue). Any decent implementation will not preload the binary stream when you access the property object.
-
-When getting the properties from a node, you can use Node::getPropertiesValues(filter, false). This allows the implementation to avoid instantiating Property objects for the property values (and saves you coding). The second boolean parameter tells wheter to dereference reference properties. If you do not need the referenced objects, pass false and you will get the UUID or path strings instead of node objects.(If you need one of them, you can still get it with Session::getNodeByIdentifier. But then the implementation will certainly not be able to optimize if you get several referenced nodes.)
-
+emember that you can filter nodes on Node::getNodes if you only need a list of
+specific nodes or all nodes in some namespace.
+
+The values of binary properties can potentially have a huge size and should
+only loaded when really needed. If you just need the size, you can get the
+property instance and do a $property->getSize() instead of
+filesize($node->getPropertyValue). Any decent implementation will not preload
+the binary stream when you access the property object.
+
+When getting the properties from a node, you can use
+Node::getPropertiesValues(filter, false). This allows the implementation to
+avoid instantiating Property objects for the property values (and saves you
+coding). The second boolean parameter tells wheter to dereference reference
+properties. If you do not need the referenced objects, pass false and you will
+get the UUID or path strings instead of node objects.(If you need one of them,
+you can still get it with Session::getNodeByIdentifier. But then the
+implementation will certainly not be able to optimize if you get several
+referenced nodes.)
 
 But request in one call as much as possible of what you need
 ------------------------------------------------------------
 
-If you need to get several nodes where you know the paths, use Session::getNodes with an array of those nodes to get all of them in one batch, saving round trip time to the storage backend.
+If you need to get several nodes where you know the paths, use
+``Session::getNodes`` with an array of those nodes to get all of them in one
+batch, saving round trip time to the storage backend.
 
-lso use Node::getNodes with a list of nodes rather than repeatedly calling Node::getNode.
+You can also use ``Node::getNodes`` with a list of nodes rather than repeatedly calling
+``Node::getNode``.
 

Diff for: book/query.rst

@@ -53,29 +53,29 @@ You can access the QueryObjectModelFactory from the session:
     <?php
     $qomFactory = $mySession->getWorkspace()->getQueryManager()->getQOMFactory();
 
-The QOM factory has a method to build a QOM query given four parameters, and [provides methods](http://phpcr.github.com/doc/html/phpcr/query/qom/queryobjectmodelfactoryinterface.html) to build these four parameters:
+The QOM factory has a method to build a QOM query given four parameters, and `provides methods <http://phpcr.github.com/doc/html/phpcr/query/qom/queryobjectmodelfactoryinterface.html>`_ to build these four parameters:
 
 .. code-block:: php
 
     <?php
     $queryObjectModel = $QOMFactory->createQuery(SourceInterface source, ConstraintInterface constraint, array orderings, array columns);
 
-`source` is made out of one or more selectors. Each selector selects a subset of nodes. Queries with more than one selector have joins. A query with two selectors will have a join, a query with three selectors will have two joins, and so on.
+- ``source`` is made out of one or more selectors. Each selector selects a subset of nodes. Queries with more than one selector have joins. A query with two selectors will have a join, a query with three selectors will have two joins, and so on.
 
-`constraint` filters the set of node-tuples to be retrieved. Constraint may be combined in a tree of constraints to perform a more complex filtering. Examples of constraints are:
+``constraint`` filters the set of node-tuples to be retrieved. Constraint may be combined in a tree of constraints to perform a more complex filtering. Examples of constraints are:
 
-* Absolute or relative paths: nodes descendant of a path, nodes children of a path, nodes reachable by a path.
-* Name of the node.
-* Value of a property.
-* Length of a property.
-* Existence of a property.
-* Full text search.
+    - Absolute or relative paths: nodes descendant of a path, nodes children of a path, nodes reachable by a path.
+    - Name of the node.
+    - Value of a property.
+    - Length of a property.
+    - Existence of a property.
+    - Full text search.
 
-`orderings` determine the order in which the filtered node-tuples will appear in the query results. The relative order of two node-tuples is determined by evaluating the specified orderings, in list order, until encountering an ordering for which one node-tuple precedes the other.
+- ``orderings`` determine the order in which the filtered node-tuples will appear in the query results. The relative order of two node-tuples is determined by evaluating the specified orderings, in list order, until encountering an ordering for which one node-tuple precedes the other.
 
-`columns` are the columns to be included in the tabular view of query results. If no columns are specified, the columns available in the tabular view are implementation determined. In Jackalope include, for each selector, a column for each single-valued non-residual property of the selector's node type.
+- ``columns`` are the columns to be included in the tabular view of query results. If no columns are specified, the columns available in the tabular view are implementation determined. In Jackalope include, for each selector, a column for each single-valued non-residual property of the selector's node type.
 
-The simplest case is to select all `[nt:unstructured]` nodes:
+The simplest case is to select all ``[nt:unstructured]`` nodes:
 
 .. code-block:: php
 

Diff for: book/reading_data_and_traversal.rst

@@ -1,8 +1,11 @@
 Reading data and traversal
 ==========================
 
-You can wrap any code into try catch blocks. See the `API doc <http://phpcr.github.com/doc/html/index.html>`_ for what exceptions to expect on which calls. With PHPCR being ported from Java, there is a lot of Exceptions defined.
-But as this is PHP, you don't have to catch them. As long as your content is as the code expects, it won't matter.
+You can wrap any code into try catch blocks. See the `API doc
+<http://phpcr.github.com/doc/html/index.html>`_ for what exceptions to expect
+on which calls. With PHPCR being ported from Java, there is a lot of
+Exceptions defined.  But as this is PHP, you don't have to catch them. As long
+as your content is as the code expects, it won't matter.
 
 .. code-block:: php
 
@@ -107,4 +110,3 @@ Traversing the hierarchy
     } while ($parent != $node);
     var_dump($breadcrumb);
 
-

Diff for: book/references.rst

@@ -1,11 +1,13 @@
 Node and property references
 ============================
 
-Nodes can be referenced by unique id (if they are mix:referenceable) or by path. getValue returns the referenced node instance.
-Properties can only be referenced by path because they can not have a unique id.
+Nodes can be referenced by unique id (if they are mix:referenceable) or by
+path. getValue returns the referenced node instance.  Properties can only be
+referenced by path because they can not have a unique id.
 
 The test document we imported above does not contain the type information we
-need to show this example. Lets create a special one and load it into the repository with Session::importXML:
+need to show this example. Lets create a special one and load it into the
+repository with ``Session::importXML``:
 
 .. code-block:: xml
 

Diff for: book/search.rst

@@ -3,5 +3,12 @@ Search
 
 TODO: intelligent filtering criteria to do as little in-memory operations to apply criteria.
 
-If you do not need the node objects but just some value, query for that value and use the result Row to avoid instantiating Node objects alltogether. If you need the Node objects, help PHPCR to optimize by using QueryResult::getNodes and iterating over the nodes instead of getting the rows, iterating over them and calling getNode on each row. (Actually, if you first do the getNodes(), you can then iterate over the rows and get the individual nodes and still use the special row methods as the implementation should have prefetched data on the getNodes.)
+If you do not need the node objects but just some value, query for that value
+and use the result Row to avoid instantiating Node objects alltogether. If you
+need the Node objects, help PHPCR to optimize by using QueryResult::getNodes
+and iterating over the nodes instead of getting the rows, iterating over them
+and calling getNode on each row. (Actually, if you first do the getNodes(),
+you can then iterate over the rows and get the individual nodes and still use
+the special row methods as the implementation should have prefetched data on
+the getNodes.)
 

Diff for: book/versioning.rst

@@ -1,7 +1,8 @@
 Versioning
 ==========
 
-Versioning is used to track changes in nodes with the possibility to get back to older versions.
+Versioning is used to track changes in nodes with the possibility to get back
+to older versions.
 
 A node with the mixin type `mix:versionable` or `mix:simpleVersionable` can be
 versioned. Versioned nodes have a version history, containing the root version

Diff for: book/writing.rst

@@ -4,9 +4,12 @@ Writing data
 Creating and updating nodes
 ---------------------------
 
-With PHPCR, you never use 'new'. The node works as a factory to create new nodes and properties. This has the nice side effect that you can not add a node where there is no parent.
+With PHPCR, you never use 'new'. The node works as a factory to create new
+nodes and properties. This has the nice side effect that you can not add a
+node where there is no parent.
 
-Everything you do on the Session, Node and Property objects is only visible locally in this session until you save the session.
+Everything you do on the Session, Node and Property objects is only visible
+locally in this session until you save the session.
 
 .. code-block:: php