further set of updates

documentation/docs/components/geomodelxml/components/gmx2geo.md

-# gmx2geo
+# Gmx2Geo
 
-[DESCRIBE GMX2GE0]
\ No newline at end of file
+`Gmx2Geo` is the main top-level class of `GeoModelXML`, and as the name suggests, it is the interface through which `GeoModel` objects are created from the `GeoModelXML` processing of the input XML files. It takes as inputs:
+
+- The XML files to be processed
+- A "world" volume into which the geometry tree to be built will be inserted
+- a `gmxInterface` to be used for communication with downstream code (or simply debugging)
+- flags to steer behvaiour (e.g. whether to read from a file or a string from a database)
+- a list of additional `processors` to be run on top of the "standard list" in `GmxUtil` (the main "driver" class)
+
+The primary uses of `Gmx2Geo` are therefore in intergrating `GeoModelXML` in a more general software framework as the method of building `GeoModel` detector description, or in writing plugins which can be used by the other `GeoModel` tools such as `gmcat`, `gmex`, etc. 

documentation/docs/components/geomodelxml/components/gmxinterface.md

-[DESCRIBING GMXINTERFACE]
\ No newline at end of file
+# GmxInterface
+
+`GmxInterface`, as the name suggests, is an *interface* class, intended to allow client code to access information from `GeoModelXML` and build on top of it within the relevant software stack. `GmxInterface` therefore implements a selection of methods to allow access to information which is expected to be needed elsewhere downstream within the client software. These methods in this base classs from `GeoModelXML` are expected to be overridden in a *derived* class by the client, so that they can provide the necessary context-specific handling of the information. The following methods are implemented in the base class:
+
+- *sensorId/splitSensorId*: To format the indices defined in the [`positionindex`](../../readout/#identifying-sensitive-volumes) into the necessary format for the client code to use. Called whenever a sensitive `logvol` has been encountered, and the result of this method should be written to a `GeoIdentifierTag` for the volume. 
+- *addSensorType*: Called whenever a new [`sensortype`](../../readout/#making-volumes-sensitive) is encountered. It allows client code to create and store as appropriate its catalog of possible sensor representations.
+- *addSensor/addSplitSensor*: Called whenever a [`sensitive` `logvol`](../../readout/#making-volumes-sensitive) is encountered, allowing a representation of a specific sensor to be created and stored by the client code. 
+- *addAlignable/addSplitAlignable:* called whenever an [`alignable` volume](../../alignment/#making-volumes-alignable) is encountered, it allows the `GeoFullPhysVol` and `GeoAlignableTransform` pointers to be passed to the client code for use, as well as any additional information such as the alignment `level` of the volume.
+- setPublisher: allows a *publisher* to be set, such that the `readout` information will be written to `SQLite` tables by that publisher.
+- publish: write the provided information via the above *publisher*
+
+It also provides helpers for accessing the `readout` information, `getParameter` and `getParameters` for retrieving single and vectors of parameters respectively (plus `checkParameter` for testing the existence of a given parameter in the `readout` definition).
+
+
+

documentation/docs/components/geomodelxml/components/processors.md

-[DESCRIBING PROCESSORS]
+`GeoModelXML` uses `processors` to append specific information that should be associated with an XML element into a vector that gets passed the various steps. The standard list of `processors` applied (in `GmxUtil`) is:
 
-## Supported shapes
\ No newline at end of file
+## Standard processors
+
+- *addbranch*: define a volume hierarchy to actually be built
+- *logvol/logvolref*: create a `logvol` (or use one that previously been defined)
+- *assembly/assemblyref*: create an `assembly` (or use one that has already been defined) 
+- *transform*: create a geometrical transformation (rotation, translation, etc)
+- *multicopy*: create multiple instances of a given `logvol` or `assembly` according to a given transformation rule to be apllied for each instance
+- *replicaX/replicaY/replicaZ/replicaRPhi/replicaXYarrays*: similar to `multicopy` - create multuple instances of a given `logvol` or `assembly` with a defined periodic structure
+- *index*: create a set of indices for addressing a volume
+
+More information on the meanings can be found in the sections on [building a geometry](../../buildinggeometry/) and [defining readout](../../readout/).
+
+## Supported shapes
+
+The following shapes are supported by `GeoModeXML`. The names reflect the `Geant4` shapes on which they are based (and may eventually create). 
+
+- simplepolygonbrep
+- twistedtrap
+- ellipticaltube
+- torus
+- box
+- cons
+- generictrap
+- para
+- pcon
+- pgon
+- trap
+- trd
+- tube
+- tubs
+
+In addition, the following boolean operations are defined, and can be applied to any of the above shapes, to create new solid volume possibilities.
+
+- intersection
+- union
+- subtraction
+
+Note that boolean operations can be very CPU intensive to navigate.
+
+To-do: add the arguments for each type?
\ No newline at end of file

documentation/docs/components/geomodelxml/readout.md

@@ -52,7 +52,7 @@ These can be set for a `logvol` or `assembly` via an `index` element directly, i
 
 ```
 <assembly name="Layer1" >
-   <index ref="layer" value="1"/>
+   <index ref="layer" value="2"/>
    [rest of assembly definition]
 </assembly>   
 ```

documentation/docs/components/geomodelxml/troubleshooting.md

-# Troubleshooting
\ No newline at end of file
+# Troubleshooting
+
+Some typical errors that can happen, and how to debug and/or solve them. This is an evolving list and may differ depending on the specific version of `GeoModelXML`, as bugs are solved and others revealed.
+
+- `evaluate: invalid expression. Last good expression was ...`:
+
+This error indicates an issue when XML is being parsed. Check for typos or invalid syntax in defining parameters, providing names to `logvolref`, etc.
\ No newline at end of file