More updates on documentation

Update #110

doc/source/advanced/CMakeLists.txt

@@ -1,4 +1,5 @@
 set(SOURCES index.rst
+            user_data.rst
             io.rst
             cpp_datastructures.rst
             hdf5_handlers.rst

doc/source/advanced/cpp_datastructures.rst

@@ -1,8 +1,70 @@
+.. _advanced-cpp-datastructures:
+
 ============================
 C++ data structures and HDF5
 ============================
 
 .. todo::
 
     Add here some content about C++ data structures and about the principal
-    difficulties with them when working with HDF5.
+    difficulties with them when working with HDF5.
+
+The HDF5 library is a C-library and thus it is primarily intended to be 
+used with C-style data structures. These are 
+
+* simple scalar values of a primitive type
+* :cpp:any:`struct` instances
+* pointers and array of pointers. 
+
+C++ provides a far more richer set of data structures including for instances 
+classes. But also more elaborate compound types could be built in particular 
+when making use of STL containers. 
+
+STL containers
+==============
+
+Recall now the concept of the memory storage introduced in the users guide 
+(see :ref:`ug-design-overview` for details). Except for three situations 
+where which will be covered also in the advanced chapter of the 
+documentation HDF5 always assumes that the memory storage from which it 
+reads or to which it writes data is contiguous and can be adressed linearly. 
+The only two data structures in the STL which satisfy this requirement are the
+two templates
+
+* :cpp:class:`std::vector`
+* :cpp:class:`std::array`. 
+
+In this case the :cpp:func:`data` method provided by both templates would be 
+already sufficient for low level HDF5 IO as the pointer returned by this 
+method would reference a block of memory that entirely satisifies the 
+requirements for memory storage. 
+
+However, already defining a vector of vectors would make no longer be 
+compliant with a memor storage. Cnsider the following example 
+
+.. code-block:: cpp
+
+    using BinType    = unsigned int;
+    using MCAReadout = std::vector<BinType>;
+    using MCAStack = std::vector<MCAReadout>; 
+    
+    #define NBINS 1024
+    #define NMCAS 100
+    
+    using namespace hdf5;
+    
+    // create the dataset
+    node::Gruop data_group = ....;
+    auto file_type = datatype::create<BinType>;
+    dataspace::Simple file_space({NMCAS,NBINS})
+    node::Dataset dset = data_gruop.create_dataset("mcas",file_type,file_space);
+    
+    // create the data
+    MCAStack mcas;
+    MCAReader reader;
+    std::generate_n(std::back_inserter(mcas),NMCAS,reader);
+    
+   
+    //now lets try to write the data  
+    dset.write(mcas);
+    

doc/source/advanced/user_data.rst

@@ -0,0 +1,33 @@
+=======================
+User defined data types
+=======================
+
+At some point in time one may wants to write data from a user defined 
+data type. Namely we want to write data from a C++ class (typically the fields 
+stored as members of the class). 
+In this case we have to distinguish two situations
+
+* classes whose members are only POD types 
+* classes with STL containers, strings, or any other dynamic non-POD type. 
+
+The former case is simple the latter one rather complicated. In general, 
+what we have to do is that for every type which should be used in an 
+IO operation (a call to :cpp:func:`read` or :cpp:func:`write` of an 
+attribute or dataset) two things must be available
+
+* a dataspace trait
+* and a datatype trait
+
+Types with POD members only
+===========================
+
+As an example for this situation 
+
+
+
+Typs with non-trivial members
+=============================
+
+.. todo:: 
+
+   Need to handle this situation.

doc/source/users_guide/overview.rst

@@ -1,4 +1,4 @@
-.. _design-overview:
+.. _ug-design-overview:
 
 ===============
 Design overview