diff --git a/documentation/docs/components/kernel/overview/MaterialGeometry.md b/documentation/docs/components/kernel/overview/MaterialGeometry.md
index 12af18a746f40871d0abb1e68d4281b842760593..a94751a87e126ccd999554c77da97343ef9a9d53 100644
--- a/documentation/docs/components/kernel/overview/MaterialGeometry.md
+++ b/documentation/docs/components/kernel/overview/MaterialGeometry.md
@@ -46,6 +46,8 @@ The materials are then used to together with shapes to form logical volumes, dis
 
 Shapes are created using the new operator. Essentially, shapes within this system are required to store and provide access to the geometrical constants that describe their geometrical form. This data is, insofar as possible, to be specified on the constructor.
 
+Shapes are extensible and custom shapes can be built.
+
 Here is how one builds a box:
 
 ```cpp
diff --git a/documentation/docs/components/kernel/reference/Actions.md b/documentation/docs/components/kernel/reference/Actions.md
new file mode 100644
index 0000000000000000000000000000000000000000..323a5594f8eeabfad060b2b7f78c614e9810f695
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/Actions.md
@@ -0,0 +1,273 @@
+
+
+## Actions
+
+The principle way of accessing the physical volume tree is through actions which facilitate a recursive tree traversal and accumulate certain volatile information, such as a volume’s absolute position, during the traversal.  An action is applied to a node in the tree, which applies it in turn to its children.  
+
+One type of action, `GeoNodeAction`,  is passed to all children.  Another type, `GeoVolumeAction`, is only passed only to daughter physical volumes (this includes “virtual” physical volumes that come from parameterizations).   Casual users should consider subclassing `GeoVolumeAction` in order to recurse through all of the physical volumes in the geometry graph.  “Power users” will occasionally need to access the geometry graph directly, in order to visit nodes such as `GeoSerialTransformer` nodes.   Such users should consider subclassing `GeoNodeAction`.  This section describes the two types of existing actions in more detail.
+
+
+
+### Volume Actions and associated classes
+
+
+#### GeoVolumeAction
+
+`GeoVolumeAction` is a base class specifically designed for user subclassing, and all users are encouraged to use it for data access.  
+
+Its interface is here:
+
+```cpp
+//=== GeoVolumeAction ===
+
+  // Enumerated Types:
+  enum GeoVolumeAction::Type {TOP_DOWN, BOTTOM_UP}
+
+  // Constructor:
+  GeoVolumeAction (Type type  = TOP_DOWN)
+
+  // Public Methods:
+  void handleVPhysVol (const GeoVPhysVol * )
+  void terminate ()
+  const GeoTraversalState * getState () const
+```
+
+In order to subclass this, follow this checklist:
+
+1.	Write a class inheriting from `GeoVolumeAction`.  You should decide whether your class should walk through the volumes from the top down, which is the default, or from the bottom up.  If you want a bottom up tree traversal you need to initialize the base class, accordingly, in the constructor for your new class.
+
+2.	Override the `handleVPhysVol()` method in order to do something with each volume you encounter during geometry graph traversal.  You may, of course, add member data or additional methods in order to carry out the action, or to access results.  
+
+3.	If you wish for the action to hit every node in the tree, you don’t need to do anything special.  If you wish it to terminate early, call the `terminate()` method from with your `handleVPhysVol()`.  Geometry graph traversal will immediately terminate.
+
+4.	The action keeps track of its traversal state, accumulating such information as absolute transformation to the current node, and the path to the current node.  The state can be retrieved from the `getState()` method.  This may be called from with your `handleVPhysVol()` method in order to, say, find out where you are in global coordinates.
+
+
+
+A GeoVolumeAction upon a tree of physical volumes is initiated when the following line of code is invoked:
+
+```cpp
+GeoPhysVol        *vol;
+MyGeoVolumeAction action;
+vol->apply(&action);
+```
+
+Your `handleVPhysVol()` routine can obtain information about the current node from two sources:  first, from the physical volume itself, which is passed as an argument to the routine, and secondly from the state (class `GeoTraversalState`) which is available from the `getState()` method.  We examine that next.
+
+
+#### GeoTraversalState
+
+```cpp
+//=== GeoTraversalState ===
+
+  // Const Public Methods:
+  const HepTransform3D & getTransform () const
+  const std::string & getName () const
+  Query<unsigned int> getId() const
+  const HepTransform3D & getDefTransform () const
+  const std::string & getAbsoluteName () const
+  const HepTransform3D & getDefAbsoluteTransform () const
+  const HepTransform3D & getAbsoluteTransform () const
+  const GeoNodePath * getPath () const
+```
+
+The interface is simple and self-explanatory; only the getPath() method and the information it returns needs further explanation.   The path (class GeoNodePath) is an ordered stack of nodes that shows how the current node was reached.  
+
+Its interface is shown here:
+
+#### GeoNodePath
+
+```cpp
+//== GeoNodePath ==
+
+  // Public Methods:
+  unsigned int getLength ()
+  const GeoVPhysVol * getItem(unsigned int i)
+  const GeoVPhysVol * getHead ()
+  const GeoVPhysVol * getTail ()
+```
+
+
+The head node, or node from which the action was initiated, and tail node, or last node in the path, are available.  The total length of the path can be retrieved, as well as arbitrary item along the path.  
+
+
+#### TemplateVolAction
+
+TemplateVolAction is a class which has been added only as an illustration for how to write volume actions.  The header file is shown here below: 
+
+```cpp
+#ifndef TemplateVolAction_h
+#define TemplateVolAction_h 1
+
+class TemplateVolAction:public GeoVolumeAction	
+{
+
+public:
+ 
+  // Constructor
+  TemplateVolAction ();
+
+  // Destructor
+  ~TemplateVolAction ();
+
+  // Action routine
+  virtual void handleVPhysVol (const GeoVPhysVol *);
+
+};
+#endif
+```
+
+while the source file is shown in the following:
+
+```cpp
+#include "GeoModelKernel/TemplateVolAction.h"
+
+TemplateVolAction::TemplateVolAction ()
+:GeoVolumeAction (GeoVolumeAction::TOP_DOWN)
+{
+}
+
+TemplateVolAction::~TemplateVolAction ()
+{
+}
+
+void TemplateVolAction::handleVPhysVol (const GeoVPhysVol *)
+{
+  /* 
+   * Your procedure here.  This one does nothing...
+   */
+}
+```
+
+
+
+### Node Actions
+
+
+`GeoNodeAction` classes do more than traverse the tree of physical volumes.  These actions stop and execute on every graph node in the geometry graph, not the physical volumes represented within or generated by the geometry graph.  Three kinds of node actions are used internally by the kernel:
+
+- `GeoCountVolAction`,
+- `GeoAccessVolumeAction`,
+- `GeoClearAbsPosAction`.
+
+`GeoCountVolAction` counts the number of physical volumes below some node, down do a depth. `GeoAccessVolumeAction` is for retrieving a particular volume.  `GeoClearAbsPosAction` can be used to invalidate a cache of absolute position information below some node. The first two have potential usefulness outside of the geometry kernel itself, and will be discussed below.
+
+The following methods are available on all `GeoNodeAction` classes, and control the depth limit:
+
+- `void setDepthLimit(int limit)`;
+- `Query<unsigned int> getDepthLimit() const`;
+- `void clearDepthLimit()`,
+
+Specific `GeoNodeAction` classes may set specific defaults for their depth limits.   See the documentation on these actions.
+
+
+
+#### GeoCountVolAction
+
+```cpp
+//== GeoCountVolAction ==
+
+  // Constructor:
+  GeoCountVolAction ();
+
+  // Public Methods:
+  const  unsigned int getCount() const;
+```
+
+When this action is executed upon a node it counts daughter volumes.  The count includes only physical volumes.  It contains virtual, or parameterized volumes as well as actual volumes.
+The depth limit for this action by default is 1:  only the volumes directly beneath the top volume are counted.  The final count does not include the top volume, only the children. The depth limit can be reset or cleared using the methods `clearDepthLimit()` or `setDepthLimit()` from the base class.  
+
+Here is a typical use case:
+
+```cpp
+GeoPhysVol *world;
+GeoCountVolAction cv;
+cv->setDepthLimit(2);
+world->exec(&cv);
+int count = cv.getCount ();
+```
+
+
+#### GeoAccessVolumeAction
+
+```cpp
+//== GeoAccessVolumeAction ==
+
+  // Constructor:
+  GeoAccessVolumeAction (unsigned int Index)
+
+  // Public Methods:
+  PVConstLink getVolume () const
+  const HepTransform3D & getTransform () const
+  const HepTransform3D & getDefTransform () const
+  const std::string & getName () const
+  Query<unsigned int> getId() const
+```
+
+`GeoAccessVolumeAction` is used to retrieve physical volume and some of its properties from within the geometry tree.  
+
+The constructor needs to provide the index of the child volume which is sought.  The public methods can be used once the action has executed and return a link to the daughter volume, the transform to the daughter, the default transform to the daughter, and the name of the daughter. 
+
+A typical use case is shown here:
+
+```cpp
+int index
+GeoFullPhysVol *vol;
+GeoAccessVolumeAction av (index);
+vol->exec (&av);
+std::string name = av->getName();
+```
+
+Besides the name, the transformations (default and misaligned), can be retrieved along with the volume.  The action executes to a depth of 1; i.e. it is used only for accessing direct descendents.
+
+A simpler alternative to accessing daughter volumes in this way is to use the methods in `GeoVPhysVol` and subclasses to retrieve information about their daughters.  This is simpler, and uses the action internally.  Using the action directly, however, can be faster if accessing different kinds of information at the same time since the volume location can be performed just once. 
+
+
+
+
+### For Power Users: How to Make Your Own `GeoNodeAction`
+
+The basic structure of the GeoModel is:  a geometry graph which emulates a physical volume tree.   The graph is constructed by adding a combination of physical volumes, transformations, name tags, serial denominators and serial transformers into physical volumes.  The information is usually retrieved by scanning the physical volume tree as opposed to the geometry graph.  The class `GeoVolumeAction` exists in order to be subclassed by users for this purpose.  
+
+
+However, in certain more rare cases users will need to navigate the geometry graph directly.  For example, when declaring the geometry to the simulation, one may wish to translate GeoModel parametrizations from `GeoSerialTransformer` nodes into `G4Parametrizations`.  In that case one is interested in accessing the parametrization directly and not the virtual volumes that they generate.   These ''power users'' can access all nodes in the geometry tree by subclassing `GeoNodeAction`.  In this subsection, we examine how to do this.  
+
+
+#### GeoNodeAction
+
+GeoNodeAction has the following interface:
+
+```cpp
+//== GeoNodeAction ==
+
+  // Constructor:
+  GeoNodeAction()
+
+  // Public Methods:
+  GeoNodePath * getPath () const
+  Query<unsigned int>  getDepthLimit () const
+  void terminate ()
+  bool shouldTerminate () const
+  void setDepthLimit (unsigned int limit)
+  void clearDepthLimit ()
+
+  // Virtual Public Methods to be overridden in subclasses:
+  void handleNode (const GeoGraphNode * )
+  void handleTransform (const GeoTransform * )
+  void handlePhysVol (const GeoPhysVol * )
+  void handleFullPhysVol (const GeoFullPhysVol * )
+  void handleNameTag (const GeoNameTag * )
+  void handleIdentifierTag(const GeoIdentifierTag *)
+  void handleSerialDenominator (const GeoSerialDenominator * )
+  void handleSerialTransformer (const GeoSerialTransformer  * )
+```
+
+
+When subclassing the `GeoNodeAction`, the principle task is to write a handle method for each type of `GeoGraphNode` object that you wish to visit.  These methods are shown in the above table under the rubric “Virtual Public Methods to be overridden in subclasses”.  They are called in sequence each time a specific kind of graph node is encountered, from top to bottom.
+
+In addition, the action can specify its own depth by calling the methods `setDepthLimit()` and `clearDepthLimit()`.  In addition the action can be terminated by any time by calling the `terminate()` method; usually this should be done within one of the handler methods.  The path (class `GeoNodePath`, discussed in section 2.8.1) can also be accessed from anywhere within the class, most notably within the handler methods.
+
+
+
+
+
diff --git a/documentation/docs/components/kernel/reference/Appendix_Query.md b/documentation/docs/components/kernel/reference/Appendix_Query.md
new file mode 100644
index 0000000000000000000000000000000000000000..11b8236a9d16cbc983d31e87738be85dc22d6161
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/Appendix_Query.md
@@ -0,0 +1,36 @@
+
+
+## Appendix: The Query<T> template class.  
+
+
+The template class `Query<T>` is designed as the return type of a query that can fail. One place we use it within this library is to return the index of a daughter volume, in other words, its position within a child list.  If the volume is not found within the daughter list, the query fails.  The failure could be handled in several ways, one of which would be to return a value of -999.  If the user were to blithely use this value without checking it first, the program could likely crash immediately or misbehave later.
+
+The class `Query<unsigned int>` fixes ths problem. Because it has a constructor taking unsigned int as a single argument and a cast operator, it can freely convert itself to and from an unsigned int. So you can write:
+
+```cpp
+GeoPhysVol *parent, *child;
+unsigned int c = parent->getIndex(child);
+```
+
+If the function succeeds, it returns `Query<unsigned int>` and a conversion takes place. But, if it fails, the conversion itself throws an exception, in this case `std::range_error`.  
+
+One does not need to handle the exception in order to proceed past the failed query, a better way is to check the return value, and this can be done by recoding the example as follows:
+
+```cpp
+GeoPhysVol *parent, *child;
+Query<unsigned int> c = parent->getIndex(child);
+if (c.isValid()) {
+    // Now use c like an ordinary unsigned integer:
+    unsigned int d = c+1;
+}
+```
+
+Now, this kind of checking is safer, but can always be skipped if the operation is guaranteed to succeed, for example, if the programmer knows the child is in the daughter list (because she put it there).  The class `Query<T>` is based on the class `Fallible<T>` from reference[^BN1].
+
+
+
+[^BN1]: JJ.Barton and  LR.Nackmann, Scientific and Engineering C++, 1994, Addison Wesley
+
+
+
+
diff --git a/documentation/docs/components/kernel/reference/Materials_Elements.md b/documentation/docs/components/kernel/reference/Materials_Elements.md
index abcabe9ba46a3a8e2beb80d69b8adc1c7d6aea96..0643c7a36fb409c815b042455777aadb90f3b34f 100644
--- a/documentation/docs/components/kernel/reference/Materials_Elements.md
+++ b/documentation/docs/components/kernel/reference/Materials_Elements.md
@@ -27,7 +27,7 @@ Ionization energy loss in materials follows the Bethe-Bloch formula and is gover
 
 Both materials and elements are reference-counted; the reference count of an element is incremented when it added to a material and decremented when a referencing material is destroyed; materials are reference counted when they are used in logical volumes and decremented when the referencing logical volume is destroyed.
 
-[^ME1]: http://pdg.lbl.gov/
+[^ME1]: <http://pdg.lbl.gov/>
 
 
 {!components/kernel/reference/RCBase/GeoElement.md!}
diff --git a/documentation/docs/components/kernel/reference/NameTags.md b/documentation/docs/components/kernel/reference/NameTags.md
index 49e31e4b582f6806b6d2729bbdb0a56c4c3ff8cb..d8d0e8d8baa8d7b65b0f779bbf29fe229a6fa997 100644
--- a/documentation/docs/components/kernel/reference/NameTags.md
+++ b/documentation/docs/components/kernel/reference/NameTags.md
@@ -20,10 +20,10 @@ This object is called a `GeoSerialDenominator`:
 The generation of names using `GeoNameTag` and `GeoSerialDenominator` applies also to the virtual volumes when parameterization is used.  If a name tag is used with parameterization, then all of the virtual physical volumes of the parameterization are given the name tag.  In case a serial denominator is used, each parameterized volume is given a name consisting of the base name plus an additional serial number.
 
 
-In many cases it is useful to assign an identifier, or "serial number", to physical volumes.  One use case is to enable a simulation engine such as GEANT[^NT1] to make a correspondence between a piece of geometry designated as sensitive, and the readout element corresponding to that piece.  For such cases, we provide a GeoIdentifierTag, similar to a GeoNameTag.  It provides a way of labeling physical volumes with an unsigned int.  GeoIdentifierTags, however, apply only to the physical volume that immediately follows the tag in the geometry graph.  Its interface follows:
+In many cases it is useful to assign an identifier, or "serial number", to physical volumes.  One use case is to enable a simulation engine such as GEANT4[^NT1] to make a correspondence between a piece of geometry designated as sensitive, and the readout element corresponding to that piece.  For such cases, we provide a `GeoIdentifierTag`, similar to a `GeoNameTag`.  It provides a way of labeling physical volumes with an unsigned int.   `GeoIdentifierTag` tags, however, apply only to the physical volume that immediately follows the tag in the geometry graph.  Its interface follows:
 
-[^NT1]: https://geant4.web.cern.ch/
+[^NT1]: <https://geant4.web.cern.ch/>
 
 
-{!components/kernel/reference/RCBase/GeoGraphNode/GeoSerialIdentifier.md!}
+{!components/kernel/reference/RCBase/GeoGraphNode/GeoIdentifierTag.md!}
 
diff --git a/documentation/docs/components/kernel/reference/Parametrization.md b/documentation/docs/components/kernel/reference/Parametrization.md
new file mode 100644
index 0000000000000000000000000000000000000000..1a33d9d00521021ec1d9cf7ecf8bbe31d31ed8b5
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/Parametrization.md
@@ -0,0 +1,136 @@
+
+
+## Parametrization
+
+### Introduction
+
+A principle goal in the design of the geometry kernel has been to limit memory usage.  A powerful way of doing this is to parameterize the volumes rather than to create them, say, inside of a single, double, or other multiple loop.
+
+Parameterizations are mathematical recipes for creating volumes.  There are three main ingredients to these recipes:
+
+
+* `GENFUNCTIONS`, which are mathematical function-objects; they allow one to perform function arithmetic in the same way that one performs floating point arithmetic.
+
+* `TRANSFUNCTIONS`, which, together with `GENFUNCTIONS` and `HepTransform3D`, allow one to expand and  parametrize elements of the Euclidean group (i.e., rigid body transformations).
+
+* `GeoSerialTransformer`, a kind of `GeoGraphNode` that allows a particular physical volume to be placed according to a `TRANSFUNCTION` expansion of a rigid body transformation.
+
+
+An example will demonstrate how this is useful. The example is taken from the actual ATLAS detector description, from the GeoModel description of the liquid argon barrel calorimeter:
+
+
+```cpp
+#include "GeoGenericFunctions/AbsFunction.hh"
+#include "GeoGenericFunctions/Variable.hh"
+#include "GeoModelKernel/GeoXF.h"  
+#include "GeoModelKernel/GeoSerialTransformer.h"
+
+using namespace Genfun;
+using namespace GeoXF;
+
+// Define some constants:
+
+GeoPhysVol  *pV, *world;
+int          N;
+double       c1, c2, r, z;
+
+// Construct a simple linear function of a variable i:
+
+Variable      i;
+GENFUNCTION   g = c1+c2*i;
+
+// Parameterize a transformation using this function:
+
+TRANSFUNCTION xf = Pow(HepRotateZ3D(1),g)*
+			       HepTranslateX3D(r)*
+			       HepTranslateZ3D(z);
+
+// Use the parametrized transformation to place a volume N times:
+
+GeoSerialTransformer *st=new GeoSerialTransformer(pV, &xf, N);
+world->add(st);
+```
+
+The file `AbsFunction.hh`, from `GeoModel/GeoModelCore/GeoGenericFunctions`---which has been adapted from the [CLHEP](proj-clhep.web.cern.ch) package---, defines the interface to `GENFUNCTIONS` and must be included.  In addition, if specific functions such as trig functions, higher transcendental functions or physics-specific functions are required, header files for these function-objects should be included from the same area.   
+
+The headers `GeoXF.h` and `GeoSerialTransformer.h` are  needed for the classes `TRANSFUNCTION` and  `GeoSerialTransformer`, respectively.
+
+`GENFUNCTIONS` and `TRANSFUNCTIONS` both live within namespaces, which we access with the `using` statements near the top of the example.  After defining the variables used in this example, we construct a simple linear function of an input variable i:
+
+```cpp
+Variable    i;
+GENFUNCTION g =  c1+c2*i;
+```
+
+This example is very simple, but shows already how we can use these classes to build symbolic expressions.  A variety of functions lives already within `GeoModel/GeoModelCore/GeoGenericFunctions`.  The set is user-extensible, and the extension procedure is amply described within the [CLHEP `GeoGenericFunctions` package documentation](https://proj-clhep.web.cern.ch/proj-clhep/doc/CLHEP_1_7/UserGuide/GenericFunctions/index.html).  Addition, subtraction, multiplication, division, composition, and direct product operations are all valid. 
+
+The next step, in which `TRANSFUNCTIONS` are constructed, parametrizes the rigid body transformation.  The `TRANSFUNCTION`, `xf`, has a function call operator that can be used to evaluate a particular rigid body transformation as a function of an input argument, like this:
+
+```cpp
+HepTransform3D tx = xf(j);
+```
+
+The expansion of the `TRANSFUNCTION` is as follows.  Let  $X_i (i  = 1, 2, … N)$ represent any transformation, either a rotation, a translation, or even some combination of these.  The rotations may be about a coordinate axis, or even some other axis.  Furthermore, let us denote by $f_i(x) ( \textrm{where}\ i =1, 2… N)$  a function of a single variable.  Then, the expansion of an arbitrary function is:
+
+$$
+T(x) = X_1^{f_1(x)} * X_2^{f_2(x)} * X_3^{f_3(x)} \cdots X_n^{f_n(x)}
+$$
+
+In this expression, $T(x)$ is the resulting transformation, which is now a function of the single input parameter, $x$. The expansion is both simple, and completely general.  A single term in this expansion (for example $X_2^{f_2(x)}$), will be referred to as an exponentiated transformation.  It is implemented in terms of the class `Pow`, which has the following constructor:
+
+```cpp
+Pow(const HepTransform3D &, GENFUNCTION f);
+```
+
+Exponentiated transformations are simple transfunctions, and can be composed to make other `TRANSFUNCTIONS`.  The `TRANSFUNCTION` interface also allows one to compose fixed transformations with exponentiated transformations. 
+
+The interface to `GENFUNCTION` and `TRANSFUNCTION` provide all the necessary operations on these types of object.  The interfaces to these types of objects are not simple to read, so we will not attempt to explain them in this document.  Instead, one should assume that all well-defined mathematical properties that apply to functions are properties of `GENFUNCTIONS`, and all mathematical properties that apply to parameterizations of elements of the Euclidean group are properties of `TRANSFUNCTIONS`.
+
+Once one has a a `TRANSFUNCTION` in hand, it can be used together with a `GeoSerialTransformer` object to repeatedly place a physical volume.  To do this, use the following constructor:
+
+```cpp
+GeoSerialTransformer(const GeoPhysVol *pVol,
+                     TRANSFUNCTION xf,
+                     unsigned int N);
+```
+
+
+In this constructor, `pVol` is the volume to be repeatedly placed, `xf` is the `TRANSFUNCTION` that specifies how to place it, and `N` is the desired number of copies.
+
+The `GeoSerialTransformer` can then be added to the geometry graph.  During any subsequent volume traversal, the geometry graph will appear to contain multiple physical volumes at different locations.  However, only the memory of a single physical volume and a `TRANSFUNCTION` is actually allocated.  
+
+During node traversal (using `GeoNodeActions`) one can recover, from the geometry graph, the actual recipe for generating volumes.  This is sometimes useful; for example, in case one wishes to create a GEANT4 parameterization from a GeoModel parameterization.
+
+
+
+
+
+!!! note
+
+    One further word about parameterizations is in order: parameterizations, as they are usually understood, allows for the shape or composition of an object to vary as a function of copy number.  This is presently not a part of the `GeoModelKernel`.  
+
+    However, we intend to include this in subsequent releases.  The basic design strategy is to start with a concrete shape class, such as GeoBox, and to use this a basis of a new class for parameterizing boxes.  In the new class—call it `GeoBoxParameterization`—we replace all of the floating point member data with `GENFUNCTION` member data, and all of the floating point constructor arguments with `GENFUNCTION` constructor arguments.  In this way we create a very flexible recipe for generating a box.  
+
+    The same technique can be used to vary an objects composition as a function of copy number.
+
+
+
+
+### GeoSerialTransformer
+
+
+```cpp
+//=== GeoSerialTransformer ===
+
+  // Constructors:
+  GeoSerialTransformer (const GeoVPhysVol * volume, const GeoXF::Function * func, unsigned int copies)
+
+  // Public Methods:
+  HepTransform3D getTransform (int  i) const
+  unsigned int getNCopies() const
+  PVConstLink getVolume() const;
+ 
+  // Public Methods from GeoGraphNode
+  void exec (GeoNodeAction * action)
+```
+
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoElement.md b/documentation/docs/components/kernel/reference/RCBase/GeoElement.md
index e98709958ed3b439c83fac7b160b8ad7cc74a756..0ec3a2a41789073937c76f03ebf05725d843df48 100644
--- a/documentation/docs/components/kernel/reference/RCBase/GeoElement.md
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoElement.md
@@ -10,8 +10,8 @@
     double getN() const
 ```
 
-`GeoElement` has a constructor which takes a name, a chemical symbol, an atomic number, and an atomic weight[^n2]. The public methods provide access to this information. The `getN()` method returns the effective number of nucleons in the material, Z+A.
+`GeoElement` has a constructor which takes a name, a chemical symbol, an atomic number, and an atomic weight[^gel1]. The public methods provide access to this information. The `getN()` method returns the effective number of nucleons in the material, $Z+A$.
 
-[^n2]: The atomic weight should be specified using units such as g/cm3.
+[^gel1]: The atomic weight should be specified using units such as g/cm3 (also known as CLHEP[^gmat2] units).
 
 
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoIdentifierTag.md b/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoIdentifierTag.md
index 807a700dc613573832b8242dbe01286eec4f7a64..a5e699345757d4a72d9c0328845d6790d2699a2a 100644
--- a/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoIdentifierTag.md
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoIdentifierTag.md
@@ -1 +1,20 @@
+
+
 ### GeoIdentifierTag
+
+```cpp
+//=== GeoIdentifierTag ===
+
+  // Constructors:
+  GeoIdentifierTag (unsigned int id)
+
+  // Public Methods:
+  const std::string & getIdentifier() const
+
+  // Public Methods from GeoGraphNode
+  void exec (GeoNodeAction * action)
+```
+
+
+
+
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoSerialIdentifier.md b/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoSerialIdentifier.md
deleted file mode 100644
index 2b54c67e1bc11d84a5e9c7a87499ad743adac450..0000000000000000000000000000000000000000
--- a/documentation/docs/components/kernel/reference/RCBase/GeoGraphNode/GeoSerialIdentifier.md
+++ /dev/null
@@ -1,20 +0,0 @@
-
-
-### GeoSerialIdentifier
-
-```cpp
-//=== GeoIdentifierTag ===
-
-  // Constructors:
-  GeoIdentifierTag (unsigned int id)
-
-  // Public Methods:
-  const std::string & getIdentifier() const
-
-  // Public Methods from GeoGraphNode
-  void exec (GeoNodeAction * action)
-```
-
-
-
-
diff --git a/documentation/docs/components/kernel/reference/RCBase/GeoMaterial.md b/documentation/docs/components/kernel/reference/RCBase/GeoMaterial.md
index a4ff15bec0eaa2f436a6962472f3251551f32fe4..359cbf88e8d3ca207a84871fd2e6a090c37cce7f 100644
--- a/documentation/docs/components/kernel/reference/RCBase/GeoMaterial.md
+++ b/documentation/docs/components/kernel/reference/RCBase/GeoMaterial.md
@@ -21,30 +21,30 @@
 `GeoMaterial` is a class that describes a material, which is a list of elements. It is created “empty”; subsequently, elements are added one-by-one until the material is "locked". When the material is locked, no further editing is possible, and a series of derived quantities (radiation length, interaction length, etc.) is computed for the material.
 
 
-`GeoMaterial (const std::string & Name, double Density) const` Constructs the material with a name and a density[^n1]
+The construvctor, `GeoMaterial(const std::string & Name, double Density)` Constructs the material with a name and a density[^gmat1].
 
 
-`void add (GeoElement * element, double fraction = 1.0)`  Adds an element to the material, with a specified mass fraction.
+The method `add(GeoElement * element, double fraction = 1.0)` adds an element to the material, with a specified mass fraction.
 
-`void add (GeoMaterial * material, double fraction)`  Adds a material to the material, with a specified mass fraction.  This is useful for combining precombined materials, such as argon + ethane.
+The method `add(GeoMaterial * material, double fraction)` adds a material to the material, with a specified mass fraction.  This is useful for combining precombined materials, such as argon + ethane.
 
-`void lock ()` Locks the material against further editing, and computes all derived quanties such as radiation length and interaction length.
+The method `lock()` Locks the material against further editing, and computes all derived quanties such as radiation length and interaction length.
 
-`std::string getName () const` Accesses the name of the material.
+The method `getName()` returns the name of the material as a string.
 
-`double getDensity () const` Returns the density of the material[^n1].
+The method `getDensity()` returns the density of the material[^gmat1].
 
-`unsigned int getID() const`  Returns the id of the material.  The id is generated automatically by counting instances of materials.
+The method `getID()` returns the *id* of the material as an integere.  The *id* is generated automatically by counting instances of materials.
 
-`unsigned int getNumElements () const`  Returns the number of elements in a material.
+The method `getNumElements()`  returns the number of elements in a material.
 
-`const GeoElement * getElement (unsigned int i) const` Returns a pointer to the ith element.
+The method `getElement(i)` returns a pointer to the $i^{th}$ element.
 
-`double getFraction (int i) const` Returns the fraction of the ith element.
+The method `getFraction(i)` returns the fraction of the $i^{th}$ element.
 
-`double getRadLength () const`  Returns the radiation length of the material, computed from the density, the list of constituents, and their properties.
+The method `getRadLength()` returns the radiation length of the material, computed from the density, the list of constituents, and their properties.
 
-`double getIntLength () const` Returns the interaction length of the material, computed from the density the list of constituents, and their properties.
+The method `getIntLength()` returns the interaction length of the material, computed from the density the list of constituents, and their properties.
 
 The following methods refer to ionization energy loss, specifically, the following formulation:
 
@@ -54,13 +54,15 @@ $$
 $$
 
 
-`double getDeDxConstant () const`  Returns the constant, $K$, which depends upon the material properties (mostly the density).
+The method `getDeDxConstant()` returns the constant, $K$, which depends upon the material properties (mostly the density).
 
-`double getDeDxI0 () const`  Returns the effective ionization potential $I_0$, which is a property of the material.
+While the method `getDeDxI0()` returns the effective ionization potential $I_0$, which is a property of the material.
 
-double getDeDxMin () const  Returns an approximation for the ionization of a minimum ionizing particle ($\beta\gamma=3.4$), given by: $K \times 11.528$.
+The method `getDeDxMin()` returns an approximation for the ionization of a minimum ionizing particle ($\beta\gamma=3.4$), given by: $K \times 11.528$.
 
 
 
 
-[^n1] The density is normally specified using CLHEP units.  The native unit of mass is the MeV, the native unit for length is the mm.  A material with a density of 1 g/cm3 has a density of 1.7 x 10-22, in these units.  
+[^gmat1]: The density is normally specified using `GeoModel` units, ported from CLHEP[^gmat2].  The native unit of mass is the MeV, the native unit for length is the mm.  A material with a density of 1 g/cm3 has a density of 1.7 x 10-22, in these units.  
+
+[^gmat2]: CLHEP - A Class Library for High Energy Physics,  <https://proj-clhep.web.cern.ch/proj-clhep/>
diff --git a/documentation/docs/components/kernel/reference/Shapes.md b/documentation/docs/components/kernel/reference/Shapes.md
index c3d96f5eb5ebece9d5a07d95efe959e08276342a..c13841d30b1c233e75876ea08bd516451a4c24cb 100644
--- a/documentation/docs/components/kernel/reference/Shapes.md
+++ b/documentation/docs/components/kernel/reference/Shapes.md
@@ -8,20 +8,38 @@
 The shape classes in the geometry kernel are data structures designed to describe several geometrical primitives. Table 1 describes the different shapes presently provided within the geometry kernel.  This set is extensible; one only needs to derive a new shape from the base class and insure that it fits the pattern described below. Shapes are reference-counted objects, as described in [Reference Counting](#reference-counting).
 
 
+In the table here below, a list of the existing geometrical shapes in the GeoModelKernel package is given:
+
+
 | Class   | Shape |
 | ------- | ----- |
-| GeoBox  | Box |
-| GeoCons | Cone Section |
-| GeoPara |Parallelepiped |
-| GeoPcon | Polycone |
-| GeoPgon | Polygon |
-| GeoTrap | Trapezoid  (complex) |
-| GeoTrd  | Trapezoid (simple) |
-| GeoTube | Tube |
-| GeoTubs | Tube Section |
-| GeoTwistedTrap | Twisted Trapezoid |
-
-Table 1: Existing geometrical shapes in the GeoModel kernel.
+| [GeoBox](#geobox)  | Box |
+| [GeoCons](#geocons) | Cone Section |
+| GeoEllipticalTube | |
+| GeoGenericTrap | |
+| [GeoPara](#geopara) |Parallelepiped |
+| [GeoPcon](#geopcon) | Polycone |
+| [GeoPgon](#geopgon) | Polygon |
+| GeoSimplePolygonBrep | |
+| GeoTessellatedSolid | |
+| GeoTorus | |
+| [GeoTrap](#geotrap) | Trapezoid  (complex) |
+| [GeoTrd](#geotrd)  | Trapezoid (simple) |
+| [GeoTube](#geotube) | Tube |
+| [GeoTubs](#geotubs) | Tube Section |
+| [GeoTwistedTrap](#geotwistedtrap) | Twisted Trapezoid |
+| GeoUnidentifiedShape | |
+
+
+In addition to the geometrical shapes listed above, a set of *boolean operator* shapes is also added:
+
+| Class   | Operation |
+| ------- | ----- |
+| GeoShapeIntersection | Intersection |
+| GeoShapeShift | Shift |
+| GeoShapeSubtraction | Subtraction |
+| GeoShapeUnion | Intersection |
+
 
 
 All shapes provide access to their geometry attributes (height, width, & cetera), and in addition perform several other services:
diff --git a/documentation/docs/components/kernel/reference/SubsystemDescription.md b/documentation/docs/components/kernel/reference/SubsystemDescription.md
new file mode 100644
index 0000000000000000000000000000000000000000..b49a701fd8a06fc87d85c91fd33a65d849caacc0
--- /dev/null
+++ b/documentation/docs/components/kernel/reference/SubsystemDescription.md
@@ -0,0 +1,87 @@
+
+
+## Base classes for subsystem description
+
+The geometry kernel contains three base classes for subsystem description.  These provide require a minimum amount of functionality from subclasses—just enough to function within a reasonable framework.  The classes are:  `GeoVDetectorElement`, an abstract base class for a separately-alignable piece of a detector subsystem,  `GeoVDetectorFactory`, an abstract base class for an algorithm which builds the geometry, including the detector elements and other pieces of nondescript support material, and a `GeoVDetectorManager`, which is stored in the transient detector store and provides access to the geometry, both material geometry and readout geometry. Both classes should be extended by subsystems people to provide a bona fide readout geometry interface. 
+
+The interfaces to these classes are shown here:
+
+
+### GeoVDetectorElement
+
+```cpp
+//== GeoVDetectorElement ==
+
+  // Constructor:
+  GeoVDetectorElement (const GeoVFullPhysVol * fullPhysVol)
+
+  // Public Methods:
+  const GeoVFullPhysVol * getMaterialGeom () const
+
+  // Virtual Public Methods to be overridden by subclasses:
+  Identifier identify() const;
+```
+
+The constructor for a `GeoVDetectorElement` requires a full physical volume, which should be unique and which should live under a unique branch.  This is how all detector elements know where they are.
+
+
+The `getMaterialGeom()` method provides access to the full physical volume.  This is mostly for subclasses to use, when they compute derived position information.
+
+The `identify()` method provides an identifier for the volume. 
+
+!!! note 
+
+    Note that the coupling to the actual identification scheme is loose because the `identify()` method is pure virtual and the `Identifier` class is forward-declared. 
+
+
+
+
+
+#### GeoVDetectorFactory
+
+```cpp
+//== GeoVDetectorFactory ==
+
+  // Constructor:
+  GeoVDetectorFactor()
+
+  // Virtual Public Methods to be overridden by subclasses:
+  void create (GeoPhysVol * world)
+  const GeoVDetectorManager *getDetectorManager() const;
+```
+
+`GeoVDetectorFactories` create geometry and map it into readout geometry.  For the simulation, access to the raw geometry is required.  The interface to `GeoVDetectorFactory` contains two pure virtual functions which must be implemented in the subclass.
+
+The method  `create (GeoPhysVol * world)` creates the material and readout geometry, and attaches the raw geometry to the physical volume tree, under the world volume, which is passed in from the calling routine.
+
+The method `getDetectorManager()` returns a detector manager, which contains all of the constructed geometry.  It is permissible to return a pointer to a subclass of GeoVDetectorManager (the so-called covariant return type mechanism).  This is proper C++ and the correct way of avoiding dynamic casting.
+
+
+
+#### GeoVDetectorManager
+
+
+```cpp 
+//== GeoVDetectorManager ==
+
+  // Constructor:
+  GeoVDetectorManager()
+
+  // Virtual Public Methods to be overridden by subclasses:
+  unsigned int getNumTreeTops () const
+  PVConstLink getTreeTop (unsigned int i) const
+```
+
+
+`GeoVDetectorManagers` hold the results of geometry construction and are stored in the transient detector store.  For the simulation, access to the raw geometry is required.  Experience has shown that subsystems cannot be cleanly implemented in terms of a single, top-level volume; instead several volumes must exist at the top level, for topological reasons, hence the iterative access to top level volumes, or tree-tops.  The interface to `GeoVDetectorManager` contains several pure virtual functions which must be implemented in the subclass.
+
+The method `getNumTreeTops()` returns the number of top-level physical volumes in the raw geometry for the subsystem.
+
+The method  `getTreeTop(unsigned int i)` returns the $i^{th}$ top-level physical volume for the subsystem.
+
+
+
+
+
+
+
diff --git a/documentation/docs/components/kernel/reference/index.md b/documentation/docs/components/kernel/reference/index.md
index 8b8638701fadfba01caf388de80080ba2bdfa6aa..3914f0ebd38ec659685ce16fce1d9b856323b4c1 100644
--- a/documentation/docs/components/kernel/reference/index.md
+++ b/documentation/docs/components/kernel/reference/index.md
@@ -21,6 +21,13 @@ Detailed descriptions of the geometry kernel classes follow.
 
 {% include 'components/kernel/reference/NameTags.md' %}
 
+{% include 'components/kernel/reference/Parametrization.md' %}
+
+{% include 'components/kernel/reference/Actions.md' %}
+
+{% include 'components/kernel/reference/SubsystemDescription.md' %}
+
+{% include 'components/kernel/reference/Appendix_Query.md' %}
 
 
 
diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml
index e00898600fcb362802c86d13a97cd0d3def3faa3..f29c2efb0d741b6ff1ceffdb89e1306a5507e82e 100755
--- a/documentation/mkdocs.yml
+++ b/documentation/mkdocs.yml
@@ -11,16 +11,17 @@ theme:
 
 nav:
     - Home: 'index.md'
-    #- Getting Started:
-    - 'Install Libraries & Tools': 'start/install.md'
-    #    - 'The Basic Concepts': 'start/basic_concepts.md'
-    #   - 'The Basic Building Blocks': 'start/basic_building_blocks.md'
-    #- How To:
-    #    - 'Build a basic geometry': 'how/how_basic_geo_cpp.md'
-    #    - 'Build a simple detector': 'how/how_simple_detector_cpp.md'
-    #    - 'Dump the geometry with `dump-geo`': 'how/how_dump_geo.md'
-    #    - 'Load a geometry from a file': 'how/how_load_geo.md'
-    #    - 'Describe a geometry with a file': 'how/how_describe_geo_file.md'
+    - Getting Started:
+        - 'Intro': 'start/index.md'
+        - 'Install Libraries & Tools': 'start/install.md'
+        - 'The Basic Concepts': 'start/basic_concepts.md'
+        - 'The Basic Building Blocks': 'start/basic_building_blocks.md'
+    - How To:
+        - 'Build a basic geometry': 'how/how_basic_geo_cpp.md'
+        - 'Build a simple detector': 'how/how_simple_detector_cpp.md'
+        - 'Dump the geometry with `dump-geo`': 'how/how_dump_geo.md'
+        - 'Load a geometry from a file': 'how/how_load_geo.md'
+        - 'Describe a geometry with a file': 'how/how_describe_geo_file.md'
     - GeoModel Components:
         - Kernel:
             - 'Overview': 'components/kernel/overview/index.md'
@@ -30,7 +31,7 @@ nav:
         - 'FullSimLight': 'fullsimlight/fullsimlight/index.md'
         - 'GeoModelClash': 'fullsimlight/gmclash/index.md'
         - 'GeoModelGeantino': 'fullsimlight/gmgeantino/index.md'
-        - 'GeoModel2GDML': 'fullsimlight/gm2gdml/index.md'
+        - 'GeoModelToGDML': 'fullsimlight/gmtogdml/index.md'
     - FAQ: 'faq.md'
     - For Developers:
         - 'Build the Libraries and Tools': 'dev/index.md'
@@ -50,6 +51,7 @@ extra_css:
     - material_nested_lists_rendering.css
 
 markdown_extensions:
+    - smarty                # to use 'SmartyPants' typography extensions as '---' for em-dashes
     - admonition            # to use notes, warnings, tips, ...
     - footnotes             # to set footnotes
     - pymdownx.superfences  
@@ -65,6 +67,7 @@ markdown_extensions:
         base_path: docs
     - pymdownx.arithmatex:  # to use LaTeX syntax in Markdown files
         generic: true
+    #- markdown.extensions.attr_list # to use custom css settings, e.g. {: .center}. Not used now
 
 plugins:
   - search