0032783: Documentation - Doxygen 1.9.3 generates corrupted HTML for dox/samples/ocaf.md

Fix incorrect/fragile Markdown syntax in samples/ocaf and user_guides/modeling_data.

dox/samples/ocaf.md

@@ -4,23 +4,19 @@
 ## Getting Started
 
 At the beginning of your development, you first define an application class by inheriting from the Application abstract class.
-  You only have to create and determine the resources of the application 
+You only have to create and determine the resources of the application for specifying the format of your documents (you generally use the standard one) and their file extension.
-  for specifying the format of your documents (you generally use the standard one)  and their file extension.  
 
 Then, you design the application data model by organizing attributes you choose among those provided with OCAF.
 You can specialize these attributes using the User attribute. For example, if you need a reflection coefficient,
 you aggregate a User attribute identified as a reflection coefficient
 with a Real attribute containing the value of the coefficient (as such, you don't define a new class).
 
-  If you need application specific data not provided with  OCAF, for example, 
+If you need application specific data not provided with OCAF, for example, to incorporate a finite element model in the data structure,
-  to incorporate a finite element model in the data structure,  
+you define a new attribute class containing the mesh, and you include its persistent homologue in a new file format.
-  you define a new attribute class containing the mesh, 
-  and you include its persistent homologue in a new file format.  
 
-  Once you have implemented the commands which create and modify the data structure 
+Once you have implemented the commands which create and modify the data structure according to your specification, OCAF provides you, without any additional programming:
-  according to your specification, OCAF provides you, without any additional programming:  
 
-  * Persistent  reference to any data, including geometric elements â€" several documents can be  linked with such reference;
+* Persistent reference to any data, including geometric elements - several documents can be linked with such reference;
 * Document-View association;
 * Ready-to-use functions such as:
   * Undo-redo;
@@ -31,8 +27,7 @@
 * Microsoft Foundation Classes (MFC) on Windows Motif on Sun;
 * Other commercial products such as Ilog Views.
 
-  You can also implement the user interface in the Java language using 
+You can also implement the user interface in the Java language using the Swing-based Java Application Desktop component (JAD) provided with OCAF.
-  the Swing-based Java Application Desktop component (JAD)  provided with OCAF.  
 
 ## An example of OCAF usage
 
@@ -42,27 +37,27 @@ In the <i> Formats </i> method, add the format of the documents, which need to b
 
 For example:
 
-~~~~
+~~~~{.cpp}
     void myApplication::Formats(TColStd_SequenceOfExtendedString& Formats)
     {
       Formats.Append(TCollection_ExtendedString ("OCAF-myApplication"));
     }
 ~~~~
 
-In the <i> ResourcesName</i> method, you only define the name of the resource file. This
+In the <i>ResourcesName</i> method, you only define the name of the resource file.
-file contains several definitions for the saving and opening mechanisms associated
+This file contains several definitions for the saving and opening mechanisms associated with each format and calling of the plug-in file.
-with each format and calling of the plug-in file.
 
-~~~~
+~~~~{.cpp}
     Standard_CString myApplication::ResourcesName()
     {
       return Standard_CString ("Resources");
     }
 ~~~~
 
-To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i> CSF_PluginDefaults</i>, which defines the path of the plug-in file, and <i> CSF_ResourcesDefault</i>, which defines the resource file:
+To obtain the saving and opening mechanisms, it is necessary to set two environment variables: <i>CSF_PluginDefaults</i>, which defines the path of the plug-in file,
+and <i>CSF_ResourcesDefault</i>, which defines the resource file:
 
-~~~~
+~~~~{.cpp}
     SetEnvironmentVariable ("CSF_ResourcesDefaults", myDirectory);
     SetEnvironmentVariable ("CSF_PluginDefaults", myDirectory);
 ~~~~
@@ -72,8 +67,7 @@ The name of the plugin file must be <i>Plugin</i>.
 
 ### Resource File
 
-The resource file describes the documents (type and extension) and 
+The resource file describes the documents (type and extension) and the type of data that the application can manipulate
-the type of data that the application can manipulate 
 by identifying the storage and retrieval drivers appropriate for this data.
 
 Each driver is unique and identified by a GUID generated, for example, with the <i>uuidgen</i> tool in Windows.
@@ -88,7 +82,6 @@ Five drivers are required to use all standard attributes provided within OCAF:
 
 These drivers are provided as plug-ins and are located in the <i>PappStdPlugin</i> library.
 
-
 For example, this is a resource file, which declares a new model document OCAF-MyApplication:
 
 ~~~~
@@ -104,12 +97,11 @@ OCAF-MyApplication.AttributeRetrievalPlugin: 47b0b827-d931-11d1-b5da-00a0c906436
    
 ### Plugin File
 
-The plugin file describes the list of required plug-ins to run the application and the
+The plugin file describes the list of required plug-ins to run the application and the libraries in which plug-ins are located.
-libraries in which plug-ins are located.
 
 You need at least the <i>FWOSPlugin</i> and the plug-in drivers to run an OCAF application.
 
-The syntax of each item is <i> Identification.Location Library_Name, </i> where:
+The syntax of each item is <i>Identification.Location Library_Name</i>, where:
 * Identification is GUID.
 * Location defines the location of the Identification (where its definition is found).
 * Library_Name is the name (and path to) the library, where the plug-in is located.
@@ -128,19 +120,18 @@ ad696002-5b34-11d1-b5ba-00a0c9064368.Location: PAppStdPlugin
 
 ## Implementation of Attribute Transformation in a HXX file
 
-~~~~
+~~~~{.cpp}
-\#include <TDF_Attribute.hxx>
+#include <TDF_Attribute.hxx>
 
-\#include <gp_Ax3.hxx>
+#include <gp_Ax3.hxx>
-\#include <gp_Pnt.hxx>
+#include <gp_Pnt.hxx>
-\#include <gp_Vec.hxx>
+#include <gp_Vec.hxx>
-\#include <gp_Trsf.hxx>
+#include <gp_Trsf.hxx>
 
 //! This attribute implements a transformation data container
 class MyPackage_Transformation : public TDF_Attribute
 {
-public:
+public: //!@ name Static methods
-  //!@ name Static methods 
 
   //! The method returns a unique GUID of this attribute.
   //! By means of this GUID this attribute may be identified
@@ -151,12 +142,12 @@ public:
   //! The found or created attribute is returned.
   Standard_EXPORT static Handle(MyPackage_Transformation) Set (const TDF_Label theLabel);
 
-  //!@ name Methods for access to the attribute data 
+public: //!@ name Methods for access to the attribute data
 
   //! The method returns the transformation.
   Standard_EXPORT gp_Trsf Get () const;
 
-  //!@ name Methods for setting the data of transformation 
+public: //!@ name Methods for setting the data of transformation
 
   //! The method defines a rotation type of transformation.
   Standard_EXPORT void SetRotation (const gp_Ax1& theAxis, Standard_Real theAngle);
@@ -179,7 +170,7 @@ public:
   //! The method defines a complex type of transformation from one coordinate system to another.
   Standard_EXPORT void SetTransformation (const gp_Ax3& theCoordinateSystem1, const gp_Ax3& theCoordinateSystem2);
 
-  //!@ name Overridden methods from TDF_Attribute 
+public: //!@ 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.
@@ -200,7 +191,7 @@ public:
   //! Prints the content of this attribute into the stream.
   Standard_EXPORT Standard_OStream& Dump(Standard_OStream& theOS);
 
-  //!@ name Constructor 
+public: //!@ name Constructor
 
   //! The C++ constructor of this attribute class.
   //! Usually it is never called outside this class.
@@ -228,7 +219,7 @@ private:
 ## Implementation of Attribute Transformation in a CPP file
 
 ~~~~{.cpp}
-\#include <MyPackage_Transformation.hxx> 
+#include <MyPackage_Transformation.hxx>
 
 //=======================================================================
 //function : GetID
@@ -389,7 +380,7 @@ void MyPackage_Transformation::SetScale(const gp_Pnt& thePoint, const Standard_R
 //=======================================================================
 //function : SetTransformation
 //purpose  : The method defines a complex type of transformation
-//           from one coordinate system to another.
+//           from one coordinate system to another
 //=======================================================================
 void MyPackage_Transformation::SetTransformation (const gp_Ax3& theCoordinateSystem1,
                                                   const gp_Ax3& theCoordinateSystem2)
@@ -465,54 +456,54 @@ void MyPackage_Transformation::Paste(const Handle(TDF_Attribute)& theAttribute,
 //function : Dump
 //purpose  : Prints the content of this attribute into the stream.
 //=======================================================================
-Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const 
+Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& theOS) const
 {
-  anOS = "Transformation: "; 
+  anOS << "Transformation: ";
   switch (myType)
   {
     case gp_Identity:
     {
-      anOS = "gp_Identity"; 
+      anOS << "gp_Identity";
       break;
     }
     case gp_Rotation:
     {
-      anOS = "gp_Rotation"; 
+      anOS << "gp_Rotation";
       break;
     }
     case gp_Translation:
     {
-      anOS = "gp_Translation"; 
+      anOS << "gp_Translation";
       break;
     }
     case gp_PntMirror:
     {
-      anOS = "gp_PntMirror"; 
+      anOS << "gp_PntMirror";
       break;
     }
     case gp_Ax1Mirror:
     {
-      anOS = "gp_Ax1Mirror"; 
+      anOS << "gp_Ax1Mirror";
       break;
     }
     case gp_Ax2Mirror:
     {
-      anOS = "gp_Ax2Mirror"; 
+      anOS << "gp_Ax2Mirror";
       break;
     }
     case gp_Scale:
     {
-      anOS = "gp_Scale"; 
+      anOS << "gp_Scale";
       break;
     }
     case gp_CompoundTrsf:
     {
-      anOS = "gp_CompoundTrsf"; 
+      anOS << "gp_CompoundTrsf";
       break;
     }
     case gp_Other:
     {
-      anOS = "gp_Other"; 
+      anOS << "gp_Other";
       break;
     }
   }
@@ -523,14 +514,17 @@ Standard_OStream& MyPackage_Transformation::Dump(Standard_OStream& anOS) const
 //function : MyPackage_Transformation
 //purpose  : A constructor.
 //=======================================================================
-MyPackage_Transformation::MyPackage_Transformation():myType(gp_Identity){ 
+MyPackage_Transformation::MyPackage_Transformation()
-
+: myType (gp_Identity)
+{
+  //
 }
 ~~~~
 
 ## Implementation of typical actions with standard OCAF attributes.
 
-There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'. They present typical actions with OCAF services (mainly for newcomers). 
+There are four sample files provided in the directory 'OpenCasCade/ros/samples/ocafsamples'.
+They present typical actions with OCAF services (mainly for newcomers).
 The method *Sample()* of each file is not dedicated for execution 'as is', it is rather a set of logical actions using some OCAF services.
 
 ### TDataStd_Sample.cxx
@@ -591,4 +585,3 @@ The following scenario is used:
 - creating a Fillet (using the selected edges) and pushing the result as a modification of Box1;
 - creating a Cut (Box1, Box2) as a modification of Box1 and push it in DF;
 - recovering the result from DF.
-