0027206: Inconsistent and obsolete information in persistence documentation and Relea... V7_0_0rc
authorabv <abv@opencascade.com>
Fri, 4 Mar 2016 11:42:53 +0000 (14:42 +0300)
committerabv <abv@opencascade.com>
Fri, 4 Mar 2016 12:03:05 +0000 (15:03 +0300)
Technical docs are reviewed to:
* update references to page with third-party products
* update description of persistence, handles, and RTTI according to changes in OCCT 7.0
* remove references to CDL, WOK, and WOK-generated stuff
* update the list of environment variables

14 files changed:
dox/dev_guides/building/3rdparty/3rdparty_linux.md
dox/dev_guides/building/3rdparty/3rdparty_osx.md
dox/dev_guides/building/3rdparty/3rdparty_windows.md
dox/dev_guides/contribution/coding_rules.md
dox/dev_guides/git_guide/git_guide.md
dox/dev_guides/tests/tests.md
dox/dev_guides/upgrade/upgrade.md
dox/overview/overview.md
dox/user_guides/foundation_classes/foundation_classes.md
dox/user_guides/modeling_data/modeling_data.md
dox/user_guides/ocaf/ocaf.md
dox/user_guides/shape_healing/shape_healing.md
dox/user_guides/step/step.md
dox/user_guides/tobj/tobj.md

index 61b3690..caa3ec0 100644 (file)
@@ -10,7 +10,7 @@ products used by Open CASCADE Technology and samples on Linux platform.
 
 The links for downloading the third-party products are available on the web site 
 of OPEN CASCADE SAS at 
-http://www.opencascade.org/getocc/require/. 
+http://www.opencascade.com/content/3rd-party-components. 
 
 There are two types of third-party products, which are  necessary to build OCCT: 
   
index 30fb99f..0a5ef6e 100644 (file)
@@ -8,8 +8,7 @@ This document presents additional guidelines for building third-party products
 used by Open CASCADE Technology and samples on Mac OS X platform (10.6.4  and later). 
 
 The links for downloading the third-party products are available 
-on the web site of OPEN CASCADE SAS at 
-http://www.opencascade.org/getocc/require/</a>. 
+on the web site of OPEN CASCADE SAS at http://www.opencascade.com/content/3rd-party-components. 
 
 There are two types of third-party products, which are  necessary to build OCCT: 
   
index 69a0697..3bbed48 100644 (file)
@@ -8,7 +8,9 @@ This document presents guidelines for building third-party products used by Open
 
 You need to use the same version of MS Visual Studio for building all third-party products and OCCT itself, in order to receive a consistent set of run-time binaries. 
 
-The links for downloading the third-party products are available on the web site of OPEN CASCADE SAS at http://www.opencascade.org/getocc/require/. There are two types of third-party products used  by OCCT: 
+The links for downloading the third-party products are available on the web site of OPEN CASCADE SAS at http://www.opencascade.com/content/3rd-party-components.
+
+There are two types of third-party products used  by OCCT: 
 
 * Mandatory  products: 
        * Tcl/Tk 8.5 -- 8.6;
index e9426f7..999726f 100644 (file)
@@ -36,7 +36,6 @@ Open CASCADE Technology is an open source platform available for an internationa
 Names should be meaningful or, at least, contain a meaningful part. To better understand this requirement, let us examine the existing names of toolkits, packages, classes and methods:
 - Packages containing words *Geom* or *Geom2d* in their names are related to geometrical data and operations.
 - Packages containing words *TopoDS* or *BRep* in their names are related to topological data and operations.
-- In OCAF, packages that define transient, persistent data classes and drivers to map between them, have similar names prefixed by *T*, *P*, and *M* correspondingly (e.g. *TDocStd*, *PDocStd*, *MDocStd*).
 - Packages ending with <i>...Test</i> define Draw Harness plugins.
 - Methods starting with *Get...* and *Set...* are usually responsible for correspondingly retrieving and storing data.
 
@@ -67,10 +66,9 @@ Names of units should not contain underscores, unless the use of underscores is
 
 The following extensions should be used for source files, depending on their type:
 
-* <i>.cdl</i> -- CDL declaration files
 * <i>.cxx</i> -- C++ source files
 * <i>.hxx</i> -- C++ header files
-* <i>.lxx</i> -- headers with definitions of inline methods (CDL packages)
+* <i>.lxx</i> -- additional headers containing definitions of inline methods and auxiliary code
 
 ### Prefix for toolkit names [MANDATORY]
 
index de5a9ee..aaec0e6 100644 (file)
@@ -265,8 +265,7 @@ Click **Save** to input the key to the system.
 
   * Create a new branch for your development, basing on the selected version of the sources 
    (usually the current master) and switch your working copy to it
-  * Develop and test your change. Note that for the first time, and after any changes 
-   made in CDL files you will have to re-generate build scripts or Visual Studio projects using WOK. 
+  * Develop and test your change.
   * Do as many commits in your branch as you feel convenient; 
    the general recommendation is to commit every stable state (even incomplete), to record the history of your development.
   * Push your branch to the repository when your development is complete or when you need to share it with other people (e.g. for review)
index 2828463..f5bcc3d 100644 (file)
@@ -23,7 +23,8 @@ The tests are organized in three levels:
   
 See @ref testmanual_5_1 "Test Groups" chapter for the current list of available test groups and grids.
 
-Some tests involve data files (typically CAD models) which are located separately and are not included with OCCT code. The archive with publicly available test data files should be downloaded and installed independently on OCCT sources (see http://dev.opencascade.org).
+@note Many tests involve data files (typically CAD models) which are located separately and (except a few) are not included with OCCT code. 
+These tests will be skipped if data files are not available.
 
 @subsection testmanual_1_2 Intended Use of Automatic Tests
 
index 4438f3a..4a9f48d 100644 (file)
@@ -50,7 +50,7 @@ for (Standard_Integer aGr = 1; aGr <= aLen; ++aGr)
 ~~~~
 
 * All occurrences of *Select3D_Projector* in the application code (if any) should be replaced with *Handle(Select3D_Projector)*.
-* The code of inheritors of *Select3D_SensitiveEntity* should be updated if they override <i>::Matches()</i> (this is probable, if clipping planes are used).
+* The code of inheritors of *Select3D_SensitiveEntity* should be updated if they override <i>Matches()</i> (this is probable, if clipping planes are used).
 * Constructor for *V3d_Plane* has been changed, so the extra argument should be removed if used in the application. It is necessary to add a new plane using method *V3d_Viewer::AddPlane()* if *V3d_Viewer* has been used to manage clipping planes list (this does not affect clipping planes representation). Please, have a look at the source code for new DRAWEXE *vclipplane* command in *ViewerTest_ObjectsCommands.cxx, VClipPlane* to see how clipping planes can be managed in the application.
 
 @section upgrade_652 Upgrade to OCCT 6.5.2
@@ -68,7 +68,7 @@ Handle(BRepMesh_DiscretRoot) aMeshAlgo = BRepMesh_DiscretFactory::Get().Discret
 ~~~~
 
 * The default state of *BRepMesh* parallelization has been turned off. The user should switch this flag explicitly:
-    *  by using methods *BRepMesh_IncrementalMesh::SetParallel(Standard_True)* for each *BRepMesh_IncrementalMesh* instance before <i>::Preform()</i>;
+    *  by using methods *BRepMesh_IncrementalMesh::SetParallel(Standard_True)* for each *BRepMesh_IncrementalMesh* instance before <i>Perform()</i>;
     *  by calling *BRepMesh_IncrementalMesh::SetParallelDefault(Standard_True)* when *BRepMesh_DiscretFactory* is used to retrieve the meshing tool (this also affects auto-triangulation in *AIS*).
 
 @section upgrade_653 Upgrade to OCCT 6.5.3
@@ -79,7 +79,7 @@ Porting of user applications from an earlier OCCT version to version 6.5.3 requi
 * The applications that might have used internal functions provided by *TKOpenGl* or removed primitives will need to be updated.
 * In connection with the implementation of Z-layers it might be necessary to revise the application code or revise the custom direct descendant classes of *Graphic3d_GraphicDriver* and *Graphic3d_StructureManager* to use the Z-layer feature.
 * Global variables *Standard_PI* and *PI* have been eliminated (use macro *M_PI* instead). 
-* Method *HashCode()* has been removed from class *Standard_Transient*. It is advisable to use global function <i>::HashCode()</i> for Handle objects instead. 
+* Method *HashCode()* has been removed from class *Standard_Transient*. It is advisable to use global function <i>HashCode()</i> for Handle objects instead. 
 * Declaration of operators new/delete for classes has become consistent and is encapsulated in macros.
 * Memory management has been changed to use standard heap <i>(MMGT_OPT=0)</i> and reentrant mode <i>(MMGT_REENTRANT=1)</i> by default.
 * Map classes in *NCollection* package now accept one more argument defining a hash tool.
@@ -299,10 +299,10 @@ SelectBasics_PickResult (aDepth, theMgr.DistToGeometryCenter (myCenter3d));
 ~~~~
 
 The interface of *SelectBasics_SensitiveEntity* now contains four new pure virtual functions that should be implemented by each custom sensitive:
-* <i>::BoundingBox()</i> – returns a bounding box of the entity;
-* <i>::Clear()</i> – clears up all the resources and memory allocated for complex sensitive entities;
-* <i>::BVH()</i> – builds a BVH tree for complex sensitive entities, if it is needed;
-* <i>::NbSubElements()</i> – returns atomic sub-entities of a complex sensitive entity, which will be used as primitives for BVH building. If the entity is simple and no BVH is required, this method returns 1.
+* <i>BoundingBox()</i> – returns a bounding box of the entity;
+* <i>Clear()</i> – clears up all the resources and memory allocated for complex sensitive entities;
+* <i>BVH()</i> – builds a BVH tree for complex sensitive entities, if it is needed;
+* <i>NbSubElements()</i> – returns atomic sub-entities of a complex sensitive entity, which will be used as primitives for BVH building. If the entity is simple and no BVH is required, this method returns 1.
 
 Each sensitive entity now has its own tolerance, which can be overridden by method *SelectBasics_SensitiveEntity::SetSensitivityFactor()* called from constructor.
 
@@ -321,10 +321,12 @@ Porting of user applications from an earlier OCCT version to version 7.0.0 requi
 
 @subsection upgrade_700_persist Removal of legacy persistence
 
-Legacy persistence for shapes and OCAF data based on *Storage_Schema* (toolkits *TKShapeShcema, TLStdLSchema, TKStdSchema* and *TKXCAFSchema*) has been removed in OCCT 7.0.0.
+Legacy persistence for shapes and OCAF data based on *Storage_Schema* (toolkits *TKPShape*, *TKPLCAF*, *TKPCAF*, *TKShapeShcema, TLStdLSchema, TKStdSchema*, and *TKXCAFSchema*) has been removed in OCCT 7.0.0.
 The applications that used these data persistence tools need to be updated to use other persistence mechanisms.
 
-The existing data files in standard formats can be converted using OCCT 6.9.0 or a previous version, as follows.
+@note For compatibility with previous versions, possibility to read standard OCAF data (TKLCAF, TKCAF) from the files stored in old format is preserved (toolkits *TKStdL*, *TKStd*).
+
+The existing data files in standard formats can be converted using OCCT 6.9.1 or a previous version, as follows.
 
 #### CSFDB files
 
@@ -340,7 +342,8 @@ The easiest way to do that is to use ImportExport sample provided with OCCT 6.9.
 #### OCAF and XCAF documents
 
 Files containing OCAF data saved in the old format usually have extensions <i>.std, .sgd</i> or <i>.dxc</i> (XDE documents).
-These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands available in OCCT 6.9.0 or earlier.
+These files can be converted to XML or binary OCAF formats using DRAW Test Harness commands.
+Note that if the file contains only attributes defined in TKLCAF and TKCAF, this action can be performed in OCCT 7.0; otherwise OCCT 6.9.1 or earlier should be used.
 
 For that, start *DRAWEXE* and perform the following commands: 
 
@@ -512,7 +515,7 @@ Handle(Geom_TrimmedCurve) aCurve = new Geom_TrimmedCurve (...);
 func (aCurve); // ambiguity error in VC++ 10
 ~~~~~
 
-Note that this problem does not appear if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
+Note that this problem can be avoided in many cases if macro *OCCT_HANDLE_NOCAST* is used, see @ref upgrade_occt700_cdl_nocast "below".
 
 To resolve this ambiguity, change your code so that argument type should correspond exactly to the function signature. 
 In some cases this can be done by using the relevant type for the corresponding variable, like in the example above:
index 4d3b578..8a647b9 100644 (file)
@@ -107,9 +107,6 @@ Threading Building Blocks is not just a threads-replacement library. It represen
 abstracts platform details and threading mechanisms for scalability and performance. 
 TBB is available under GPLv2 license with the runtime exception.
 
-Open CASCADE Technology WOK module on Windows also makes use of LGPL-licensed C routines **regexp** 
-and **getopt**, taken from GNU C library.
-
 **OpenGL** is an industry standard API for 3D graphics used by OCCT for 
 implementation of 3D viewer. OpenGL specification is developed by the
 Khronos group, http://www.khronos.org/opengl/. OCCT code includes header 
@@ -299,8 +296,7 @@ The contents of the OCCT-7.0.0 directory (called further "OCCT root", or $CASROO
   * **data**  This folder contains CAD files in different formats, which can be used to test the OCCT functionality;
   * **doc**  This folder contains OCCT documentation in HTML and PDF format;
   * **dox**  This folder contains sources of OCCT documentation in plain text (MarkDown) format;
-  * **drv**  This folder contains source files generated by WOK (private header files and instantiations of generic classes);
-  * **inc**  This folder contains all OCCT header files;
+  * **inc**  This folder contains copies of all OCCT header files;
   * **samples**  This folder contains sample applications.
   * **src**  This folder contains OCCT source files. They are organized in folders, one per development unit;
   * **tests**  This folder contains scripts for OCCT testing.
@@ -341,7 +337,7 @@ The scripts are located in the OCCT root folder.
   * **MMGT_OPT** (optional) if set to 1, the memory manager performs optimizations as described below; if set to 2, 
     Intel (R) TBB optimized memory manager is used; if 0 (default), every memory block is allocated 
     in C memory heap directly (via malloc() and free() functions). 
-    In the latter case, all other options except MMGT_CLEAR are ignored;
+    In the latter case, all other options starting with *MMGT*, except MMGT_CLEAR, are ignored;
   * **MMGT_CLEAR** (optional) if set to 1 (default), every allocated memory block is cleared by zeros; 
     if set to 0, memory block is returned as it is;
   * **MMGT_CELLSIZE** (optional) defines the maximal size of blocks allocated in large pools of memory. Default is 200;
@@ -352,21 +348,18 @@ The scripts are located in the OCCT root folder.
   * **MMGT_MMAP** (optional) when set to 1 (default), large memory blocks are allocated using 
     memory mapping functions of the operating system; if set to 0, 
     they will be allocated in the C heap by malloc();
-  * **CSF_LANGUAGE** is required to define the default language of messages;
+  * **CSF_LANGUAGE** (optional) defines default language of messages;
   * **CSF_DEBUG** (optional, Windows only): if defined then a diagnostic message is displayed in case of an exception;
   * **CSF_DEBUG_BOP** (optional): if defined then it should specify directory where diagnostic data on problems occured in Boolean operations will be saved;
   * **CSF_MDTVTexturesDirectory** defines the directory for available textures when using texture mapping;
-  * **CSF_ShadersDirectory** defines the directory for GLSL programs (required for advanced rendering techniques and custom shaders);
-  * **CSF_UnitsDefinition** and **CSF_UnitsLexicon** should define paths to resource files Lexi_Expr.dat and Units.dat, respectively, required for support of measurement units;
-  * **CSF_SHMessage** is required in order to define the path to the messages file for *ShapeHealing*;
-  * **CSF_XSMessage** is required in order to define the path to the messages file for **STEP** and **IGES** translators;
-  * **CSF_StandardDefaults** and **CSF_PluginDefaults** are required in order to maintain CASCADE Persistence mechanism to make possible any open/save operations with OCAF documents;
-  * **CSF_StandardLiteDefaults** is required in order to maintain *OCCT Persistence mechanism* to make possible any open/save operations with Lite OCAF documents;
-  * **CSF_XCAFDefaults**  any open/save operations for **XDE** documents;
-  * **CSF_IGESDefaults** and **CSF_STEPDefaults** are required for **IGES** and **STEP** translators correspondingly in order to define the path to the resource files;
+  * **CSF_ShadersDirectory** defines the directory for GLSL programs (required for 3D viewer to work);
+  * **CSF_UnitsDefinition** and **CSF_UnitsLexicon** should define paths to resource files Lexi_Expr.dat and Units.dat, respectively (required for support of measurement units);
+  * **CSF_SHMessage** defines the path to the messages file for *ShapeHealing*;
+  * **CSF_XSMessage** defines the path to the messages file for **STEP** and **IGES** translators;
+  * **CSF_StandardDefaults**, **CSF_StandardLiteDefaults*, **CSF_XCAFDefaults**, and **CSF_PluginDefaults** define paths to directory where configuration files for OCAF persistence are located (required for open/save operations with OCAF documents);
+  * **CSF_IGESDefaults** and **CSF_STEPDefaults** (optional) define paths to directory where resource files of **IGES** and **STEP** translators are located;
   * **CSF_XmlOcafResource** is required in order to set the path to **XSD** resources, which defines XML grammar.
   * **CSF_MIGRATION_TYPES** is required in order to read documents that contain old data types, such as *TDataStd_Shape*;
-  * **TCLLIBPATH**, **TCL_LIBRARY**, **TK_LIBRARY** and **TIX_LIBRARY** are required to allow work with **DRAW** and **WOK**.
 
 @section OCCT_OVW_SECTION_7 Getting Started
 
index edceb82..977892d 100644 (file)
@@ -124,38 +124,8 @@ The fundamental software component in object-oriented software  development is t
 
 Classes fall into three categories: 
 * Ordinary classes.
-* Deferred classes. A **deferred class** cannot be instantiated. The purpose  of having such classes is to have a given behavior shared by a hierarchy of  classes and dependent on the implementation of the descendants. This is a way  of guaranteeing a certain base of inherited behavior common to all the classes  based on a particular deferred class. The C++ equivalent of a deferred CDL  class is an abstract class. 
-* Generic classes. A **generic class** offers a set of functional behaviors  to manipulate other data types. Instantiation of a generic class requires that  a data type is given for its argument(s). The generic classes in CDL perform  the same mission as template classes in C++.
-  
-@subsubsection occt_fcug_2_a_4 Generic Classes 
-Generic classes are implemented in two steps. First you  declare the generic class to establish the model, then you instantiate this  class by giving information about the generic types. 
-
-#### Declaring a Generic Class
-
-The generic classes in Open CASCADE Technology are similar  by their intent to C++ templates with explicit instantiation. 
-A generic class is declared in CDL as operating on data  items of non-fixed types which are declared as arguments of the generic class.  It is possible to put a restriction on these data types to be of subtype of  some definite class. Definition of the generic class does not create new class  type in C++ terms; it only defines a pattern for generation (instantiation) of  the real classes.
-#### Instantiation of a Generic Class
-
-When a generic class is instantiated, its argument types are  substituted by actually existing data types (elementary types or classes). The  result of instantiation is a new C++ class with an arbitrary name (specified in  the instantiating declaration). By convention, the name of the instantiated class  is usually constructed from the name of the generic class and names of actual  argument types. As for any other class, the name of the class instantiating a generic  type is prefixed by the name of the package in which instantiation is declared. 
-@code
-class Array1OfReal instantiates Array1 from TCollection  (Real);
-@endcode
-
-This declaration located in a CDL file of the *TColStd*  package defines a new C++ class *TColStd_Array1OfReal* as the instantiation of  generic class *TCollection_Array1* for *Real* values. 
-More than one class can be instantiated from the same  generic class with the same argument types. Such classes will be identical by  implementation, but considered as two different classes by C++.  
-No class can inherit from a generic class. 
-A generic class can be a deferred class. A generic class can  also accept a deferred class as its argument. In both these cases, any class  instantiated from it will also be deferred. The resulting class can then be  inherited by another class. 
-
-#### Nested Generic Classes
-
-It often happens that many classes are linked by a common  generic type. This is the case when a base structure furnishes an iterator. In  this context, it is necessary to make sure that the group of linked generic  classes is indeed instantiated for the same type of object. In order to group  the instantiation, you may declare certain classes as being nested. 
-When generic class is instantiated, its nested classes are  instantiated as well. The name of the instantiation of the nested class is  constructed from the name of that nested class and name of the main generic  class, connected by ‘Of’. 
-@code
-class MapOfReal instantiates Map from TCollection  (Real,MapRealHasher);
-@endcode
-This declaration in *TColStd* defines not only class  *TColStd_MapOfReal*, but also class *TColStd_MapIteratorOfMapOfReal*, which is  instantiated from nested class *MapIterator* of the generic class  *TCollection_Map*. Note that instantiation of the nested class is separate class,  it is not nested class to the instantiation of the main class. 
-**Nested classes**, even though they are described as  non-generic classes, are generic by construction being inside the class they  are a member of. 
+* Abstract classes. An **abstract class** cannot be instantiated. The purpose  of having such classes is to have a given behavior shared by a hierarchy of  classes and dependent on the implementation of the descendants. This is a way  of guaranteeing a certain base of inherited behavior common to all the classes  based on a particular deferred class. 
+* Template classes. A **template class** offers a set of functional behaviors  to manipulate other data types. Instantiation of a template class requires that  a data type is given for its argument(s).
 
 @subsubsection occt_fcug_2_a_5 Inheritance
 The purpose of inheritance is to reduce the development  workload. The inheritance mechanism allows a new class to be declared already  containing the characteristics of an existing class. This new class can then be  rapidly specialized for the task in hand. This avoids the necessity of  developing each component “from scratch”. 
@@ -163,16 +133,7 @@ For example, having already developed a class *BankAccount* you  could quickly s
 
 The corollary of this is that when two or more classes  inherit from a parent (or ancestor) class, all these classes guarantee as a  minimum the behavior of their parent (or ancestor). For example, if the parent  class BankAccount contains the method Print which tells it to print itself out,  then all its descendant classes guarantee to offer the same service. 
 
-One way of ensuring the use of inheritance is to declare  classes at the top of a hierarchy as being **deferred**. In such classes,  the methods are not implemented. This forces the user to create a new class  which redefines the methods. This is a way of guaranteeing a certain minimum of  behavior among descendant classes. 
-
-@subsection occt_fcug_2_b Persistence  and Data Schema
-The data schema is the structure used by an application to  store its data. Data schemas consist of persistent classes. 
-
-An object is called **persistent** if it can be  permanently stored. Thus, the object can be reused at a later date by the  application, which created it, or by another application.
-In order for an object to be persistent for CDL, its type  must be declared as inheriting from the class *Standard_Persistent* or have a  parent class inheriting from the *Standard_Persistent* class. Note that classes  inheriting from *Standard_Persistent* are handled by a reference. 
-
-Objects instantiated from classes which inherit from the  Standard_Storable class cannot themselves be stored individually, but they can  be stored as fields of an object which inherits from *Standard_Persistent*. Note  that objects inheriting from *Standard_Storable* are handled by a value. 
+One way of ensuring the use of inheritance is to declare  classes at the top of a hierarchy as being **abstract**. In such classes,  the methods are not implemented. This forces the user to create a new class  which redefines the methods. This is a way of guaranteeing a certain minimum of  behavior among descendant classes. 
 
 @subsection occt_fcug_2_1 Data Types
 
@@ -203,19 +164,17 @@ In Open CASCADE Technology, the  Handles are specific classes that are used to s
 @subsubsection occt_fcug_2_1_1 Primitive Types
 
 The primitive types are predefined in the language and they  are **manipulated by value**. 
-Some of these primitives inherit from the **Storable** class.  This means they can be used in the implementation of persistent objects, either  contained in entities declared within the methods of the object, or they form  part of the internal representation of the object. 
 
-The primitives inheriting from *Standard_Storable* are the  following: 
 * **Boolean** is used to represent logical  data. It may have only two values: *Standard_True*  and *Standard_False*. 
 * **Character** designates any ASCII  character. 
 * **ExtCharacter** is an extended character. 
 * **Integer** is a whole number. 
 * **Real** denotes  a real number (i.e. one with whole and a fractional part, either of which may  be null). 
 * **ShortReal** is a real with a smaller choice of  values and memory size. 
-There are also non-Storable primitives. They are: 
 * **CString** is used for literal  constants. 
 * **ExtString** is an extended string. 
 * **Address** represents a byte address of  undetermined size. 
+
 The services offered by each of these types are described in  the **Standard** Package. 
 The table below presents the equivalence existing between  C++ fundamental types and OCCT primitive types. 
 
@@ -251,31 +210,21 @@ The table below presents the equivalence existing between  C++ fundamental types
 There are three categories of types which are manipulated by  value: 
   * Primitive types
   * Enumerated types
-  * Types defined by classes not inheriting from *Standard_Persistent* or *Standard_Transient*, whether directly or not.
+  * Types defined by classes not inheriting from *Standard_Transient*, whether directly or not.
 Types which are manipulated by value behave in a more direct  fashion than those manipulated by handle and thus can be expected to perform  operations faster, but they cannot be stored independently in a file. 
 
 @image html /user_guides/foundation_classes/images/foundation_classes_image005.png   "Manipulation of a data type by value"
 @image latex /user_guides/foundation_classes/images/foundation_classes_image005.png   "Manipulation of a data type by value"
 
-Types that are known to the schema (i.e. they are either **primitives** or they inherit from *Storable*) and are manipulated by value, can be  stored inside a persistent object as part of the representation. Only in this  way can a “manipulated by value” object be stored in a file. 
-
 @subsubsection occt_fcug_2_1_3 Types manipulated by reference (handle)
-There are two categories of types which are manipulated by  handle: 
-  * Types defined by classes inheriting from the *Persistent* class,  which are therefore storable in a file.
-  * Types defined by classes inheriting from the *Transient* class.
+
+These are types defined by classes inheriting from the *Transient* class.
   
 @image html /user_guides/foundation_classes/images/foundation_classes_image006.png   "Manipulation of a data type by reference"
 @image latex /user_guides/foundation_classes/images/foundation_classes_image006.png   "Manipulation of a data type by reference"
   
 @subsubsection occt_fcug_2_1_4 When is it necessary to use a handle?
 
-The following table summarizes how various data types are handled and stored.
-
-| Type        | Manipulated by handle | Manipulated by value |
-| :------- | :-------------------- | :-------------------- |
-| storable |     Persistent    | Primitive, Storable (if nested in a persistent class)|
-|temporary | Transient | Other |
-
 When you design an object, it can be difficult to choose how to manipulate that
 object: by value or by handle. The following ideas can help you to make up your mind: 
 
@@ -296,21 +245,27 @@ global variable.
 
 @subsubsection occt_fcug_2_2_1 Handle Definition
 
-A handle may be compared with a C++ pointer. Several handles  can reference the same object. Also, a single handle may reference several  objects, but only one at a time. To have access to the object it refers to, the  handle must be de-referenced just as with a C++ pointer. 
-
-Transient and Persistent classes may be manipulated either  with handles or with values. Handles which reference non-persistent objects are  called non-storable handles; therefore, a persistent object cannot contain a  non-storable handle.  
+A handle is OCCT implementation of a smart pointer.
+Several handles  can reference the same object.
+Also, a single handle may reference several  objects, but only one at a time.
+To have access to the object it refers to, the  handle must be de-referenced just as with a C++ pointer. 
 
 #### Organization of Classes
 
-Classes used with handles are persistent or transient. 
-
-Classes that inherit from *Standard_Transient*  are transient while classes that inherit from *Standard_Persistent*  are persistent. 
-
-In this chapter we will discuss only transient classes and  relevant handles. Persistent classes and their handles are organized in a similar  manner. 
-
 Class *Standard_Transient* is a root of a big hierarchy of OCCT  classes that are said to be operable by handles. It provides a reference  counter field, inherited by all its descendant classes, that is used by  associated *Handle()* classes to track a number of handles pointing to this  instance of the object. 
 
-For every class derived (directly or indirectly) from *Transient*, CDL extractor creates associated class *Handle()* whose name is the  same as the name of that class prefixed by *Handle_*. Open CASCADE Technology  provides preprocessor macro *Handle()* that produces a name of a *Handle()* class  for a given transient class name. 
+Objects of classes derived (directly or indirectly) from *Transient*, are normally allocated in dynamic memory using operator **new**, and manipulated by handle.
+Handle is defined as template class *opencascade::handle<>*.
+Open CASCADE Technology  provides preprocessor macro *Handle()* that is historically used throughout OCCT code to name a handle:
+~~~~~{.cpp}
+Handle(Geom_Line) aLine; // "Handle(Geom_Line)" is expanded to "opencascade::handleL<Geom_Line>"
+~~~~~
+
+In addition, for standard OCCT classes additional typedef is defined for a handle, as name of a class prefixed by *Handle_*.
+For instance, above example can be also coded as:
+~~~~~{.cpp}
+Handle_Geom_Line aLine; // "Handle_Geom_Line" is typedef to "opencascade::handleL<Geom_Line>"
+~~~~~
 
 #### Using a Handle
 
@@ -329,17 +284,61 @@ To initialize a handle, either a new object should be  created or the value of a
 
 @subsubsection occt_fcug_2_2_2 Type Management
 
-Open CASCADE Technology provides a means to describe the hierarchy  of data types in a generic way, with a possibility to check the exact type of  the given object at run-time (similarly to C++ RTTI). For every class type  derived from *Standard_Transient*, CDL extractor creates a code instantiating single  instance of the class *Standard_Type* (type descriptor) that holds information on  that type: its name and list of ancestor types. 
+Open CASCADE Technology provides a means to describe the hierarchy  of data types in a generic way, with a possibility to check the exact type of  the given object at run-time (similarly to C++ RTTI). 
+
+To enable this feature, a class declaration should include declaration of OCCT RTTI.
+Header *Standard_Type.hxx* provides two variants of preprocessor macros facilitating this:
+
+* Inline variant, declares and defines RTTI methods by single line of code:
+~~~~~{.cpp}
+#include <Geom_Surface.hxx>
+class Appli_ExtSurface : public Geom_Surface
+{
+. . .
+public:
+  DEFINE_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
+};
+~~~~~
+
+* Out-of line variant, using one macros in declaration (normally put in header file), and another for implementation (to be put in C++ source):
+
+  In *Appli_ExtSurface.hxx* file:
+~~~~~{.cpp}
+#include <Geom_Surface.hxx>
+class Appli_ExtSurface : public Geom_Surface
+{
+. . .
+public:
+  DEFINE_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
+};
+~~~~~
+
+   In *Appli_ExtSurface.cxx* file:
+~~~~~{.cpp}
+#include <Appli_ExtSurface.hxx>
+IMPLEMENT_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
+~~~~~
+
+These macros define method *DynamicType()* that returns a type descriptor - handle to singleton instance of the class *Standard_Type* describing the class.
+Type descriptor stores name of the class and descriptor of its parent class.
 
-That instance (actually, a handle on it) is returned by the  virtual method *DynamicType()* of the class derived from *Standard_Transient*. The  other virtual method *IsKind()* provides a means to check whether a given object  has specified type or inherits it. 
+Note that while inline version is easier to use, for widely used classes this method may lead to bloating of binary code of dependent libraries, due to multiple instantiations of inline method.
 
-In order to refer to the type descriptor object for a given  class type, use macros *STANDARD_TYPE()* with argument being a name of the class. 
+To get the type descriptor for a given class type, use macros *STANDARD_TYPE()* with name of the class as argument.
+
+Example of usage:
+~~~~~{.cpp}
+if (aCurve->IsKind(STANDARD_TYPE(Geom_Line))) // equivalent to "if (dynamic_cast<Geom_Line>(aCurve.get()) != 0)"
+{
+...
+}
+~~~~~
 
 #### Type Conformity
 
 The type used in the declaration of a handle is the static  type of the object, the type seen by the compiler. A handle can reference an  object instantiated from a subclass of its static type. Thus, the dynamic type  of an object (also called the actual type of an object) can be a descendant of  the type which appears in the handle declaration through which it is  manipulated. 
 
-Consider the persistent class *CartesianPoint*, a  sub-class of *Point*; the rule of type conformity can be illustrated as  follows: 
+Consider the class *CartesianPoint*, a  sub-class of *Point*; the rule of type conformity can be illustrated as  follows: 
 
 ~~~~~
 Handle (Geom_Point) p1;
@@ -418,7 +417,7 @@ p = new Geom_CartesianPoint (0, 0, 0);
 Unlike for a pointer, the **delete** operator does not  work on a handle; the referenced object is automatically destroyed when no  longer in use. 
 
 @subsubsection occt_fcug_2_2_4 Invoking Methods
-Once you have a handle on a persistent or transient object,  you can use it like a pointer in C++. To invoke a method which acts on the  referenced object, you translate this method by the standard *arrow* operator, or  alternatively, by function call syntax when this is available. 
+Once you have a handle to an object,  you can use it like a pointer in C++. To invoke a method which acts on the  referenced object, you translate this method by the standard *arrow* operator, or  alternatively, by function call syntax when this is available. 
 
 To test or to modify the state of the handle, the method is  translated by the *dot* operator. 
 The example below illustrates how to access the coordinates  of an (optionally initialized) point object: 
@@ -508,123 +507,6 @@ There are two approaches how to avoid such situation:
   * Use C++ pointer for one kind of references, e.g. from a primitive  to the graph
   * Nullify one set of handles (e.g. handles to a graph in  primitives) when a graph object needs to be destroyed
   
-@subsubsection occt_fcug_2_2_7 Creating  Transient Classes without CDL
-
-Though generation of Handle class and related C++ code is  normally performed by CDL extractor, it is also possible to define a class managed  by handle without CDL. To facilitate that, several macros are provided in the  file Standard_DefineHandle.hxx: 
-
-* **DEFINE_STANDARD_HANDLE(class_name,ancestor_name)** -- declares Handle class  for a class *class_name* that inherits class *ancestor_name* (for  instance, *Standard_Transient*). This macro should be put in a header file; the  declaration of the handle to a base class must be available (usually put before  or after the declaration of the class *class_name*, or into a separate  header file).  
-* **IMPLEMENT_STANDARD_HANDLE(class_name,ancestor_name)** -- implements method  *DownCast()* of the *Handle* class. Should be located in a C++ file (normally the  file where methods of the class *class_name* are implemented). 
-* **DEFINE_STANDARD_RTTI(class_name)** -- declares methods required for  RTTI in the class *class_name* declaration; should be in public: section. 
-* **IMPLEMENT_STANDARD_RTTIEXT(class_name,ancestor_name)** -- implements above methods. Usually  put into the C++ file implementing class *class_name*. 
-Note that it is important to ensure correctness of macro  arguments, especially the ancestor name, otherwise the definition may be  inconsistent (no compiler warnings will be issued in case of mistake). 
-
-In *Appli_ExtSurface.hxx* file:
-~~~~~
-#include <Geom_Surface.hxx>
-class Appli_ExtSurface : public Geom_Surface
-{
-. . .
-public:
-  DEFINE_STANDARD_RTTI(Appli_ExtSurface)
-}
-DEFINE_STANDARD_HANDLE(Appli_ExtSurface,Geom_Surface)
-~~~~~
-
-In *Appli_ExtSurface.cxx* file:
-~~~~~
-#include <Appli_ExtSurface.hxx>
-IMPLEMENT_STANDARD_HANDLE(Appli_ExtSurface,Geom_Surface)
-IMPLEMENT_STANDARD_RTTIEXT(Appli_ExtSurface,Geom_Surface)
-~~~~~
-
-#### Example
-
-The following example shows how to define a class <i> SamplePoint </i> manipulated by handle.
-
-First you need to define *Sample_Point.hxx* :
-
-~~~~
-
-    #ifndef _Sample_Point_HeaderFile
-    #define _Sample_Point_HeaderFile
-    #ifndef _Standard_Macro_HeaderFile
-    #include <Standard_Macro.hxx>
-    #endif
-    #include <MMgt_TShared.hxx>
-    #include <Standard_DefineHandle.hxx>
-    // Handle definition
-    //
-
-    DEFINE_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
-    class Sample_Point: public MMgt_TShared {
-    public:
-    Sample_Point();
-    Sample_Point(const Standard_Real, const
-    Standard_Real);
-    void SetX(const Standard_Real x) {
-    myX = x;
-    }
-    void SetY(const Standard_Real y) {
-    myY = y;
-    }
-    Standard_Real X() const {
-    return myX;
-    }
-    Standard_Real Y() const {
-    return myY;
-    }
-    // some methods like DynamicType() or
-    IsKind()
-    //
-    DEFINE_STANDARD_RTTI(Sample_Point)
-    private:
-    Standard_Real myX;
-    Standard_Real myY;
-    };
-    #endif
-
-~~~~
-
-Then you need to define *Sample_Point.cxx* :
-
-~~~~
-
-    #include <Sample_Point.hxx>
-
-    // Implementation of Handle and type mgt
-
-    IMPLEMENT_STANDARD_HANDLE(Sample_Point,MMgt_TShared)
-    IMPLEMENT_STANDARD_RTTI(Sample_Point,MMgt_TShared)
-
-    // For ancestors, we add a IMPLEMENT_STANDARD_SUPERTYPE and
-    // a IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY  macro.
-    // We must respect the order: from the direct ancestor class to the base class.
-
-    IMPLEMENT_STANDARD_TYPE(Sample_Point)
-    IMPLEMENT_STANDARD_SUPERTYPE(MMgt_TShared)
-    IMPLEMENT_STANDARD_SUPERTYPE(Standard_Transient)
-    IMPLEMENT_STANDARD_SUPERTYPE_ARRAY()
-    IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(MMgt_TShared)
-    IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_ENTRY(Standard_Transient)
-    IMPLEMENT_STANDARD_SUPERTYPE_ARRAY_END()
-    IMPLEMENT_STANDARD_TYPE_END(Sample_Point)
-
-   // Constructors implementation
-
-    Sample_Point::Sample_Point(const
-    Standard_Real x, const Standard_Real y)
-    {
-    myX = x;
-    myY = y;
-    }
-    Sample_Point::Sample_Point()
-    {
-    myX = 0.0;
-    myY = 0.0;
-    }
-~~~~
-
-
 @subsection occt_fcug_2_3 Memory Management 
 
 In a work session, geometric modeling  applications create and delete a considerable number of C++ objects allocated  in the dynamic memory (heap). In this context, performance of standard  functions for allocating and deallocating memory may be not sufficient. For this reason, Open CASCADE Technology employs a specialized memory manager implemented in the *Standard* package. 
@@ -642,7 +524,8 @@ To  allocate memory in a C code with Open CASCADE Technology memory manager, sim
 
 In C++, operators *new()* and *delete()* for a class may be  defined so as to allocate memory using *Standard::Allocate()* and free it using  *Standard::Free()*. In that case all objects of that class and all inherited  classes will be allocated using the OCCT memory manager. 
 
-CDL extractor defines *new()* and *delete()* in this way for all  classes declared with CDL. Thus all OCCT classes (apart from a few exceptions)  are allocated using the OCCT memory manager. 
+Preprocessor macro *DEFINE_STANDARD_ALLOC* provided by header *Standard_DefineAlloc.hxx* defines *new()* and *delete()* in this way.
+It is used for all OCCT classes (apart from a few exceptions) which thus are allocated using the OCCT memory manager. 
 Since operators *new()* and *delete()* are inherited, this is  also true for any class derived from an OCCT class, for instance, for all  classes derived from *Standard_Transient*. 
 
 **Note** that it is possible (though not  recommended unless really unavoidable) to redefine *new()* and *delete()* functions  for a class inheriting *Standard_Transient*. If that is done, the method  *Delete()* should be also redefined to apply operator *delete* to this pointer. This will ensure that appropriate *delete()* function will be called,  even if the object is manipulated by a handle to a base class.
@@ -1073,21 +956,6 @@ The **Collections** component provides a wide range of  generic collections:
   * **Lists** are similar to sequences but have different algorithms to explore them. 
   * Specific iterators for sequences and maps. 
   
-Most collections follow value semantics: their  instances are the actual collections, not **handles** to a collection. Only  arrays and sequences may also be manipulated by handle, and therefore shared. 
-
-Each collection directly used as an argument in Open CASCADE Technology public syntax
-is instantiated in an OCCT component using the corresponding generic class in package
-<i> TCollection</i>, by means of compiling the CDL declaration of the instance. 
-Thus OCCT generic classes require compilation of definitions in the CDL language and therefore
-can only be instantiated in WOK.
-
-If you do not use CDL in your project (CDL compilation under WOK is necessary
-to instantiate any generic Collection from package <i>TCollection</i>), then you should
-use the Collections defined in <i> NCollection</i> package. It contains definitions of the
-same generic collection classes described above, but in a form of C++ templates.
-Therefore, to instantiate any collection type no additional support is required beyond
-the ANSI C++ compiler.
-
 @subsubsection occt_fcug_3_1_2 Generic general-purpose Aggregates
 
 #### TCollection_Array1
@@ -1152,14 +1020,6 @@ Sequences have about the same goal as unidimensional arrays  *TCollection_HArray
   * *Item*, the type of element in the sequence,
   * *Seq*, the actual type of sequence handled by *HSequence*.  This is an instantiation with *Item* of the *TCollection_Sequence* generic  class.
   
-#### TCollection_HSet
-
-This is a collection of non-ordered items without any duplicates. At  each transaction, the system checks if  there are no duplicates. 
-*HSet* objects are *handles* to sets. 
-*HSet* is a generic class which depends on two  parameters: 
-  * *Item*, the type of element in the set,
-  * *Set*, the actual type of set handled by *HSet*. This  is an instantiation with *TCollection_Set* generic class.
-  
 #### TCollection_List
 
 These are ordered lists of non-unique objects which can be accessed  sequentially using an iterator. 
@@ -1174,10 +1034,6 @@ A sequence is a better structure when searching for items by  value.
 
 Queues and stacks are other kinds of list with a different  access to data. 
 
-#### TCollection_Queue
-
-This is a structure, where items are added at the end and removed  from the front. The first item entered will be the first removed (**FIFO**  structure: First In First Out). *Queue* is a generic class which depends  on *Item*, the type of element in the structure. 
-
 #### TCollection_Sequence
 
 This is a sequence of items indexed by an integer. 
@@ -1185,22 +1041,6 @@ Sequences have about the same goal as unidimensional arrays  (*TCollection_Array
 
 *Sequence* is a generic class which depends on *Item*,  the type of element in the sequence. 
 
-#### TCollection_Set
-
-This is a collection of non-ordered items without any duplicates. At  each transaction, the system checks if there are no duplicates. 
-
-A set generates the same result as a map. A map is more  effective; so it is advisable to use maps instead of sets. 
-
-*Set* is a generic class which depends on *Item*,  the type of element in the set. 
-Use *SetIterator* iterator to explore a *Set* structure. 
-
-#### TCollection_Stack
-
-This is a structure where items are added and removed from the top.  The last item entered will be the first removed. 
-
-*Stack* is a generic class which depends on *Item*,  the type of element in the structure. 
-Use a *StackIterator* iterator to explore a *Stack* structure. 
-
 @subsubsection occt_fcug_3_1_3 Generic Maps
 
 Maps are dynamically extended data structures where data is  quickly accessed with a key. *TCollection_BasicMap* is a root class for maps. 
@@ -1403,13 +1243,9 @@ These instantiations are the following:
 @subsection occt_fcug_3_3 NCollections
 @subsubsection occt_fcug_3_3_1 Overview  
   
-*NCollection* package allows to not use WOK development environment in projects. Though it is quite natural to develop a code based on OCCT in any environment accepted in the industry, there is still one limitation: the so-called OCCT generic classes provided in TCollection package require compilation of the definitions in the CDL language and therefore can only be instantiated in WOK development environment.
-
-The NCollection library provides a full replacement of all TCollection generic classes so that any OCCT collection could be instantiated via C++ template or macro definitions. It can be used in WOK as a package development unit, or in any other configuration, since it only uses the standard capabilities of C++ compiler.
+The *NCollection* package provides a set of template collection classes used throughout OCCT.
 
-Macro definitions of these classes are stored in *NCollection_Define\*.hxx* files. These definitions are now obsolete though still can be used, particularly for compatibility with the existing code. On the contrary, template classes in *NCollection_\*.hxx* files are recommended, they are supported by OPEN CASCADE Company and further developed according to various needs.
-
-The technology used in this unit continues and complements the one offered in the header file *Standard_DefineHandle* -- allowing to implement outside CDL the classes managed by Handle, also providing OCCT RTTI support.
+Macro definitions of these classes are stored in *NCollection_Define\*.hxx* files. These definitions are now obsolete though still can be used, particularly for compatibility with the existing code.
 
 @subsubsection occt_fcug_3_3_2 Instantiation of collection classes
 
@@ -1478,24 +1314,26 @@ Source code file will be *MyPackage_HSequenceOfPnt.cxx* or any other .cxx file (
 IMPLEMENT_HSEQUENCE (MyPackage_HSequenceOfPnt)
 ~~~~~
 
-@subsubsection occt_fcug_3_3_3 Class architecture
-
-
-To understand the basic architecture of the classes instantiated from *NCollection* macros, please refer to the documentation on *TCollection* package, particularly to CDL files. Almost all API described there is preserved in *NCollection*. Changes are described in corresponding *NCollection_Define\*.hxx* files. 
-
-Nevertheless the internal structure of NCollection classes is more complex than that of *TCollection* ones, providing more capabilities. The advanced layer of architecture is described in the next chapter Features.
+@subsubsection occt_fcug_3_3_3 Arrays and sequences
 
-There are two principal changes:
-* In *TCollection* some classes ( Stack, List, Set, Map, DataMap, DoubleMap ) define the Iterator type, the name of Iterator being like *MyPackage_DoubleMapIteratorOfDoubleMapOfIntegerReal*. In *NCollection* each Iterator is always defined as subtype of the collection *MyPackage_DoubleMapOfIntegerReal::Iterator*. 
-* Hashed collections (of type Map\* ) require in *TCollection* that the special class *Map\*Hasher* is defined. In *NCollection* it is only required that the global functions *IsEqual* and *HashCode* are defined. 
+Standard collections provided by OCCT are:
+* *NCollection_Array1* - fixed-size (at initialization) one-dimensional array; note that index can start at any value, usually 1
+* *NCollection_Array2* - fixed-size (at initialization) two-dimensional array; note that index can start at any value, usually 1
+* *NCollection_List* - plain list
+* *NCollection_Sequence* - double-connected list with access by index; note that index starts at 1
 
-#### Interface to classes defined in CDL
+These classes provide STL-style iterators (methods begin() and end()) and thus can be used in STL algorithms.
 
-The classes defined above can be used as types for fields, parameters of methods and return values in CDL definitions. In our example, if MyPackage is a CDL package, you will need to create the file *MyPackage_SequenceOfPnt.hxx* containing or including the above definitions, and then to add the line: imported *SequenceOfPnt* to file *MyPackage.cdl*;
+@subsubsection occt_fcug_3_3_3x Maps
 
-Then the new collection type can be used in any CDL definition under the name *SequenceOfPnt* from *MyPackage*.
+NCollection provides several classes for storage of objects by value, providing fast search due to use of hash:
+* *NCollection_Map* - hash set
+* *NCollection_IndexedMap* - set with prefixed order of elements, allowing fast access by index or by value (hash-based)
+* *NCollection_DataMap* - hash map
+* *NCollection_IndexedDataMap* - map with prefixed order of elements, allowing fast access by index or by value (hash-based)
+* *NCollection_DoubleMap* - two-side hash map (with two keys)
 
-@subsubsection occt_fcug_3_3_4 New collection types
+@subsubsection occt_fcug_3_3_4 Other collection types
 
 There are 4 collection types provided as template classes:
 * *NCollection_Vector*
@@ -1904,7 +1742,7 @@ They provide:
   
 All these functions are provided by geometric processor package <i> gp</i>. Its classes for 2d and 3d objects are handled by value rather than by reference. When this sort of object is copied, it is copied entirely. Changes in one instance will not be  reflected in another. 
 
-The *gp* package defines the basic non-persistent  geometric entities used for algebraic calculation and basic analytical geometry  in 2d & 3d space. It also provides basic transformations such as identity,  rotation, translation, mirroring, scale transformations, combinations of  transformations, etc. Entities are handled by value.  
+The *gp* package defines the basic geometric entities used for algebraic calculation and basic analytical geometry  in 2d & 3d space. It also provides basic transformations such as identity,  rotation, translation, mirroring, scale transformations, combinations of  transformations, etc. Entities are handled by value.  
 
 Please, note that <i> gp</i> curves and surfaces are analytic: there is no parameterization and no orientation on <i>gp</i> entities, i.e. these entities do not provide functions which work with these properties. 
 
@@ -1922,7 +1760,6 @@ Note: the <i> gp</i> entities cannot be shared when they are inside more complex
 Before creating a geometric object, you must decide whether  you are in a 2d or in a 3d context and how you want to handle the object. 
 If you do not need a single instance of a geometric  primitive but a set of them then the package which deals with collections of  this sort of object, *TColgp*, will provide the necessary functionality. 
 In particular, this package provides standard and frequently  used instantiations of generic classes with geometric objects, i.e. *XY*, *XYZ*,  *Pnt*, *Pnt2d*, *Vec*, *Vec2d*, *Lin*, *Lin2d*, *Circ*,  *Circ2d.* 
-These are non-persistent classes. 
 
 @subsection occt_occt_fcug_4_5 Basic Geometric Libraries
 There are various library packages available which offer a  range of basic computations on curves and surfaces. 
@@ -2135,76 +1972,3 @@ This is reasonable precision to pass to an Intersection process as  a limit of r
 This is a reasonable precision to pass to an approximation process  as a limit of refinement of fitting. The approximation is greater than the other  precisions because it is designed to be used when the time is at a premium. It has  been provided as a reasonable compromise by the designers of the Approximation  algorithm. The current value is *Confusion() * 10*. 
 Note that Approximation is greater than Confusion, so care  must be taken when using Confusion in an approximation process. 
 
-@section occt_fcug_5 Data Storage
-@subsection occt_fcug_5_1 Saving and Opening Files
-
-@image html /user_guides/foundation_classes/images/foundation_classes_image007.png "Example of Saving-Opening workflow"
-@image latex /user_guides/foundation_classes/images/foundation_classes_image007.png "Example of Saving-Opening workflow"
-   
-In the example, the roots of the transferable transient objects *TopoDS_Shape, Geom_Geometry* and *Geom2d_Geometry* are used in algorithms, they contain data and temporary results. 
-The associated objects in the persistent domain are *PTopoDS_HShape, PGeom_Geometry* and *PGeom2d_Geometry*. They contain a real data  structure which is stored in a file. 
-Note that when an object is stored, if it contains another  stored object, the references to the contained object are also managed. 
-@image html /user_guides/foundation_classes/images/foundation_classes_image008.png "Saving-Opening mechanism"
-@image latex /user_guides/foundation_classes/images/foundation_classes_image008.png "Saving-Opening mechanism"
-
-
-@subsection occt_fcug_5_2 Basic Storage Procedures
-
-@subsubsection occt_fcug_5_2_1 Saving
-
-The storage procedure of a transient object follows five  main steps. 
-1. Create  an I/O driver for files. For example, *FSD_File f()*; 
-2. Instance the data schema, which will process your persistent information. The schema is  used for read/write operations. If ShapeSchema is the name of your schema: 
-~~~~~
-Handle(ShapeSchema) s = new ShapeSchema; 
-~~~~~
-3. Create a persistent shape from a transient shape. 
-~~~~~
-TopoDS_Shape  aShape; 
-PTColStd_TransientPersistentMap  aMap; 
-Handle(PTopoDS_HShape)  aPShape = MgtBRep::Translate 
-  (aShape, aMap, MgtBRep_WithoutTriangle); 
-~~~~~
-4. Create  a new container and fill it using the *AddRoot()* method. 
-~~~~~
-Handle(Storage_Data)  d = new Storage_Data; 
-d  -> AddRoot (“ObjectName”, aPShape); 
-~~~~~
-You may add as  many objects as you want in this container. 
-5. Save  to the archive. 
-~~~~~
-s -> Write (f,d); 
-~~~~~
-
-@subsubsection occt_fcug_5_2_2 Opening
-The retrieval mechanism is the opposite of the storage  mechanism. The procedure for retrieving an object is as follows:
-1. Create  an I/O driver and instance a data schema (if not done). 
-2. Read  the persistent object from the archive and get the list of objects using *Roots()* method. 
-~~~~~
-Handle(Storage_Data)  d = s -> Read(f); 
-Handle(Storage_HSeqOfRoot)  roots = d-> Roots(); 
-~~~~~
-3. Loop  on root objects to get *Standard_Persistent* objects (the following sequence only  gets the first root). 
-~~~~~
-Handle(Standard_Persistent)  p; 
-Handle(Standard_Root)  r; 
-if(roots  -> Length() >= 1) { 
-   r = roots -> Value(1); 
-   p = r -> Object(); 
-} 
-~~~~~
-4. DownCast  the persistent object to a *PTopoDS_Hshape*. 
-~~~~~
-Handle(PTopoDS_HShape) aPShape; 
-aPShape =  Handle(PTopoDS_HShape)::DownCast(p); 
-~~~~~
-5. Create  the *TopoDS_Shape*. 
-~~~~~
-TopoDS_Shape aShape; 
-PTColStd_PersistentTransientMap aMap;    
-MgtBRep::Translate (aPShape, aMap,  aShape, MgtBRep_WithoutTriangle); 
-~~~~~
-
-
-
index cbcb533..f9ee0a1 100644 (file)
@@ -202,9 +202,9 @@ construction or construction error) is described by the enumeration <i>gce_Error
 Note, that classes, which construct geometric transformations do not return a status, and therefore do not inherit from *Root*.
 
 
-@subsubsection occt_modat_1_2_1 Non-persistent entities
+@subsubsection occt_modat_1_2_1 Simple geometric entities
 
-The following algorithms used to build entities from non-persistent *gp* entities are provided by *gce* package. 
+The following algorithms used to build entities from *gp* package are provided by *gce* package. 
 - 2D line parallel to another at a distance, 
 - 2D line parallel to another passing through a point, 
 - 2D circle passing through two points, 
@@ -264,9 +264,11 @@ This is useful if you are uncertain as to whether the arguments can create the *
 gp_Lin2d l = gce_MakeLin2d(Point1,Point2); 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-@subsubsection occt_modat_1_2_2 Persistent entities
+@subsubsection occt_modat_1_2_2 Geometric entities manipulated by handle
 
-*GC* and *GCE2d* packages provides an implementation of algorithms used to build entities from *Geom* and *Geom2D* packages. They implement the same algorithms as the *gce* package but create **persistent** entities, and also contain algorithms for trimmed surfaces and curves. The following algorithms are available: 
+*GC* and *GCE2d* packages provides an implementation of algorithms used to build entities from *Geom* and *Geom2D* packages.
+They implement the same algorithms as the *gce* package, and also contain algorithms for trimmed surfaces and curves.
+The following algorithms are available: 
 - arc of a circle trimmed by two points, 
 - arc of a circle trimmed by two parameters, 
 - arc of a circle trimmed by one point and one parameter, 
@@ -420,7 +422,7 @@ The *GeomAPI_ExtremaSurfaceSurface* class allows calculation of all extrema betw
 
 @section occt_modat_2 2D Geometry
 
-*Geom2d* package defines geometric objects in 2dspace. All geometric entities are STEP processed. The objects are non-persistent and are handled by reference.
+*Geom2d* package defines geometric objects in 2dspace. All geometric entities are STEP processed. The objects are handled by reference.
 
 In particular, <i>Geom2d</i> package provides classes for:
 * description of points, vectors and curves,
@@ -484,7 +486,7 @@ In particular, it provides classes for:
  * their positioning in 3D space using axis or coordinate systems, and
  * their geometric transformation, by applying translations, rotations, symmetries, scaling transformations and combinations thereof.
 
-The following non-persistent and reference-handled objects are available: 
+The following objects are available: 
 - Point 
 - Cartesian point 
 - Vector
index 942f1cf..6c58138 100644 (file)
@@ -105,7 +105,7 @@ The *Application* is an abstract class in charge of handling documents during th
   
 In addition,  application-specific data can be added by defining new attribute classes; naturally, this changes the standard file format. The only functions that have to be implemented are:
     * Copying the  attribute
-    * Converting  it from and to its persistent homologue (persistence is briefly presented in the paragraph @ref occt_ocaf_9a_3 "Persistent Data Storage")
+    * Converting  it from and persistent data storage
        
 @subsection occt_ocaf_1_3  Reference-key model
 
@@ -483,32 +483,23 @@ If the set of existing and ready to use attributes implementing standard data ty
 
 There are two ways to implement a new data type: create a new attribute (standard approach), or use the notion of User Attribute by means of a combination of standard attributes  (alternative way) 
 
-In order to create a new attribute in the standard way do the following: 
-* Create a class inherited from *TDF_Attribute* and implement all purely virtual and necessary virtual methods:
-       + **ID()** -- returns a unique GUID of a given attribute 
-       + **Restore(attribute)** -- sets fields of this attribute equal to the fields of a given attribute of the same type 
-       + **Paste(attribute, relocation_table)** -- sets fields of a given attribute equal to the field values of this attribute ; if the attribute has references to some objects of the data framework  and relocation_table has this element, then the given attribute must also refer to this object . 
-       + **NewEmpty()** -- returns a new attribute of this class with empty fields 
-       + **Dump(stream)** --  outputs information about a given attribute to a given stream debug (usually outputs an attribute of type string only) 
-* Create the persistence classes for this attribute according to the file format chosen for the document (see below).
+In order to create a new attribute in the standard way, create a class inherited from *TDF_Attribute* and implement all purely virtual and necessary virtual methods:
+* **ID()** -- returns a unique GUID of a given attribute 
+* **Restore(attribute)** -- sets fields of this attribute equal to the fields of a given attribute of the same type 
+* **Paste(attribute, relocation_table)** -- sets fields of a given attribute equal to the field values of this attribute ; if the attribute has references to some objects of the data framework  and relocation_table has this element, then the given attribute must also refer to this object . 
+* **NewEmpty()** -- returns a new attribute of this class with empty fields 
+* **Dump(stream)** --  outputs information about a given attribute to a given stream debug (usually outputs an attribute of type string only) 
 
 Methods *NewEmpty, Restore* and *Paste* are used for the common transactions mechanism (Undo/Redo commands). If you don’t need this attribute to react to undo/redo commands, you can write only stubs of these methods, else you must call the Backup method of the *TDF_Attribute* class every time attribute fields are changed. 
 
-If you use a standard file format and you want your new attributes to be stored during document saving and retrieved to the data framework whenever a document is opened, you must do the following: 
-
-  1. If you place an attribute to a new package, it is desirable (although not mandatory) if your package name starts with letter "T" (transient), for example: attribute *TMyAttributePackage_MyAttribute* in the package *TMyAttributePackage*.
-  2. Create a new package with name "P[package name]" (for example *PMyAttributePackage*) with class *PMyAttributePackage_MyAttribute* inside. The new class inherits the *PDF_Attribute* class and contains fields of attributes, which must be saved or retrieved ("P" -- persistent).
-  3. Create a new package with name "M[package name]" (for example *MMyAttributePackage*) with classes *MMyAttributePackage_MyAttributeRetrievalDriver* and *MMyAttributePackage_MyAttributeStorageDriver* inside. The new classes inherit *MDF_ARDriver* and *MDF_ASDriver* classes respectively and contain the translation functionality: from T... attribute to P... and vice versa (M -- middle) (see the realization of the standard attributes).
-  4. M... package must contain *AddStorageDrivers(aDriverSeq : ASDriverHSequence* from MDF) and *AddRetrievalDrivers(aDriverSeq : ASDriverHSequence* from MDF) methods, which append to the given sequence  of drivers *aDriverSeq*, which is a sequence of all new attribute drivers (see the previous point) used for the storage/retrieval of attributes. 
-  5 Use the standard schema (*StdSchema* unit) or create a new one to add your P-package and compile it. 
-
-If you use the XML format, do the following: 
+To enable possibility to save / restore the new attribute in XML format, do the following: 
   1. Create a new package with the name Xml[package name] (for example *XmlMyAttributePackage*) containing  class *XmlMyAttributePackage_MyAttributeDriver*. The new class inherits *XmlMDF_ADriver* class and contains the translation functionality: from transient to persistent and vice versa (see the realization of the standard attributes in the packages *XmlMDataStd*, for example). Add package method AddDrivers which adds your class to a driver table (see below).
   2. Create a new package (or do it in the current one) with two package methods: 
          * *Factory*, which loads the document storage and retrieval drivers; and 
          * *AttributeDrivers*, which calls the methods AddDrivers for all packages responsible for persistence of the document.
   3. Create a plug-in implemented as an executable (see example *XmlPlugin*). It calls a macro PLUGIN with the package name where you implemented the method Factory.
-If you use the binary format, do the following: 
+
+To enable possibility to save / restore the new attribute in binary format, do the following: 
   1. Create a new package with name <i> Bin[package name] </i> (for example *BinMyAttributePackage*) containing a class *BinMyAttributePackage_MyAttributeDriver*. The new class inherits *BinMDF_ADriver* class and contains the translation functionality: from transient to persistent and vice versa (see the realization of the standard attributes in the packages *BinMDataStd*, for example). Add package method *AddDrivers*, which adds your class to a driver table.
   2. Create a new package (or do it in the current one) with two package methods: 
          * Factory, which loads the document storage and retrieval drivers; and 
@@ -1745,25 +1736,11 @@ Both the XML format and the XML OCAF persistence code are extensible in the sens
 In OCAF, persistence, that is, the mechanism used to  save a document in a file, is based on an explicit formal description of the  data saved.  
  
 When you open a document, the application reads the corresponding file and first creates a memory representation of it. This representation is then converted to the application data model —  the OCAF-based data structure the application operates on. The file's memory representation  consists of objects defined by classes known as persistent. 
-  
-The persistent  classes needed by an application to save its documents make the application's data schema. This schema defines the way the data are organized in the file — the format of the data. In other words, the file is simply an ASCII dump of the  persistent data defined by the schema, the persistent data being created from  the application data model during the save process.  
    
-Only canonical information is saved. As a matter of  fact, the application data model usually contains additional data to optimize  processing. For example, the persistent Bézier curve is defined by its poles, whereas its data model equivalent also contains coefficients used to compute a point at a given parameter.  The additional data is calculated when the document is opened.  
-The major advantages of this approach are the following:  
-  * Providing  that the data format is published, files created by OCAF-based applications 
-   can be read without needing a runtime of the application (openness)
-  * Although the  persistence approach makes the data format more stable, 
-   OCAF provides a  framework for managing compatibility of data between versions of the application — 
-   modification of the data format is supported through the  versioning of schema.
-  OCAF includes a ready-to-use schema suitable for most  applications. 
-  However, it can be extended if needed. For that, the only things  you have to do are:  
-
-  * To define  the additional persistent attributes
-  * To implement  the functions converting these persistent attribute to and from the application  data model.
+OCAF includes a ready-to-use schema suitable for most  applications. 
+However, it can be extended if needed. 
   
-Applications using compound documents extensively (saving data in many files linked together) should implement data management services. As a matter of fact, it's out the scope of OCAF to provide functions such as:
+Applications using compound documents extensively (saving data in many files linked together) should implement data management services. It is out the scope of OCAF to provide functions such as:
 * Version and configuration management of compound documents;
 * Querying a referenced document for its referencing documents.
 
@@ -1774,198 +1751,14 @@ In order to ease the delegation of document management to a data management appl
 
 There are three schemes of persistence, which you can use to store and retrieve OCAF data (documents):
 
-  * <i> Standard</i> persistence schema, compatible with previous OCAF applications
+  * <i> Standard</i> persistence schema, compatible with previous OCAF applications. This schema is deprecated and supports only reading of standard attributes (no writing).
   * <i> XmlOcaf</i> persistence, allowing the storage of all OCAF data in XML form
   * <i> BinOcaf</i> persistence, allowing the storage of all OCAF data in binary format form
 
 
-All schemes are independent of each other, but they guarantee that the standard OCAF
-attributes stored and retrieved by one schema will be storable and retrievable by
-the other. Therefore in any OCAF application you can use any persistence schema or
+In an OCAF application you can use any persistence schema or
 even all three of them. The choice is made depending on the *Format* string of stored OCAF documents
 or automatically by the file header data -- on retrieval.
-
-Persistent data storage in OCAF using the <i> Standard</i> package is presented in: 
-
-  * Basic Data Storage 
-  * Persistent Collections 
-
-Persistent storage of shapes is presented in the following chapters:
-
-  * Persistent Geometry 
-  * Persistent Topology 
-
-Finally, information about opening and saving persistent data is presented in Standard
-Documents. 
-
-@subsection occt_ocaf_9a_3 Basic Data Storage
-
-Normally, all data structures provided by Open CASCADE Technology are run-time structures,
-in other words, transient data. As transient data, they exist only while an application
-is running and are not stored permanently. However, the Data Storage module provides
-resources, which enable an application to store data on disk as persistent data.
-
-Data storage services also provide libraries of persistent classes and translation
-functions needed to translate data from transient to persistent state and vice-versa.
-
-#### Libraries of persistent classes
-
-Libraries of persistent classes are extensible libraries of elementary classes you
-use to define the database schema of your application. They include:
-* Unicode (8-bit or 16-bit character type) strings 
-* Collections of any kind of persistent data such as arrays.
-
-All persistent classes are derived from the \b Persistent base class, which defines
-a unique way of creating and handling persistent objects. You create new persistent
-classes by inheriting from this base class.
-
-#### Translation Functions
-
-Translation functions allow you to convert persistent objects to transient ones and
-vice-versa. These translation functions are used to build Storage and Retrieval drivers
-of an application.
-
-For each class of 2D and 3D geometric types, and for the general shape class in the
-topological data structure library, there are corresponding persistent class libraries,
-which allow you to translate your data with ease.
-
-#### Creation of Persistent Classes
-
-If you use Unix platforms as well as WOK and CDL, you can create your own persistent
-classes. In this case, data storage is achieved by implementing *Storage* and *Retrieval*
-drivers.
-
-The <i> Storage </i> package is used to write and read persistent objects. 
-These objects are read and written by a retrieval or storage algorithm 
-(<i> Storage_Schema </i>object) in a container (disk, memory, network ...). 
-Drivers (<i> FSD_File</i> objects) assign a physical container for data to be stored or retrieved.
-
-The standard procedure for an application in reading a container is as follows:
-
-* open the driver in reading mode,
-* call the Read function from the schema, setting the driver as a parameter. This function returns an instance of the <i> Storage_Data </i> class which contains the data being read,
-* close the driver.
-
-The standard procedure for an application in writing a container is as follows:
-
-* open the driver in writing mode,
-* create an instance of the <i> Storage_Data </i> class, then add the persistent data to write with the function <i> AddRoot</i>,
-* call the function <i> Write </i> from the schema, setting the driver and the <i> Storage_Data </i> instance as parameters,
-* close the driver.
-
-@subsection occt_ocaf_9a_4 Persistent Collections
-
-Persistent collections are classes which handle dynamically sized collections of data that can be stored in the database. These collections provide three categories of service:
-
-  * persistent strings,
-  * generic arrays of data, 
-  * commonly used instantiations of arrays.
-
-Persistent strings are concrete classes that handle sequences of characters based
-on both ASCII (normal 8-bit) and Unicode (16-bit) character sets.
-
-Arrays are generic classes, that is, they can hold a variety of objects not necessarily inheriting from a unique root class. These arrays can be instantiated with any kind of storable or persistent object, and then inserted into the persistent data model of a user application.
-
-The purpose of these data collections is simply to convert transient data into its persistent equivalent so that it can be stored in the database. To this end, the collections are used to create the persistent data model and assure the link with the database. They do not provide editing or query capabilities because it is more efficient, within the operative data model of the application, to work with transient data structures (from the <i> TCollection</i> package).
-
-For this reason:
-
-  * the persistent strings only provide constructors and functions to convert between transient and persistent strings, and
-  * the persistent data collections are limited to arrays. In other words, <i> PCollection</i> does not include sequences, lists, and so on (unlike <i> TCollection</i>).
-
-Persistent string and array classes are found in the <i> PCollection</i> package. In addition, <i> PColStd</i> package provides standard, and frequently used, instantiations of persistent arrays, for very simple objects.
-
-@subsection occt_ocaf_9a_5 Persistent Geometry
-
-The Persistent Geometry component describes geometric data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
-
-Persistent Geometry consists of a set of atomic data models parallel to the geometric data structures described in the geometry packages. Geometric data models, independent of each other, can appear within the data model of any application. The system provides the means to convert each atomic transient data model into a persistent one, but it does not provide a way for these data models to share data.
-
-Consequently, you can create a data model using these components, store data in, and retrieve it from a file or a database, using the geometric components provided in the transient and persistent "worlds". In other words, you customize the system by declaring your own objects, and the conversion of the geometric components from persistent to transient and vice versa is automatically managed for you by the system.
-
-However, these simple objects cannot be shared within a more complex data model. To allow data to be shared, you must provide additional tools.
-
-Persistent Geometry is provided by several packages.
-
-The <i> PGeom</i> package describes geometric persistent objects in 3D space, such as points,
-vectors, positioning systems, curves and surfaces.
-
-These objects are persistent versions of those provided by the <i> Geom</i> package: for
-each type of transient object provided by Geom there is a corresponding type of persistent
-object in the <i>PGeom</i> package. In particular the inheritance structure is parallel.
-
-However the <i> PGeom </i>package does not provide any functions to construct, edit or access
-the persistent objects. Instead the objects are manipulated as follows:
-
-  * Persistent objects are constructed by converting the equivalent transient <i> Geom </i> objects. To do this you use the <i>MgtGeom::Translate</i> function.
-  * Persistent objects created in this way are used to build persistent data structures that are then stored in a file or database.
-  * When these objects are retrieved from the file or database, they are converted back into the corresponding transient objects from the Geom package. To do this, you use <i>MgtGeom::Translate</i> function.
-
-In other words, you always edit or query transient data structures within the transient
-data model supplied by the session.
-Consequently, the documentation for the <i> PGeom </i> package consists simply of a list of available objects.
-
-The <i> PGeom2d </i> package describes persistent geometric objects in 2D space, such as points,
-vectors, positioning systems and curves. This package provides the same type of services
-as the <i> PGeom</i> package, but for the 2D geometric objects provided by the <i> Geom2d</i> package.
-Conversions are provided by the <i>MgtGeom::Translate</i> function.
-
-~~~~
-//Create a coordinate system
-Handle(Geom_Axis2Placement) aSys;
-
-
-//Create a persistent coordinate PTopoDS_HShape.cdlsystem
-Handle(PGeom_Axis2placement)
-       aPSys = MgtGeom::Translate(aSys);
-
-//Restore a transient coordinate system
-Handle(PGeom_Axis2Placement) aPSys;
-
-Handle(Geom_Axis2Placement)
-       aSys = MgtGeom::Translate(aPSys);
-~~~~
-
-
-@subsection occt_ocaf_9a_6 Persistent Topology
-
-The Persistent Topology component describes topological data structures which can be stored in the database. These packages provide a way to convert data from the transient "world" to the persistent "world".
-
-Persistent Topology is based on the BRep concrete data model provided by the topology packages. Unlike the components of the Persistent Geometry package, topological components can be fully shared within a single model, as well as between several models.
-
-Each topological component is considered to be a shape: a <i> TopoDS_Shape</i> object. The system's capacity to convert a transient shape into a persistent shape and vice-versa applies to all objects, irrespective of their complexity: vertex, edge, wire, face, shell, solid, and so on.
-
-When a user creates a data model using BRep shapes, he uses the conversion functions that the system provides to store the data in, and retrieve it from the database. The data can also be shared.
-
-Persistent Topology is provided by several packages.
-
-The <i> PTopoDS</i> package describes the persistent data model associated with any BRep shape; it is the persistent version of any shape of type <i> TopoDS_Shape</i>. As is the case for persistent geometric models, this data structure is never edited or queried, it is simply stored in or retrieved from the database. It is created or converted by the <i>MgtBRep::Translate</i> function.
-
-The <i> MgtBRepAbs</i> and <i> PTColStd </i> packages provide tools used by the conversion functions of topological objects.
-
-~~~~
-//Create a shape
-TopoDS_Shape aShape;
-
-//Create a persistent shape
-PtColStd_DoubleTransientPersistentMap aMap;
-
-Handle(PTopoDS_HShape) aPShape =
-       aMap.Bind2(MgtBRep::Translate
-               aShape,aMap,MgtBRepAbs_WithTriangle));
-
-aPShape.Nullify();
-
-//Restore a transient shape
-Handle(PTopoDS_HShape) aPShape;
-
-Handle(TopoDS_HShape) aShape =
-       aMap.Bind1(MgtBRep::Translate
-               (aPShape,aMap,MgtBRepAbs_WithTriangle));
-
-aShape.Nullify();
-~~~~
-
   
 @section occt_ocaf_10 GLOSSARY
 
@@ -1986,7 +1779,6 @@ aShape.Nullify();
        * Store the names of software extensions. 
 * **Driver** -- an abstract class, which defines the communications protocol with a system. 
 * **Entry** -- an ASCII character string containing the tag list of a label. For example:
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
 0:3:24:7:2:7 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2002,7 +1794,6 @@ To store these references properly, a label must also contain an external link a
 In C++, the application behavior is implemented in virtual functions redefined in these derived classes. This is known as overriding. 
 
 * **GUID** -- Global Universal ID. A string of 37 characters intended to uniquely identify an object. For example:
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
 2a96b602-ec8b-11d0-bee7-080009dc3333 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2148,162 +1939,109 @@ ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
  
 
 
-@subsection occt_ocaf_11_1 Implementation of Attribute Transformation in a CDL file
+@subsection occt_ocaf_11_1 Implementation of Attribute Transformation in a HXX file
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-class Transformation from MyPackage inherits Attribute from TDF 
+\#include <TDF_Attribute.hxx>
 
-    ---Purpose: This attribute implements a transformation data container. 
+\#include <gp_Ax3.hxx>
+\#include <gp_Pnt.hxx>
+\#include <gp_Vec.hxx>
+\#include <gp_Trsf.hxx>
 
-uses 
+//! This attribute implements a transformation data container
+class MyPackage_Transformation : public TDF_Attribute
+{
+public:
+  //!@name Static methods 
 
-     Attribute       from TDF, 
-     Label           from TDF, 
-     GUID            from Standard, 
-     RelocationTable from TDF, 
-     Pnt             from gp, 
-     Ax1             from gp, 
-     Ax2             from gp, 
-     Ax3             from gp, 
-     Vec             from gp, 
-     Trsf            from gp, 
-     TrsfForm        from gp 
+  //! The method returns a unique GUID of this attribute. 
+  //! By means of this GUID this attribute may be identified   
+  //! among other attributes attached to the same label. 
+  Standard_EXPORT static const Standard_GUID& GetID ();
 
-is 
+  //! Finds or creates the attribute attached to <theLabel>. 
+  //! The found or created attribute is returned. 
+  Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
 
-    ---Category: Static methods 
-    --          =============== 
+  //!@name Methods for access to the attribute data 
+      
+  //! The method returns the transformation. 
+  Standard_EXPORT gp_Trsf Get () const; 
 
-    GetID (myclass)     
-    ---C++: return const &    
-    ---Purpose: The method returns a unique GUID of this attribute. 
-    --          By means of this GUID this attribute may be identified   
-    --          among other attributes attached to the same label. 
-    returns GUID from Standard; 
+  //!@name Methods for setting the data of transformation 
 
-    Set (myclass; theLabel : Label from TDF) 
-    ---Purpose: Finds or creates the attribute attached to <theLabel>. 
-    --          The found or created attribute is returned. 
-    returns Transformation from MyPackage; 
+  //! The method defines a rotation type of transformation. 
+  Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle); 
 
+  //! The method defines a translation type of transformation. 
+  Standard_EXPORT void SetTranslation (const gp_Vec& theVector); 
 
-    ---Category: Methods for access to the attribute data 
-    --           ======================================== 
-      
-    Get (me) 
-    ---Purpose: The method returns the transformation. 
-    returns Trsf from gp; 
+  //! The method defines a point mirror type of transformation (point symmetry). 
+  Standard_EXPORT void SetMirror (const gp_Pnt& thePoint); 
 
+  //! The method defines an axis mirror type of transformation (axial symmetry). 
+  Standard_EXPORT void SetMirror (const gp_Ax1& theAxis); 
 
-    ---Category: Methods for setting the data of transformation 
-    --           ============================================== 
+  //! The method defines a point mirror type of transformation (planar symmetry). 
+  Standard_EXPORT void SetMirror (const gp_Ax2& thePlane); 
 
-    SetRotation (me : mutable; 
-                         theAxis : Ax1 from gp; 
-                         theAngle : Real from Standard); 
-    ---Purpose: The method defines a rotation type of transformation. 
+  //! The method defines a scale type of transformation. 
+  Standard_EXPORT void SetScale (const gp_Pnt& thePoint, Standard_Real theScale); 
 
-    SetTranslation (me : mutable; 
-                            theVector : Vec from gp); 
-    ---Purpose: The method defines a translation type of transformation. 
+  //! The method defines a complex type of transformation from one co-ordinate system to another. 
+  Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2); 
 
-    SetMirror (me : mutable; 
-                   thePoint : Pnt from gp); 
-    ---Purpose: The method defines a point mirror type of transformation 
-    --          (point symmetry). 
+  //!@name Overridden methods from TDF_Attribute 
+      
+  //! The method returns a unique GUID of the attribute. 
+  //! By means of this GUID this attribute may be identified among other attributes attached to the same label. 
+  Standard_EXPORT const Standard_GUID& ID () const; 
 
-    SetMirror (me : mutable; 
-                   theAxis : Ax1 from gp); 
-    ---Purpose: The method defines an axis mirror type of transformation 
-    --          (axial symmetry). 
+  //! The method is called on Undo / Redo. 
+  //! It copies the content of theAttribute into this attribute (copies the fields). 
+  Standard_EXPORT void Restore (const Handle(TDF_Attribute)& theAttribute); 
 
-    SetMirror (me : mutable; 
-                   thePlane : Ax2 from gp); 
-    ---Purpose: The method defines a point mirror type of transformation 
-    --          (planar symmetry). 
+  //! It creates a new instance of this attribute. 
+  //! It is called on Copy / Paste, Undo / Redo. 
+  Standard_EXPORT Handle(TDF_Attribute) NewEmpty () const;
 
-    SetScale (me : mutable; 
-                  thePoint : Pnt from gp; 
-                  theScale : Real from Standard); 
-    ---Purpose: The method defines a scale type of transformation. 
+  //! The method is called on Copy / Paste. 
+  //! It copies the content of this attribute into theAttribute (copies the fields). 
+  Standard_EXPORT void Paste (const Handle(TDF_Attribute)& theAttribute, const Handle(TDF_RelocationTable)& theRelocationTable); 
 
-    SetTransformation (me : mutable; 
-                               theCoordinateSystem1 : Ax3 from gp; 
-                               theCoordinateSystem2 : Ax3 from gp); 
-    ---Purpose: The method defines a complex type of transformation 
-    --          from one co-ordinate system to another. 
+  //! Prints the content of this attribute into the stream. 
+  Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
 
+  //!@name Constructor 
 
-    ---Category: Overridden methods from TDF_Attribute 
-    --           ===================================== 
-      
-    ID (me) 
-    ---C++: return const &   
-    ---Purpose: The method returns a unique GUID of the attribute. 
-    --          By means of this GUID this attribute may be identified   
-    --          among other attributes attached to the same label. 
-    returns GUID from Standard; 
-
-    Restore (me: mutable;   
-                 theAttribute : Attribute from TDF); 
-    ---Purpose: The method is called on Undo / Redo. 
-    --          It copies the content of <theAttribute> 
-    --          into this attribute (copies the fields). 
-
-    NewEmpty (me) 
-    ---Purpose: It creates a new instance of this attribute. 
-    --          It is called on Copy / Paste, Undo / Redo. 
-    returns mutable Attribute from TDF; 
-
-    Paste (me;   
-               theAttribute : mutable Attribute from TDF; 
-               theRelocationTable : mutable RelocationTable from TDF); 
-    ---Purpose:: The method is called on Copy / Paste. 
-    --           It copies the content of this attribute into 
-    --           <theAttribute> (copies the fields). 
-
-    Dump(me; anOS : in out OStream from Standard) 
-    ---C++: return; 
-    ---Purpose: Prints the content of this attribute into the stream. 
-    returns OStream from Standard is redefined; 
-
-
-    ---Category: Constructor 
-    --           =========== 
-
-    Create 
-    ---Purpose: The C++ constructor of this atribute class. 
-    --          Usually it is never called outside this class. 
-    returns mutable Transformation from MyPackage;      
-
-
-fields 
-
-    -- Type of transformation 
-    myType : TrsfForm from gp; 
-
-    -- Axes (Ax1, Ax2, Ax3) 
-    myAx1 : Ax1 from gp; 
-    myAx2 : Ax2 from gp; 
-    myFirstAx3 : Ax3 from gp; 
-    mySecondAx3 : Ax3 from gp; 
-      
-    -- Scalar values 
-    myAngle : Real from Standard; 
-    myScale : Real from Standard; 
-      
-    -- Points 
-    myFirstPoint : Pnt from gp; 
-    mySecondPoint : Pnt from gp; 
+  //! The C++ constructor of this atribute class. 
+  //! Usually it is never called outside this class. 
+  Standard_EXPORT MyPackage_Transformation();
+
+private:
+  gp_TrsfForm myType;
 
+  // Axes (Ax1, Ax2, Ax3) 
+  gp_Ax1 myAx1;
+  gp_Ax2 myAx2;
+  gp_Ax3 myFirstAx3;
+  gp_Ax3 mySecondAx3;
 
-end Transformation; 
+  // Scalar values 
+  Standard_Real myAngle;
+  Standard_Real myScale;
+
+  // Points 
+  gp_Pnt myFirstPoint;
+  gp_Pnt mySecondPoint;
+}; 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 @subsection occt_ocaf_11_2 Implementation of Attribute Transformation in a CPP file
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
-#include MyPackage_Transformation.ixx; 
+\#include <MyPackage_Transformation.hxx> 
 
 //======================================================================= 
 //function : GetID 
index 1281dbb..3501349 100644 (file)
@@ -50,7 +50,7 @@ Each sub-domain has its own scope of functionality:
 * customization -- modifying shape representation to fit specific needs (shape is not modified, only the form of its representation is modified); 
 * processing  -- mechanism of managing shape modification via a user-editable resource file. 
 
-Message management is used for creating messages, filling them with various parameters and storing them in the trace file. This tool provides functionality for attaching messages to the shapes for deferred analysis of various run-time events. In this document only general principles of using Shape Healing will be described. For more detailed information please see the corresponding CDL files. 
+Message management is used for creating messages, filling them with various parameters and storing them in the trace file. This tool provides functionality for attaching messages to the shapes for deferred analysis of various run-time events. In this document only general principles of using Shape Healing will be described. For more detailed information please see the corresponding header files. 
 
 Tools responsible for analysis, fixing and upgrading of shapes can give the information about how these operations were performed. This information can be obtained by the user with the help of mechanism of status querying. 
 
@@ -70,7 +70,7 @@ if ( object.Status.. ( ShapeExtend_DONE ) ) {// something was done
 } 
 ~~~~~
 
-8 'DONE' and 8 'FAIL' flags, named ShapeExtend_DONE1 ... ShapeExtend_FAIL8, are defined for a detailed analysis of the encountered situation. Each method assigns its own meaning to each flag, documented in the CDL for that method. There are also three enumerative values used for testing several flags at a time: 
+8 'DONE' and 8 'FAIL' flags, named ShapeExtend_DONE1 ... ShapeExtend_FAIL8, are defined for a detailed analysis of the encountered situation. Each method assigns its own meaning to each flag, documented in the header for that method. There are also three enumerative values used for testing several flags at a time: 
 * *ShapeExtend_OK*   --     if no flags have been set; 
 * *ShapeExtend_DONE* -- if at least one ShapeExtend_DONEi has been set; 
 * *ShapeExtend_FAIL* -- if at least one ShapeExtend_FAILi has been set. 
index 958cf63..d31ed41 100644 (file)
@@ -40,7 +40,7 @@ These modules share common architecture and capabilities with other exchange mod
 In addition, Open Cascade provides tools to process models described using STEP: to reflect EXPRESS descriptions, to read, write and check data, to analyze the whole models ... Their key features are:
 
 * Modularity by sets of data types, which can be hierarchized to reflect the original modularity describing the resources and application protocols;
-* Implementation as CDL/C++ classes, providing comprehensive access to their members;
+* Implementation as C++ classes, providing comprehensive access to their members;
 * Early binding is basically used, providing good performance, easy installation and use as well as the capability to support non-compiled descriptions.
 
 This provides a natural way to deal with non-supported protocols when they share common definitions, as for geometry, which can then be exploited. The common frame, as the already supported data types, give a good foundation to go towards new uses of STEP, either on data definition (protocols from ISO or from industrial consortia) or on mapping with applicative data.
@@ -1105,14 +1105,14 @@ writer.Write(;Output.stp;);
 @subsection occt_step_4_1 Architecture of STEP Read and Write classes
 @subsubsection occt_step_4_1_1 General principles
 
-To perform data loading from a STEP file and to translate this data it is necessary to create correspondence between the EXPRESS schema and the structure of CDL classes. There are two possibilities to organize such correspondence: the so-called early binding and late binding. 
+To perform data loading from a STEP file and to translate this data it is necessary to create correspondence between the EXPRESS schema and the structure of the classes. There are two possibilities to organize such correspondence: the so-called early binding and late binding. 
 * Late binding means that the processor works with a description of the schema. The processor builds a dictionary of entities and can recognize and read any entity that is described in the schema. To change the behavior and the scope of processor based on late binding it is enough to change the description of the schema. However, this binding has some disadvantages (for example low speed of reading process). 
-* In case of early binding, the structure of CDL classes is created beforehand with the help of a specific automatic tool or manually. If the processor finds an entity that is not found in this schema, it will simply be ignored. The processor calls constructors of appropriate classes and their read methods. To add a new type in the scope of the processor it is necessary to create a class corresponding to the new entity. 
+* In case of early binding, the structure of the classes is created beforehand with the help of a specific automatic tool or manually. If the processor finds an entity that is not found in this schema, it will simply be ignored. The processor calls constructors of appropriate classes and their read methods. To add a new type in the scope of the processor it is necessary to create a class corresponding to the new entity. 
 
-The STEP processor is based on early binding principles. It means that specific classes for each EXPRESS type have been created with the help of an automatic tool from the EXPRESS schema. There are two CDL classes for each EXPRESS type. The first class (named the representing class) represents the STEP entity in memory. The second one (RW-class) is intended to perform the initialization of the representing class and to output data to an intermediate structure to be written in a STEP file. 
+The STEP processor is based on early binding principles. It means that specific classes for each EXPRESS type have been created with the help of an automatic tool from the EXPRESS schema. There are two classes for each EXPRESS type. The first class (named the representing class) represents the STEP entity in memory. The second one (RW-class) is intended to perform the initialization of the representing class and to output data to an intermediate structure to be written in a STEP file. 
 
 @subsubsection occt_step_4_1_2 Complex entities
-EXPRESS schema allows multiple inheritance. Entities that are built on the basis of multiple inheritance are called complex entities. Multiple inheritance is not available in CDL. EXPRESS enables any type of complex entities that can be inherited from any EXPRESS type. In the manner of early binding it is not possible to create a CDL class for any possible complex type. Thus, only widespread complex entities have corresponding representing classes and RW-classes that are created manually beforehand. 
+EXPRESS schema allows multiple inheritance. Entities that are built on the basis of multiple inheritance are called complex entities. EXPRESS enables any type of complex entities that can be inherited from any EXPRESS type. In the manner of early binding it is not possible to create a C++ class for any possible complex type. Thus, only widespread complex entities have corresponding representing classes and RW-classes that are created manually beforehand. 
 
 @subsection occt_step_4_2 Physical file reading
 Physical file reading consists of the following steps: 
@@ -1140,7 +1140,7 @@ The final phase is building a graph of references between entities. For each ent
 @subsection occt_step_4_3 How to add a new entity in scope of the STEP processor
 If it is necessary to read and translate a new entity by the STEP processor the Reader and Actor scope should be enhanced. Note that some actions to be made for adding a new type are different for simple and complex types. 
 The following steps should be taken: 
-* Create a CDL class representing a new entity. This can be *Stepxxx_NewEntity* class where xxx can be one of the following: 
+* Create a class representing a new entity. This can be *Stepxxx_NewEntity* class where xxx can be one of the following: 
      * Basic 
      * Geom 
      * Shape 
index 0d5f601..b2c5cd6 100644 (file)
@@ -15,7 +15,7 @@ This includes:
   * Definition of classes representing data objects. Data objects store their data using primitive OCAF attributes, taking advantage of OCAF mechanisms for Undo/Redo and persistence. At the same time they provide a higher level abstraction over the pure OCAF document structure (labels / attributes).
   * Organization of the data model as a hierarchical (tree-like) structure of objects.
   * Support of cross-references between objects within one model or among different models. In case of cross-model references the models should depend hierarchically.
-  * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without regenerating the schema. 
+  * Persistence mechanism for storing *TObj* objects in OCAF files, which allows storing and retrieving objects of derived types without writing additional code to support persistence. 
 
 This document describes basic principles of logical and physical organization 
 of TObj-based data models and typical approaches to implementation of classes representing model objects.