0023962: Moving OCCT documentation to sources

OCCT documentation (Overview and User Guides) has been converted from MS Word files to text-based MarkDown format and added to OCCT sources, in the new subfolder 'dox'. The HTML and PDF articles can be generated from the sources using Doxygen and MiKTeX. See the file OCCT_Docs_HowTo.md for details on the new documentation system.

This branch includes:

- new folder structure for Open CASCADE documentation
- sources of almost all OCCT User Guides and Overview
- tcl and bat scripts, which allow to generate HTML and PDF articles

dox/dev_guides/building/automake.md

@@ -0,0 +1,69 @@
+Building with Automake {#dev_guides__building__automake}
+======================
+
+This file describes steps to build OCCT libraries from complete source
+archive on Linux with GNU build system (Autotools).
+
+If you are building OCCT from bare sources (as in Git repository), or do some 
+changes affecting CDL files, you need to use WOK to re-generate header files
+and build scripts / projects. See file \ref wok "WOK" for instructions.
+
+Before building OCCT, you need to install required third-party libraries; see
+OCCT_Build3rdParty_Linux.pdf for instructions.
+
+Note that during compilation by makefiles on some Linux OS on a station with 
+NVIDIA video card you may experience problems because the installation 
+procedure of NVIDIA video driver removes library libGL.so included in package 
+libMesaGL from directory /usr/X11R6/lib and places this library libGL.so in 
+directory /usr/lib. However, libtool expects to find the library in directory 
+/usr/X11R6/lib, which causes compilation crash (See /usr/X11R6/lib/libGLU.la). 
+
+To prevent this, suggest making links: 
+
+ ln -s /usr/lib/libGL.so /usr/X11R6/lib/libGL.so 
+ ln -s /usr/lib/libGL.la /usr/X11R6/lib/libGL.la 
+
+  1.In OCCT root folder, launch build_configure script 
+
+   This will generate files configure and Makefile.in for your system.
+
+  2.Go to the directory where OCCT will be built, and run configure to generate
+   makefiles.
+
+   $CASROOT/configure \<FLAGS\>
+
+   Where \<FLAGS\> is a set of options.
+   The following flags are mandatory:
+
+   * --with-tcl=  defines location of tclConfig.sh
+   * --with-tk=  defines location of tkConfig.sh
+   * --with-freetype=  defines location of installed FreeType product
+   * --prefix= defines location for the installation of OCCT binaries
+
+   Additional flags:
+
+   * --with-gl2ps=  defines location of installed gl2ps product
+   * --with-freeimage=  defines location of installed FreeImage product
+   * --with-tbb-include= defines location of tbb.h
+   * --with-tbb-library=  defines location of libtbb.so
+   * --enable-debug=       yes: includes debug information, no: does not include debug information
+   * --enable-production=   yes: switches code optimization, no: switches off code optimization
+   * --disable-draw - allows OCCT building without Draw.
+
+   If location of FreeImage, TBB, and Gl2Ps is not specified, OCCT will be
+   built without these optional libraries.
+
+   
+   Attention: 64-bit platforms are detected automatically.
+
+   Example:
+
+   > ./configure -prefix=/PRODUCTS/occt-6.5.5 --with-tcl=/PRODUCTS/tcltk-8.5.8/lib --with-tk=/PRODUCTS/tcltk-8.5.8/lib --with-freetype=/PRODUCTS/freetype-2.4.10 --with-gl2ps=/PRODUCTS/gl2ps-1.3.5 --with-freeimage=/PRODUCTS/freeimage-3.14.1 --with-tbb-include=/PRODUCTS/tbb30_018oss/include --with-tbb-library=/PRODUCTS/tbb30_018oss/lib/ia32/cc4.1.0_libc2.4_kernel2.6.16.21
+
+  3.If configure exits successfully, you can build OCCT with make command.
+
+   > make -j8 install
+
+To start DRAW, launch
+
+   > draw.sh

dox/dev_guides/building/cmake.md

@@ -0,0 +1,77 @@
+Building with CMake {#dev_guides__building__cmake}
+===================
+
+This file describes steps to build OCCT libraries from complete source package
+with CMake. CMake is free software that can create GNU Makefiles, KDevelop, 
+XCode, and Visual Studio project files. Version 2.6 or above of CMake is 
+required.
+
+If you are building OCCT from bare sources (as in Git repository), or do some 
+changes affecting CDL files, you need to use WOK to re-generate header files
+and build scripts / projects. See file \ref wok "WOK" for instructions.
+
+Before building OCCT, you need to install required third-party libraries; see
+instructions for your platform on Resources page at http://dev.opencascade.org
+
+1.  Decide on location of build and install directories.
+    
+    The build directory is the one where intermediate files will be created 
+    (projects / makefiles, objects, binaries).
+    The install directory is the one where binaries will be installed after 
+    build, along with header files and resources required for OCCT use in 
+    applications.
+    
+    OCCT CMake scripts assume use of separate build and one install directories
+    for each configuration (Debug or Release).
+    
+    It is recommended to separate build and install directories from OCCT 
+    source directory, for example:
+    
+       /user/home/occt/ros - sources
+       /user/home/tmp/occt-build-release - intermediate files (release)
+       /user/home/occt-install-release - installed binaries (release)
+    
+2.  Run CMake indicating path to OCCT sources (ros subdirectory) and selected build directory. 
+    It is recommended to use GUI tools provided by CMake: cmake-gui on Windows
+    and Mac, ccmake on Linux.
+    
+    Example:
+    
+       Linux> cd /user/home/occt-install-release
+       Linux> ccmake /user/home/occt/ros
+    
+3. Run Configure
+    
+    You will likely get CMake errors due to missing paths to 3rd-party 
+    libraries. This is normal; proceed with configuration as follows.
+    
+4. Check parameters shown by CMake, set them in accordance with your 
+    environment, and repeat Configure until it runs without error:
+    
+    - 3RDPARTY_DIR: path to directory whethe 3rd-party libraries are installed
+      (for the cases when they are not in default locations, or on Windows)
+    - 3RDPARTY_USE_\<library\>: select to use optional libraries
+    - Other options in 3RDPARTY group can be used to fine-tune paths to 
+      3rd-party libraries
+    
+    - BUILD_TYPE: configuration to build (Debug or Release)
+    - BUILD_BITNESS: bitness (32 or 64)
+    - BUILD_TOOLKITS: optional string containing list of toolkits to be built
+      in addition to those included in completely built modueles
+    - BUILD_\<module\>: select to build corresponding OCCT module
+    
+    - INSTALL_DIR: directory to install OCCT
+    - INSTALL_\<library\>: select to copy corresponding 3rd-party library to OCCT
+      install dir
+
+5. Run Generate
+
+    This will create makefiles or project files for your build system.
+
+6. Build OCCT:
+
+    - on Windows with MSVC: open solution OCCT.sln and build it, when build project INSTALL_ALL explicitly to have binaries and headers installed
+    - on Linux with make files: run 'make install'
+
+ 
+ 

dox/dev_guides/building/code_blocks.md

@@ -0,0 +1,64 @@
+Building with Code::Blocks on Mac OS X {#dev_guides__building__code_blocks}
+======================================
+
+This file describes steps to build OCCT libraries from complete source package
+on Mac OS X with Code::Blocks.
+
+If you are building OCCT from bare sources (as in Git repository), or do some 
+changes affecting CDL files, you need to use WOK to re-generate header files
+and build scripts / projects. See file \ref wok "WOK" for instructions.
+
+Before building OCCT, you need to install required third-party libraries; see
+OCCT_Build3rdParty_OSX.pdf for details.
+
+1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType) in file 
+   custom.sh located in \<OCCT_ROOT_DIR\>. For this:
+
+   1.1. Add paths to the includes in variable "CSF_OPT_INC";
+
+   1.2. Add paths to the binary libraries in variable  "CSF_OPT_LIB64";
+   
+   All paths should be separated by ":" symbol. 
+
+2. Add paths to the optional 3rd-party libraries (TBB, gl2ps and FreeImage) 
+   in the aforementioned environment variables "CSF_OPT_INC" and 
+   "CSF_OPT_LIB64" from file custom.sh.
+
+   If you want to build OCCT without the optional libraries perform the 
+   following steps:
+
+   2.1 Disable unnecessary library in custom.sh by setting the corresponding 
+       variable HAVE_\<LIBRARY_NAME\> to "false". 
+
+       export HAVE_GL2PS=false
+
+   2.2 Remove this library from Linker settings in Code::Blocks for each project 
+       that uses it: right click on the required project, choose "Build options", 
+       go to "Linker settings" tab in the opened window , select unnecessary 
+       libraries and click "Delete" button.
+
+3. Open Terminal application
+
+4. Enter \<OCCT_ROOT_DIR\>:
+
+   cd \<OCCT_ROOT_DIR\>
+
+5. To start Code::Blocks, run the command /codeblocks.sh
+
+6. To build all toolkits, click "Build->Build workspace" in the menu bar.
+
+
+To start DRAWEXE, which has been built with Code::Blocks on Mac OS X, perform 
+the following steps:
+
+1. Open Terminal application
+
+2. Enter \<OCCT_ROOT_DIR\>:
+
+   cd \<OCCT_ROOT_DIR\>
+
+3. Run script
+
+   ./draw_cbp.sh cbp [d]
+
+   Option "d" is used if OCCT has been built in Debug mode.

dox/dev_guides/building/msvc.md

@@ -0,0 +1,31 @@
+Building with MS Visual C++ {#dev_guides__building__msvc}
+===========================
+
+This file describes steps to build OCCT libraries from complete source
+archive on Windows with MS Visual C++. 
+
+If you are building OCCT from bare sources (as in Git repository), or do some 
+changes affecting CDL files, you need to use WOK to re-generate header files
+and build scripts / projects. See file \ref wok "WOK" for instructions.
+
+Before building OCCT, you need to install required third-party libraries; see
+OCCT_Build3rdParty_Windows.pdf for instructions.
+
+1. Edit file custom.bat to define environment: 
+
+   - VCVER - version of Visual Studio (vc8, vc9, vc10 or vc11), 
+             and relevant VCVARS path
+   - ARCH - architecture (32 or 64), affects only PATH variable for execution
+   - HAVE_* - flags to enable or disable use of optional third-party products
+   - CSF_OPT_* - paths to search for includes and binaries of all used 
+                 third-party products
+
+2. Launch msvc.bat to start Visual Studio with all necessary environment 
+   variables defined.
+
+   Note: the MSVC project files are located in folders adm\\msvc\\vc[9-11].
+   Binaries are produced in win32 or win64 folders.
+
+3. Build with Visual Studio
+
+To start DRAW, launch draw.bat.

dox/dev_guides/building/xcode.md

@@ -0,0 +1,71 @@
+Building with Xcode {#dev_guides__building__xcode}
+===================
+
+This file describes steps to build OCCT libraries from complete source package
+on Mac OS X with Xcode.
+
+If you are building OCCT from bare sources (as in Git repository), or do some 
+changes affecting CDL files, you need to use WOK to re-generate header files
+and build scripts / projects. See file \ref wok "WOK" for instructions.
+
+Before building OCCT, you need to install required third-party libraries; see
+OCCT_Build3rdParty_OSX.pdf for details.
+
+1. Add paths to the mandatory 3rd-party products (Tcl/Tk and FreeType) 
+   in file custom.sh located in \<OCCT_ROOT_DIR\>. For this:
+
+   1.1. Add paths to the includes in variable "CSF_OPT_INC";
+
+   1.2. Add paths to the binary libraries in variable  "CSF_OPT_LIB64";
+
+   All paths should be separated by ":" symbol. 
+
+2. Add paths to the optional 3rd-party libraries (TBB, gl2ps and FreeImage) 
+   in the aforementioned environment variables "CSF_OPT_INC" and 
+   "CSF_OPT_LIB64" from file custom.sh.
+
+   If you want to build OCCT without the optional libraries perform the 
+   following steps:
+
+   2.1 Disable unnecessary library in custom.sh by setting the corresponding 
+       variable HAVE_<LIBRARY_NAME> to "false". 
+
+       export HAVE_GL2PS=false
+
+   2.2 Remove this library from Project navigator in Xcode for each project that 
+       uses it: choose the required project, right click on the unnecessary 
+       library and select "Delete" button.
+
+3. Open Terminal application.
+
+4. Enter \<OCCT_ROOT_DIR\>:
+
+   cd \<OCCT_ROOT_DIR\>
+
+5. To start Xcode, run the command  /xcode.sh
+
+6. To build a certain toolkit, select it in "Scheme" drop-down list in Xcode 
+   toolbar, press "Product" in the menu and click "Build" button. 
+
+   To build the entire OCCT, create a new empty project (select "File -> 
+   New -> Project -> "Empty project" in the menu. Input the project name, 
+   e.g. "OCCT", click "Next" and "Create" buttons). Drag and drop the "OCCT" 
+   folder in the created "OCCT" project in the Project navigator. Select 
+   "File -> New -> Target -> Aggregate" in the menu. Enter the project name 
+   (e.g. "OCCT") and click "Finish". The "Build Phases" tab will open.  
+   Click "+" button to add the necessary toolkits to the target project. 
+   It is possible to select all toolkits by pressing "Command+A" combination. 
+
+To start DRAWEXE, which has been built with Xcode on Mac OS X, perform the following steps:
+
+1. Open Terminal application
+
+2. Enter \<OCCT_ROOT_DIR\>:
+
+   cd \<OCCT_ROOT_DIR\>
+
+3. Run script
+
+   ./draw_cbp.sh xcd [d]
+
+   Option "d" is used if OCCT has been built in Debug mode.

dox/dev_guides/dev_guides.md

@@ -0,0 +1,102 @@
+ Developer Guides {#dev_guides}
+================
+
+@section OCCT_OVW_SECTION1 Source Repository
+
+This directory contains sources of Open CASCADE Technology (OCCT), a collection
+of C++ libraries providing services for 3D surface and solid modeling, CAD data
+exchange, and visualization. OCCT can be best applied in development of
+software dealing with 3D modeling (CAD), manufacturing / measuring (CAM) or
+numerical simulation (CAE).
+
+The OCCT code is subject to the Open CASCADE Technology Public License Version
+6.6 (the "License"). You may not use the content of the relevant files except in
+compliance with the License. Please see the LICENSE file or obtain a copy of the
+License at http://www.opencascade.org and read it completely before using this
+software.
+
+@section OCCT_OVW_SECTION11 Building OCCT Libraries
+
+The source package of the Open CASCADE Technology including the source files of samples
+and tools and the set of building procedures is available for self-dependent preparation
+binary files on UNIX and Windows platforms. 
+
+In order to build OCCT libraries from these sources for use in your program, 
+you need to:
+
+1. Install the required third-party libraries.
+
+   Follow the instructions provided in the documents titled "Building 3rd party
+   products for OCCT" on http://dev.opencascade.org/?q=home/resources for
+   choice of the needed libraries, their installation and building.
+
+2. If you use OCCT sources from Git repository or do come changes affecting
+   CDL files or dependencies of OCCT toolkit, update header files generated 
+   from CDL, and regenerate build scripts for your environment using WOK.
+   See \subpage dev_guides__wok "WOK" for details.
+
+   Skip to step 3 if you use complete source package (e.g. official OCCT 
+   release) without changes in CDL.
+
+3. Build using your preferred build tool.
+   - \subpage dev_guides__building__automake "Building on Linux with Autotools"
+   - \subpage dev_guides__building__cmake "Building with CMake (cross-platform)"
+   - \subpage dev_guides__building__code_blocks "Building on Mac OS X with Code::Blocks"
+   - \subpage dev_guides__building__msvc "Building on Windows with MS Visual Studio 2005-2012"
+   - \subpage dev_guides__building__xcode "Building on Mac OS X with Xcode"
+
+The current version of OCCT can be consulted in the file src/Standard/Standard_Version.hxx
+
+@section OCCT_OVW_SECTION111 Automatic tests
+
+OCCT automatic testing system is integrated with @ref draw "DRAW Test Harness",
+a console application based on Tcl (a scripting language).
+All tests are run from DRAW command prompt (run **draw.bat** or 
+**draw.sh** to start it).
+
+Standard OCCT tests are located in subdirectory **tests** of the OCCT root 
+folder. This location is set as default at DRAW start (see environment variable 
+_CSF_TestScriptsPath_ defined in **src/DrawResources/DrawDefaults**).
+
+The tests are organized in three levels:
+- Group: a group of related test grids, usually testing a particular subset of OCCT functionality (e.g. *blend*). 
+- Grid: a set of test cases within a group, usually aimed at testing a particular aspect or mode of execution of the relevant functionality (e.g. *buildevol*).
+- Test case: a script implementing an individual test (e.g. *K4*).
+
+To run all tests, type command *testgrid*:
+
+    Draw[]\> testgrid
+
+For running only a group or a grid of tests, give additional arguments indicating the group and (if needed) the grid name:
+
+    Draw[]\> testgrid blend simple
+
+As the tests progress, the result of each test case is reported. 
+At the end of the log a summary of test cases is output, including the list of 
+detected regressions and improvements, if any.
+The tests are considered as non-regressive if only OK, BAD (i.e. known problem), 
+and SKIPPED (i.e. not executed, typically because of lack of a data file) 
+statuses are reported. 
+
+To run a single test, type command 'test' followed by the names of 
+group, grid, and test case. 
+
+    Draw[1]\> test blend simple A1
+    CASE blend simple A1: OK
+
+To see intermediate commands and their output during the test execution, 
+add one more argument '-echo' at the end of the command line, or type 'dlog get'
+after test completion. 
+
+For more information consult \subpage dev_guides__tests "Automatic Testing System"
+
+@section OCCT_OVW_SECTION1112 CDL Overview
+
+CDL is the component definition language of the Open CASCADE Technology (OCCT) programming platform. 
+Some components, which CDL allows you to create, are specific to OCCT application architecture. 
+
+For more information consult \subpage dev_guides__cdl "Component Definition Language Developer's Guide"
+
+@section OCCT_OVW_SECTION1113 Documentation Overview
+
+\subpage dev_guides__documentation "Documentation Developer's Guide"

dox/dev_guides/documentation/documentation.md

@@ -0,0 +1,531 @@
+ Documentation  {#dev_guides__documentation}
+=================
+
+@section  OCCT_DM_SECTION_1 Introduction
+
+This document provides practical guidenes for generation and editing of OCCT user documentation.
+
+@section  OCCT_DM_SECTION_2 Prerequisites
+
+<b>Tcl/Tk</b>
+The lates version: http://www.tcl.tk/software/tcltk/download.html
+
+<b>Doxygen</b> ( >= 1.8.4 ) 
+The latest version: http://www.stack.nl/~dimitri/doxygen/download.html
+
+<b>MathJax</b> (used for rendering math formulas in browser). Download it for local installation or use the MathJax Content Delivery Network.  \(read 
+@htmlonly <a href="#OCCT_DM_SECTION_A_9">Formulas</a> @endhtmlonly paragraph for more detailed description\). 
+The latest version: http://www.mathjax.org/download/
+
+<b>MiKTeX</b> or equivalent tool (used for PDF document creation)
+Latest version: http://miktex.org/download
+
+@section OCCT_DM_SECTION_2_1 Documentation Generation
+
+Run gendoc.bat from OCCT directory to generate all articles are defined in FILES.txt:
+
+gendoc.bat options:
+
+  * -html                : To generate HTML files (cannot be used with -pdf);
+  * -pdf                 : To generate PDF files (cannot be used with -html);
+  * -m=<modules_list>    : Specifies list of articles to generate. If it is not specified, all files, mentioned in FILES.txt are processed;
+  * -l=<document_name>   : Specifies the article caption for a single document;
+  * -h                   : Prints help message;
+  * -v                   : Specifies the Verbose mode (info on all script actions is shown).
+
+If you run the command without arguments (like example above) it will generate HTML documentation 
+for all articles are defined into FILES.txt.
+
+**Note**: the generation process generates PDF files for each article, 
+but in html case it generates common Html page with references to the ones.
+
+For generation of specific article you need:
+  * have it's name with relative path (from \%OCCDIR\%/dox/ to the file) contained in FILES.txt 
+  (is located into \%OCCDIR\%/dox/ directory).
+
+@verbatim
+devs_guid/documentation/documentation.md
+@endverbatim
+
+where documentation .md is name of article and devs_guid/documentation/ is relative path of it
+
+  * use this name with -m option in the generation process:
+
+@verbatim
+% gen.bat -html -m=devs_guid/documentation/documentation.md
+@endverbatim
+
+Multiple files are separated with comma:
+
+@verbatim
+% gen.bat -html -m=MD_FILE_1,MD_FILE_2
+@endverbatim
+
+To sepcify a article name with -l option, use tcl list to prevent whitespaces incorrect interpretation:
+
+@verbatim
+% gen.bat -pdf -m=MD_FILE_1 -l=[list MD File 1 Label]
+@endverbatim
+
+@section  OCCT_DM_SECTION_3 Documentation Conventions
+
+This section contains information about conventions in the field of OCCT documentation file format, 
+structure of documentation directories, etc.
+
+@subsection  OCCT_DM_SECTION_3_1 File Format
+
+It is proposed to use MarkDown file format for easy maintainance of generic text documents. 
+The MarkDown files have a "*.md" extension and are based on rules desribed in 
+@htmlonly <a href="#OCCT_DM_SECTION_A">Document Syntax</a> @endhtmlonly section.
+
+@subsection  OCCT_DM_SECTION_3_2 Directory Structure
+
+![](/devs_guide/documentation/images/documentation_image001.png)
+
+Every separate article has own folder if images are used in it. These images 
+are stored into "images" subfolder.
+
+If you want to use the same image for several articles, you can place the one into "dox/resources" folder.
+
+**Note**: Every article can use any image that is used by others articles. To avoid incorrect image
+displaying, use relative path to the image (starting from dox folder). For instance
+@verbatim
+![](/devs_guide/snv/images/snv_image001.svg)
+@endverbatim
+
+Result of generation of the documentation is:
+
+%OCCT_DIR% / doc         - a folder for generated articles;
+            * html/             - a directory for generated HTML pages;
+            * pdf/              - a directory for generated PDF files.
+
+@section  OCCT_DM_SECTION_4 Adding a New Article
+
+ - Place a new article into folder that is chosen taking into account the place of the article 
+at the hierarchy of the documentation. For instance the article about "using SVN working with OCCT 
+source code" (svn.md - the file of the article) might be placed into /dox/devs_guide/ . If the article has images then you may create
+the own folder of the article and subfolder in it for images. For instance
+*/dox/devs_guide/svn/ - for svn.md file
+*/dox/devs_guide/svn/images/ - for images
+
+ - Update dox/FILES.txt to add relative path to svn.md. For instance
+@verbatim
+devs_guide/snv/svn.md
+@endverbatim
+
+**Note**: the place of the relative path to an article is connected with the place
+into treeview of html version.
+
+
+Note, that you should specify a file tag, not the document name. 
+See <a href="#OCCT_DM_SECTION_A_1">Header section</a> for details.
+
+@section  OCCT_DOC_SECTION_5 Additional Resources
+
+More information about OCCT can be found at http://www.opencascade.org
+
+The information on formula syntax can be found at: 
+http://en.wikipedia.org/wiki/Help:Displaying_a_formula
+
+More information on MarkDown and Doxygen syntax can be found at:
+http://www.stack.nl/~dimitri/doxygen/manual
+
+
+@section  OCCT_DM_SECTION_A Appendix 1: Document Syntax
+
+Each OCCT document file in *.md format has a simple structure.
+It can contain: 
+
+| Content type      | Obligation            |
+| :---------------- | :-------------------: |
+| Header            | M                     |
+| Footer            | M                     |
+| Plain text        | O                     |
+| List              | O                     |
+| Table             | O                     |
+| Code              | O                     |
+| Formula           | O                     |
+| Image             | O                     |
+| Page numbers      | M (auto generation)   |
+| Table of contents | M (auto generation)   |
+
+The legend:
+
+  * M is for Mandatory
+  * O is for Optional
+
+@subsection  OCCT_DM_SECTION_A_1 Text Caption (a header)
+
+headings of different levels can be specified with the following code:
+
+@verbatim
+Header 1  {#header1}
+=======
+@endverbatim
+
+  to get
+
+ Header 1
+=========
+
+  and with the following code:
+
+@verbatim
+Header 2 {#header2}
+--------
+@endverbatim
+
+to get 
+
+Header 2
+---------
+
+Where a word in curly braces is a MarkDown-style reference, which can be used in table of contents.
+If you would like to have the table of contents, it is recommended to use \@section, 
+\@subsection and \@subsubsection pages instead of MarkDown headers as follows:
+
+@verbatim
+  @section Section_Name Section Header
+  @subsection SubSection_Name SubSection Header
+  @subsubsection SubSubSection_Name SubSubSection Header
+@endverbatim
+
+@subsection OCCT_DM_SECTION_A_2 Plain Text
+
+Plain text is a text in a notepad-like format. To insert special symbols, 
+like \< , \> or \\, prepend them with \\ character: \\\<, \\\>, \\\\ 
+To emphasize some words, write one pair of asterisks ( * ) or underscores ( _ ) across the word 
+to make it *italic* and two pairs of these symbols to make a word **Bold**.
+
+@subsection OCCT_DM_SECTION_A_3 Lists
+
+To create a bulleted list, start each line with a hyphen or an asterisk, 
+followed by a space. List items can be nested. This code:
+
+@verbatim
+  * Bullet 1
+  * Bullet 2
+    * Bullet 2a
+    * Bullet 2b
+  * Bullet 3
+@endverbatim
+
+  produces this list:
+
+  * Bullet 1
+  * Bullet 2
+    * Bullet 2a
+    * Bullet 2b
+  * Bullet 3  
+
+To create a numbered list, start each line with number and a period, then a space. Thus this code 
+
+@verbatim
+  1. ListItem_1
+  2. ListItem_2
+  3. ListItem_3
+@endverbatim
+
+  produces this list:
+
+  1. ListItem_1
+  2. ListItem_2
+  3. ListItem_3
+
+It is recommended to indent lists with 2 spaces.
+
+@subsection  OCCT_DM_SECTION_A_4 Tables
+
+A table consists of a header line, a separator line, and at least one row line. 
+Table columns are separated by the pipe (|) character. The following example: 
+
+@verbatim
+First Header  | Second Header
+------------- | -------------
+Content Cell  | Content Cell 
+Content Cell  | Content Cell 
+@endverbatim
+
+  will produce the following table:
+
+First Header | Second Header
+------------ | -------------
+Content Cell | Content Cell 
+Content Cell | Content Cell 
+
+Column alignment can be controlled via one or two colons at the header separator line: 
+
+@verbatim
+| Right | Center | Left  |
+| ----: | :----: | :---- |
+| 10    | 10     | 10    |
+| 1000  | 1000   | 1000  |
+@endverbatim
+
+which will looks as follows:
+
+| Right | Center | Left  |
+| ----: | :----: | :---- |
+| 10    | 10     | 10    |
+| 1000  | 1000   | 1000  |
+
+@subsection  OCCT_DM_SECTION_A_5 Code Blocks
+
+It is recommended to indent a code lines with 4 spaces.
+A fenced code block does not require indentation, and is defined by a pair of "fence lines". 
+Such line consists of 3 or more tilde (~) characters on a line. 
+The end of the block should have the same number of tildes. Here is an example:
+
+~~~~~~~~~~~~~~~~~~~~~~~
+  a one-line code block
+~~~~~~~~~~~~~~~~~~~~~~~
+
+By default the output is the same as for a normal code block.
+To highlight the code, the developer has to indicate the typical file extension, 
+which corresponds to the programming language, after the opening fence. 
+For highlighting according to the C++ language, for instance,  write the following code (the curly braces and dot are optional): 
+
+@verbatim
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
+    int func(int a,int b) { return a*b; }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+@endverbatim
+
+which will produce:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} 
+    int func(int a,int b) { return a*b; }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Verbatim content can be written by using framing \@verbatim \@endverbatim . For instance
+
+@verbatim
+  verbatim text
+@endverbatim
+
+@subsection  OCCT_DM_SECTION_A_6 References
+
+To insert a reference to a website, it is proposed to write a URL. For example: http://en.wikipedia.org
+To insert a reference to another part of the same document, the developer can write:
+
+@verbatim
+  @htmlonly 
+    <a href="#OCCT_DOC_SECTION_5">Doxygen Configuration file</a>
+  @endhtmlonly 
+@endverbatim
+
+to get a link to paragraph : @htmlonly <a href="#OCCT_DOC_SECTION_5">Doxygen configuration</a> @endhtmlonly 
+
+@subsection  OCCT_DM_SECTION_A_7 Images
+
+To insert image into document the developer can write the following code(in Doxygen-style):
+@verbatim
+![alt-caption](relative/path/to/image/image001.svg "Image Caption")
+@endverbatim
+
+This code tells Doxygen to insert a picture right in the place this code was written. Like this:
+@verbatim
+![](/resources/occt_logo.png "OCCT logo")
+@endverbatim
+
+![](/resources/occt_logo.png "OCCT logo")
+ 
+@subsection  OCCT_DM_SECTION_A_8 Table Of Contents
+
+To get the table of contents at the beginning of the document, write \@tableofcontents tag. 
+But it is not needed now because TreeView option for HTML is used.
+The TOC in the PDF document will be generated automatically.
+
+@subsection  OCCT_DM_SECTION_A_9 Formulas
+
+Formulas within documents will be generated using MathJax tool.
+
+A developer has to specify these parameters in Doxyfile to enable support of MathJax in Doxygen:
+
+    USE_MATHJAX         = YES
+    MATHJAX_FORMAT      = HTML-CSS
+    MATHJAX_RELPATH     = http://cdn.mathjax.org/mathjax/latest
+    MATHJAX_EXTENSIONS  = TeX/AMSmath TeX/AMSsymbols
+
+To use MathJax tool with the HTML page, it's \<head\> block has to contain 
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.html}
+    <script type="text/x-mathjax-config">
+      MathJax.Hub.Config({
+        tex2jax: {inlineMath: [["$","$"],["\\(","\\)"]]},
+        displayAlign: "left"
+      });
+    </script>
+
+    <script type="text/javascript"
+      src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
+    </script>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First script configures MathJax to understand separator types and to left allign formulas. 
+The second script inserts reference to MathJax tool. 
+This tool will always be used when the HTML output will be shown.
+
+Equations can be written by several ways:
+
+1.Unnumbered displayed formulas that are centered on a separate line. 
+These formulas should be put between \@f\[ and \@f\] tags. An example: 
+
+@verbatim
+@f$[
+    |I_2|=\left| \int_{0}^T \psi(t)
+            \left\{ 
+                u(a,t)-
+                \int_{\gamma(t)}^a 
+                \frac{d\theta}{k(\theta,t)}
+                \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
+            \right\} dt
+        \right|
+@f$]
+@endverbatim
+
+gives the following result:
+
+   @f$
+       |I_2|=\left| \int_{0}^T \psi(t)
+               \left\{ 
+                   u(a,t)-
+                   \int_{\gamma(t)}^a 
+                   \frac{d\theta}{k(\theta,t)}
+                   \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
+               \right\} dt
+           \right|
+   @f$
+   
+2.Formulas can also be put between @verbatim \begin{align} @endverbatim and @verbatim \end{align} @endverbatim tags. An example: 
+
+@verbatim
+  \begin{align}
+  \dot{x} & = \sigma(y-x) \\
+  \dot{y} & = \rho x - y - xz \\
+  \dot{z} & = -\beta z + xy
+  \end{align}
+@endverbatim
+
+  gives the following result:
+@latexonly
+  \begin{align}
+  \dot{x} & = \sigma(y-x) \\
+  \dot{y} & = \rho x - y - xz \\
+  \dot{z} & = -\beta z + xy
+  \end{align}
+@endlatexonly
+
+@htmlonly
+  \begin{align}
+  \dot{x} & = \sigma(y-x) \\
+  \dot{y} & = \rho x - y - xz \\
+  \dot{z} & = -\beta z + xy
+  \end{align}
+@endhtmlonly
+
+3.Inline formulas can be specified using this syntax:
+
+@verbatim
+  @f$ \sqrt{3x-1}+(1+x)^2 @f$
+@endverbatim
+
+  that leads to the following result: @f$ \sqrt{3x-1}+(1+x)^2 @f$
+  
+@section  OCCT_DM_SECTION_B Appendix 2: Doxygen Configuration
+
+@subsection OCCT_DM_SECTION_B_1 Doxygen Configuration File
+
+To generate documentation from "source" *.md files a developer can use file OCCT.doxyfile, 
+which is located in /docs directory of OCCT (more information can be found at @htmlonly 
+<a href="#OCCT_DM_SECTION_X_X_X">Directory Structure</a> @endhtmlonly paragraph)
+or create his own configuration file, called "Doxyfile". The configuration file may look as follows: 
+
+@verbatim
+  DOXYFILE_ENCODING      = UTF-8
+  PROJECT_NAME           = "OCCT User's Guides"
+  PROJECT_NUMBER         = 1.0.1
+  PROJECT_LOGO           = "D:/OS/OCCT/docs/OCCT_logo.png"
+  OUTPUT_LANGUAGE        = English
+  TAB_SIZE               = 4
+  MARKDOWN_SUPPORT       = YES
+  AUTOLINK_SUPPORT       = NO
+  SHOW_FILES             = NO
+  WARNINGS               = YES
+  WARN_IF_UNDOCUMENTED   = YES
+  WARN_IF_DOC_ERROR      = YES
+  WARN_NO_PARAMDOC       = NO
+  WARN_FORMAT            = "$file:$line: $text"
+  INPUT                  = "D:/OS/OCCT/docs/"
+  INPUT_ENCODING         = UTF-8
+  FILE_PATTERNS          = *.md
+  RECURSIVE              = YES
+  IMAGE_PATH             = tmp
+  GENERATE_HTML          = YES
+  SEARCHENGINE           = NO
+  HTML_OUTPUT            = html
+  HTML_FILE_EXTENSION    = .html
+  HTML_HEADER            = "static/header.html"
+  HTML_FOOTER            = "static/footer.html"
+  HTML_STYLESHEET        = "static/general.css"
+  HTML_EXTRA_STYLESHEET  = "static/styles.css"
+  HTML_COLORSTYLE_HUE    = 220
+  HTML_COLORSTYLE_SAT    = 100
+  HTML_COLORSTYLE_GAMMA  = 80
+  HTML_TIMESTAMP         = YES
+  HTML_DYNAMIC_SECTIONS  = NO
+  HTML_INDEX_NUM_ENTRIES = 100
+  GENERATE_LATEX         = YES
+  GENERATE_RTF           = YES
+@endverbatim
+
+@subsection OCCT_DM_SECTION_B_2 Doxygen Output Customization
+
+The customization of the output files, produced by Doxygen, can be made by using different Doxyfile parameters,
+like HTML_COLORSTYLE_SAT, which specifies one of HSV color component of HTML page header, and also by using DoxygenLayout xml file.
+A developer can use default file from /docs directory or generate his own with doxygen -l command. It may looks as follows:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.xml}
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.8.3.1 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title="Introduction"/>
+    <tab type="pages" visible="yes" title="Documents" intro=
+    "This section contains links to all OCCT documents that are available at the moment"/>
+    <tab type="modules" visible="no" title="" intro=""/>
+    <tab type="namespaces" visible="no" title="">
+      <tab type="namespacelist" visible="no" title="" intro=""/>
+      <tab type="namespacemembers" visible="no" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="no" title="">
+      <tab type="classlist" visible="no" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
+      <tab type="hierarchy" visible="no" title="" intro=""/>
+      <tab type="classmembers" visible="no" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="Files">
+      <tab type="filelist" visible="yes" title="" intro=""/>
+      <tab type="globals" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="examples" visible="no" title="" intro=""/>  
+  </navindex>
+    ...
+</doxygenlayout>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tag \<tab\> specifies tabs which appear at the head of each html page. For the OCCT user documentation
+ "mainpage" and "pages" tabs are usually needed and their visible parameter should always be "yes". 
+The visibility of other tabs should be set to "no".
+
+Developers can find more information about Doxygen configuration in the help file 
+or at http://www.stack.nl/~dimitri/doxygen/manual/
+
+@subsection OCCT_DM_SECTION_B_3 Doxywizard Usage
+
+The easiest way of applying and modification of Doxyfile is to use a Doxywizard application, 
+which is usually a part of the Doxygen tool. To apply a configuration file, the developer should 
+select "Open..." item of the File menu or press Ctrl + O. Modification of Doxyfile can be made
+using "Wizard" or "Expert" tabs of Doxywizard application. 
+
+Developers can find more information about Doxywizard usage in the help file or at 
+http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html.

dox/dev_guides/tests/tests.md

@@ -0,0 +1,593 @@
+ Automated Testing System  {#dev_guides__tests}
+======================================
+
+@section testmanual_1 Introduction
+
+This document provides overview and practical guidelines for work with OCCT automatic testing system.
+Reading this section *Introduction* should be sufficient for OCCT developers to use the test system 
+to control non-regression of the modifications they implement in OCCT. Other sections provide 
+more in-depth description of the test system, required for modifying the tests and adding new test cases. 
+
+@subsection testmanual_1_1 Basic Information
+
+OCCT automatic testing system is organized around DRAW Test Harness [1], 
+a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands.
+Standard OCCT tests are included with OCCT sources and are located in subdirectory *tests*
+ of the OCCT root folder. Other test folders can be included in the scope of the test system, 
+ e.g. for testing applications based on OCCT.
+Logically the tests are organized in three levels:
+
+  * Group: group of related test grids, usually relating to some part of OCCT functionality (e.g. blend)
+  * Grid: set of test cases within a group, usually aimed at testing some particular aspect or mode of execution of the relevant functionality (e.g. buildevol)
+  * Test case: script implementing individual test (e.g. K4)
+
+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 code from dev.opencascade.org.
+
+@subsection testmanual_1_2 Intended Use of Automatic Tests
+
+Each modification made in OCCT code must be checked for non-regression 
+by running the whole set of tests. The developer who does the modification 
+is responsible for running and ensuring non-regression on the tests that are available to him.
+Note that many tests are based on data files that are confidential and thus available only at OPEN CASCADE. 
+Thus official certification testing of the changes before integration to master branch 
+of official OCCT Git repository (and finally to the official release) is performed by OPEN CASCADE in any case.
+
+Each new non-trivial modification (improvement, bug fix, new feature) in OCCT 
+should be accompanied by a relevant test case suitable for verifying that modification. 
+This test case is to be added by developer who provides the modification.
+If a modification affects result of some test case(s), 
+either the modification should be corrected (if it causes regression) 
+or affected test cases should be updated to account for the modification. 
+
+The modifications made in the OCCT code and related test scripts 
+should be included in the same integration to master branch.
+
+@subsection testmanual_1_3 Quick Start
+
+@subsubsection testmanual_1_3_1 Setup
+
+Before running tests, make sure to define environment variable CSF_TestDataPath 
+pointing to the directory containing test data files. 
+(The publicly available data files can be downloaded 
+from http://dev.opencascade.org separately from OCCT code.) 
+The recommended way for that is adding a file *DrawInitAppli* 
+in the directory which is current at the moment of starting DRAWEXE (normally it is $CASROOT). 
+This file is evaluated automatically at the DRAW start. Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+set env(CSF_TestDataPath) d:/occt/tests_data
+return ;# this is to avoid an echo of the last command above in cout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All tests are run from DRAW command prompt, thus first run draw.tcl or draw.sh to start DRAW.
+
+@subsubsection testmanual_1_3_2 Running Tests
+
+To run all tests, type command *testgrid* followed by path 
+to the new directory where results will be saved. 
+It is recommended that this directory should be new or empty; 
+use option –overwrite to allow writing logs in existing non-empty directory. 
+
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[]> testgrid d:/occt/results-2012-02-27
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If empty string is given as log directory name, the name will be generated automatically 
+using current date and time, prefixed by *results_*. Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[]> testgrid {}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For running only some group or a grid of tests, 
+give additional arguments indicating group and (if needed) grid. Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[]> testgrid d:/occt/results-2012-02-28 blend simple
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As the tests progress, the result of each test case is reported. 
+At the end of the log summary of test cases is output, 
+including list of detected regressions and improvements, if any. Example:
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Tests summary
+
+    CASE 3rdparty export A1: OK 
+    ...
+    CASE pipe standard B1: BAD (known problem)
+    CASE pipe standard C1: OK
+    No regressions 
+    Total cases: 208 BAD, 31 SKIPPED, 3 IMPROVEMENT, 1791 OK
+    Elapsed time: 1 Hours 14 Minutes 33.7384512019 Seconds
+    Detailed logs are saved in D:/occt/results_2012-06-04T0919
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tests are considered as non-regressive if only OK, BAD (i.e. known problem), 
+and SKIPPED (i.e. not executed, e.g. because of lack of data file) statuses are reported. 
+See <a href="#testmanual_3_4">Grid’s *cases.list* file</a> chapter for details.
+
+The detailed logs of running tests are saved in the specified directory and its sub-directories. 
+Cumulative HTML report summary.html provides links to reports on each test case. 
+An additional report TESTS-summary.xml is output in JUnit-style XML format 
+that can be used for integration with Jenkins or other continuous integration system.
+Type *help testgrid* in DRAW prompt to get help on additional options supported by testgrid command.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[3]> help testgrid
+    testgrid: Run all tests, or specified group, or one grid
+        Use: testgrid logdir [group [grid]] [options...]
+        Allowed options are:
+        -verbose {0-2}: verbose level, 0 by default, can be set to 1 or 2
+        -parallel N: run in parallel with up to N processes (default 0)
+        -refresh N: save summary logs every N seconds (default 60)
+        -overwrite: force writing logs in existing non-empty directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_1_3_3 Running Single Test
+
+To run single test, type command *test*’ followed by names of group, grid, and test case. 
+
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[1]> test blend simple A1
+    CASE blend simple A1: OK
+    Draw[2]>
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that normally intermediate output of the script is not shown. 
+To see intermediate commands and their output, type command *decho on* 
+before running the test case. (Type ‘decho off’ to disable echoing when not needed.) 
+The detailed log of the test can also be obtained after the test execution by command *dlog get*.
+
+@section testmanual_2 Organization of Test Scripts
+
+@subsection testmanual_2_1 General Layout
+
+Standard OCCT tests are located in subdirectory tests of the OCCT root folder ($CASROOT).
+Additional test folders can be added to the test system 
+by defining environment variable CSF_TestScriptsPath. 
+This should be list of paths separated by semicolons (*;*) on Windows 
+or colons (*:*) on Linux or Mac. Upon DRAW launch, 
+path to tests sub-folder of OCCT is added at the end of this variable automatically.
+Each test folder is expected to contain:
+
+  * Optional file parse.rules defining patterns for interpretation of test results, common for all groups in this folder
+  * One or several test group directories. 
+
+Each group directory contains:
+
+  * File grids.list that identifies this test group and defines list of test grids in it.
+  * Test grids (sub-directories), each containing set of scripts for test cases, and optional files cases.list, parse.rules, begin, and end.
+  * Optional sub-directory data
+  * Optional file parse.rules
+  * Optional files begin and end
+
+By convention, names of test groups, grids, and cases should contain no spaces and be lowercase. 
+Names begin, end, data, parse.rules, grids.list, cases.list are reserved. 
+General layout of test scripts is shown on Figure 1.
+
+![](/devs_guide/tests/images/tests_image001.png "")
+
+Figure 1. Layout of tests folder
+
+@subsection testmanual_2_2 Test Groups
+
+@subsubsection testmanual_2_2_1 Group Names
+
+Test folder usually contains several directories representing test groups (Group 1, Group N). 
+Each directory contains test grids for certain OCCT functionality. 
+The name of directory corresponds to this functionality.
+Example:
+
+@verbatim
+  caf
+  mesh
+  offset
+@endverbatim
+
+@subsubsection testmanual_2_2_2 Group's *grids.list* File
+
+The test group must contain file *grids.list* file 
+which defines ordered list of grids in this group in the following format:
+
+~~~~~~~~~~~~~~~~~
+001 gridname1
+002 gridname2
+...
+NNN gridnameN
+~~~~~~~~~~~~~~~~~
+
+Example:
+
+~~~~~~~~~~~~~~~~~
+    001 basic
+    002 advanced
+~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_2_2_3 Group's *begin* File
+
+The file *begin* is a Tcl script. It is executed before every test in current group. 
+Usually it loads necessary Draw commands, sets common parameters and defines 
+additional Tcl functions used in test scripts.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    pload TOPTEST ;# load topological command
+    set cpulimit 300 ;# set maximum time allowed for script execution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_2_2_4 Group's *end* File
+
+The file end is a TCL script. It is executed after every test in current group. 
+Usually it checks the results of script work, makes a snap-shot 
+of the viewer and writes *TEST COMPLETED* to the output.
+Note: *TEST COMPLETED* string should be presented in output 
+in order to signal that test is finished without crash. 
+See <a href="#testmanual_3">Creation And Modification Of Tests</a> chapter for more information.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    if { [isdraw result] } {
+        checkshape result
+    } else {
+        puts *Error: The result shape can not be built*
+    }
+    puts *TEST COMPLETED*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_2_2_5 Group’s *parse.rules* File
+
+The test group may contain *parse.rules* file. 
+This file defines patterns used for analysis of the test execution log 
+and deciding the status of the test run. 
+Each line in the file should specify a status (single word), 
+followed by a regular expression delimited by slashes (*/*) 
+that will be matched against lines in the test output log to check if it corresponds to this status.
+The regular expressions support subset of the Perl re syntax.
+The rest of the line can contain a comment message 
+which will be added to the test report when this status is detected.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    FAILED /\b[Ee]xception\b/ exception
+    FAILED /\bError\b/ error
+    SKIPPED /Cannot open file for reading/ data file is missing
+    SKIPPED /Could not read file .*, abandon/ data file is missing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Lines starting with a *#* character and blank lines are ignored to allow comments and spacing.
+See <a href="#testmanual_2_3_4">Interpretation of test results</a> chapter for details.
+
+If a line matches several rules, the first one applies. 
+Rules defined in the grid are checked first, then rules in group, 
+then rules in the test root directory. This allows defining some rules on the grid level 
+with status IGNORE to ignore messages that would otherwise be treated as errors due to the group level rules.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    FAILED /\bFaulty\b/ bad shape
+    IGNORE /^Error [23]d = [\d.-]+/ debug output of blend command
+    IGNORE /^Tcl Exception: tolerance ang : [\d.-]+/ blend failure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsection testmanual_2_3 Test Grids
+
+@subsubsection testmanual_2_3_1 Grid Names
+
+Group folder can have several sub-directories (Grid 1… Grid N) defining test grids. 
+Each test grid directory contains a set of related test cases. 
+The name of directory should correspond to its contents.
+
+Example:
+
+caf
+   basic
+   bugs
+   presentation
+
+Where **caf** is the name of test group and *basic*, *bugs*, *presentation*, etc are the names of grids.
+
+@subsubsection testmanual_2_3_2 Grid’s *begin* File
+
+The file *begin* is a TCL script. It is executed before every test in current grid. 
+Usually it sets variables specific for the current grid.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    set command bopfuse ;# command tested in this grid
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_2_3_3 Grid’s *end* File
+
+The file *end* is a TCL script. It is executed after every test in current grid. 
+Usually it executes specific sequence of commands common for all tests in the grid.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    vdump $logdir/${casename}.gif ;# makes a snap-shot of AIS viewer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsubsection testmanual_2_3_4 Grid’s *cases.list* File
+
+The grid directory can contain an optional file cases.list 
+defining alternative location of the test cases. 
+This file should contain singe line defining the relative path to collection of test cases.
+
+Example:
+
+../data/simple
+
+This option is used for creation of several grids of tests with the same data files 
+and operations but performed with differing parameters. 
+The common scripts are usually located place in common 
+subdirectory of the test group (data/simple as in example).
+If cases.list file exists then grid directory should not contain any test cases. 
+The specific parameters and pre- and post-processing commands 
+for the tests execution in this grid should be defined in the begin and end files.
+
+@subsection testmanual_2_4 Test Cases
+
+The test case is TCL script which performs some operations using DRAW commands 
+and produces meaningful messages that can be used to check the result for being valid.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    pcylinder c1 10 20 ;# create first cylinder
+    pcylinder c2 5 20 ;# create second cylinder
+    ttranslate c2 5 0 10 ;# translate second cylinder to x,y,z
+    bsection result c1 c2 ;# create a section of two cylinders
+    checksection result ;# will output error message if result is bad
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The test case can have any name (except reserved names begin, end, data, cases.list, parse.rules). 
+For systematic grids it is usually a capital English letter followed by a number.
+
+Example:
+
+@verbatim
+    A1
+    A2
+    B1
+    B2
+@endverbatim
+
+Such naming facilitates compact representation of results 
+of tests execution in tabular format within HTML reports.
+
+@subsection testmanual_2_5 Directory *data*
+
+The test group may contain subdirectory data. 
+Usually it contains data files used in tests (BREP, IGES, STEP, etc.) 
+and / or test scripts shared by different test grids 
+(in subdirectories, see <a href="#testmanual_2_3_4">Grid’s *cases.list* file</a> chapter).
+
+@section testmanual_3 Creation And Modification Of Tests
+
+This section describes how to add new tests and update existing ones.
+
+@subsection testmanual_3_1 Choosing Group, Grid, and Test Case Name
+
+The new tests are usually added in context of processing some bugs. 
+Such tests in general should be added to group bugs, in the grid 
+corresponding to the affected OCCT functionality. 
+New grids can be added as necessary to contain tests on functionality not yet covered by existing test grids. 
+The test case name in the bugs group should be prefixed by ID 
+of the corresponding issue in Mantis (without leading zeroes). 
+It is recommended to add a suffix providing a hint on the situation being tested. 
+If more than one test is added for a bug, they should be distinguished by suffixes; 
+either meaningful or just ordinal numbers.
+
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    12345_coaxial
+    12345_orthogonal_1
+    12345_orthogonal_2
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the case if new test corresponds to functionality for which 
+specific group of tests exists (e.g. group mesh for BRepMesh issues), 
+this test can be added (or moved later by OCC team) to this group. 
+
+@subsection testmanual_3_2 Adding Data Files Required for a Test
+
+It is advisable that tests scripts should be made self-contained whenever possible, 
+so as to be usable in environments where data files are not available. 
+For that simple geometric objects and shapes can be created using DRAW commands in the test script itself.
+If test requires some data file, it should be put to subdirectory data of the test grid. 
+Note that when test is integrated to master branch, 
+OCC team can move data file to data files repository, 
+so as to keep OCCT sources repository clean from big data files.
+When preparing a test script, try to minimize size of involved data model. 
+For instance, if problem detected on a big shape can be reproduced on a single face 
+extracted from that shape, use only this face in the test.
+
+@subsection testmanual_3_3 Implementation of the Script
+
+Test should run commands necessary to perform the operations being tested, 
+in a clean DRAW session. This includes loading necessary functionality by *pload* command, 
+if this is not done by *begin* script. The messages produced by commands in standard output 
+should include identifiable messages on the discovered problems if any. 
+Usually the script represents a set of commands that a person would run interactively 
+to perform the operation and see its results, with additional comments to explain what happens.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    # Simple test of fusing box and sphere
+    box b 10 10 10 
+    sphere s 5
+    bfuse result b s
+    checkshape result
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure that file parse.rules in the grid or group directory contains 
+regular expression to catch possible messages indicating failure of the test. 
+For instance, for catching errors reported by *checkshape* command 
+relevant grids define a rule to recognize its report by the word *Faulty*: FAILED /\bFaulty\b/ bad shape
+For the messages generated in the script the most natural way is to use the word *Error* in the message.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    set expected_length 11
+    if { [expr $actual_length - $expected_length] > 0.001 } {
+        puts *Error: The length of the edge should be $expected_length*
+    }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the end, the test script should output *TEST COMPLETED* string 
+to mark successful completion of the script. 
+This is often done by the end script in the grid.
+When test script requires data file, use Tcl procedure *locate_data_file* 
+to get path to the data file, rather than explicit path. 
+This will allow easy move of the data file from OCCT repository 
+to the data files repository without a need to update test script.
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    stepread [locate_data_file CAROSKI_COUPELLE.step] a *
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When test needs to produce some snapshots or other artifacts, 
+use Tcl variable logdir as location where such files should be put. 
+Command *testgrid* sets this variable to the subdirectory of the results folder 
+corresponding to the grid. Command *test* sets it to $CASROOT/tmp unless it is already defined. 
+Use Tcl variable casename to prefix all the files produced by the test. 
+This variable is set to the name of the test case. 
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    xwd $logdir/${casename}.gif
+    vdisplay result; vfit
+    vdump $logdir/${casename}-axo.gif
+    vfront; vfit
+    vdump $logdir/${casename}-front.gif
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+could produce:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    A1.gif
+    A1-axo.gif
+    A1-front.gif
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsection testmanual_3_4 Interpretation of Test Results
+
+The result of the test is evaluated by checking its output against patterns 
+defined in the files parse.rules of the grid and group.
+The OCCT test system recognizes five statuses of the test execution:
+
+  * SKIPPED: reported if line matching SKIPPED pattern is found (prior to any FAILED pattern). This indicates that the test cannot be run in the current environment; most typical case is absence of the required data file.
+  * FAILED: reported if some line matching pattern with status FAILED is found (unless it is masked by preceding IGNORE pattern or a TODO statement, see below), or if message TEST COMPLETED is not found at the end. This indicates that test produces bad or unexpected result, and usually highlights a regression.
+  * BAD: reported if test script output contains one or several TODO statements and corresponding number of matching lines in the log. This indicates a known problem (see 3.5). The lines matching TODO statements are not checked against other patterns and thus will not cause a FAILED status.  
+  * IMPROVEMENT: reported if test script output contains TODO statement for which no corresponding line is found. This is possible indication of improvement (known problem disappeared).
+  * OK: If none of the above statuses have been assigned. This means test passed without problems.
+
+Other statuses can be specified in the parse.rules files, these will be classified as FAILED.
+Before integration of the change to OCCT repository, all tests should return either OK or BAD status.
+The new test created for unsolved problem should return BAD. 
+The new test created for a fixed problem should return FAILED without the fix, and OK with the fix.
+
+@subsection testmanual_3_5 Marking BAD Cases
+
+If the test produces invalid result at a certain moment then the corresponding bug 
+should be created in the OCCT issue tracker [3], and the problem should be marked as TODO in the test script.
+The following statement should be added to such test script:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    puts *TODO BugNumber ListOfPlatforms: RegularExpression* 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+where:
+
+  * BugNumber is an ID of the bug in the tracker. For example: #12345
+  * ListOfPlatform is a list of platforms at which the bug is reproduced (e.g. Mandriva2008, Windows or All). 
+  
+*Note: the platform name is custom for the OCCT test system;* 
+*it can be consulted as value of environment variable os_type defined in DRAW.*
+
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    Draw[2]> puts $env(os_type)
+    windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+
+  * RegularExpression is a regular expression which should be matched against the line indicating the problem in the script output. 
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    puts *TODO #22622 Mandriva2008: Abort .* an exception was raised*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Parser checks the output of the test and if an output line matches 
+the RegularExpression then it will be assigned a BAD status instead of FAILED.
+For each output line matching to an error expression a separate TODO line 
+must be added to mark the test as BAD. 
+If not all the TODO statements are found in the test log, 
+the test will be considered as possible improvement.
+To mark the test as BAD for an incomplete case 
+(when final TEST COMPLETE message is missing) 
+the expression *TEST INCOMPLETE* should be used instead of regular expression. 
+
+Example:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    puts *TODO OCC22817 All: exception.+There are no suitable edges*
+    puts *TODO OCC22817 All: \\*\\* Exception \\*\\**
+    puts *TODO OCC22817 All: TEST INCOMPLETE*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@section testmanual_4 Extended Use
+
+@subsection testmanual_4_1 Running Tests on Older Versions of OCCT
+
+Sometimes it might be necessary to run tests on previous versions of OCCT (up to to 6.5.3) 
+that do not include this test system. This can be done by adding DRAW configuration file DrawAppliInit 
+in the directory which is current by the moment of DRAW startup, 
+to load test commands and define necessary environment. Example 
+(assume that d:/occt contains up-to-date version of OCCT sources 
+with tests, and test data archive is unpacked to d:/test-data):
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    set env(CASROOT) d:/occt
+    set env(CSF_TestScriptsPath) $env(CASROOT)/tests
+    source $env(CASROOT)/src/DrawResources/TestCommands.tcl
+    set env(CSF_TestDataPath) d:/test-data
+    return
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that on older versions of OCCT the tests are run in compatibility mode 
+and not all output of the test command can be captured; 
+this can lead to absence of some error messages (can be reported as improvement).
+
+@subsection testmanual_4_2 Adding Custom Tests
+
+You can extend the test system by adding your own tests. 
+For that it is necessary to add paths to the directory where these tests are located, 
+and additional data directory(ies), to the environment variables CSF_TestScriptsPath and CSF_TestDataPath. 
+The recommended way for doing this is using DRAW configuration file DrawAppliInit 
+located in the directory which is current by the moment of DRAW startup.
+
+Use Tcl command *_path_separator* to insert platform-dependent separator to the path list.
+Example:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+    set env(CSF_TestScriptsPath) \
+      $env(TestScriptsPath)[_path_separator]d:/MyOCCTProject/tests
+    set env(CSF_TestDataPath) \
+      d:/occt/test-data[_path_separator]d:/MyOCCTProject/tests
+    return ;# this is to avoid an echo of the last command above in cout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@section testmanual_5 References
+
+-# DRAW Test Harness User’s Guide
+-# Perl regular expressions, http://perldoc.perl.org/perlre.html 
+-# OCCT MantisBT issue tracker, http://tracker.dev.opencascade.org 

dox/dev_guides/wok/wok.md

@@ -0,0 +1,153 @@
+WOK {#dev_guides__wok}
+=========
+
+WOK is a legacy build environment for Open CASCADE Technology. It is required 
+for generation of header files for classes defined with @ref ug_cdl "CDL"
+("Cascade Definition Language"). Also tools for generation of project files
+for other build systems, and OCCT documentation, are integrated to WOK.
+
+WOK thus is needed in the following situations:
+- Building from OCCT sources from Git repository (do not contain generated files)
+- Building after some changes made in CDL files
+
+Before installing and using WOK, make sure that you have installed a compiler (it is assumed that it is Visual Studio on Windows or gcc on Linux and MacOS) and third-party components required for building OCCT.
+
+@section wok1 Installing WOK
+
+  Download the latest version of binary distribution WOK from http://dev.opencascade.org/index.php?q=home/resources
+
+@subsection wok11 Windows
+
+  Run the installer. You will be prompted to read and accept the OCCT Public License to proceed:
+  
+  ![](/devs_guide/wok/images/wok_image001.jpg "")
+ 
+  Click Next and proceed with the installation.
+  At the end of the installation you will be prompted to specify the version and the location of Visual Studio to be used, and the location of third-party libraries:
+  
+  ![](/devs_guide/wok/images/wok_image002.jpg "")
+ 
+  You can change these settings at any time later. For this click on the item "Customize environment (GUI tool)" in the WOK group in the Windows Start menu.
+  
+  The shortcuts from this group provide two ways to run WOK: 
+  * In command prompt window ("WOK TCL shell"). 
+  * In Emacs editor ("WOK Emacs"). Using Emacs is convenient if you need to work within WOK environment. 
+
+  By default WOK installer creates a WOK factory with name "LOC" within workshop "dev" (WOK path :LOC:dev). 
+
+@subsection wok12 Linux
+
+  * Unpack the .tgz archive containing WOK distributive into an installation directory <WOK_INSTALL_DIR>.
+
+  * Perform the following commands assuming that you have unpacked WOK distributive archive into <WOK_INSTALL_DIR>:
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  cd <WOK_INSTALL_DIR>/site
+  wok_confgui.sh
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  
+  Define all necessary paths to third-party products in the dialog window:
+  
+  ![](/devs_guide/wok/images/wok_image003.jpg "")
+ 
+  * Run the following commands to create WOK LOC factory:
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  cd <WOK_INSTALL_DIR>/site
+  wok_init.sh
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  
+  * Your installation procedure is over. To run WOK use one the following commands:
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  cd <WOK_INSTALL_DIR>/site
+  wok_emacs.sh
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  or
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  cd <WOK_INSTALL_DIR>/site
+  wok_tclsh.sh
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+@subsection wok13 Mac OS X
+
+  * In the Finder double click on wokSetup.dmg file. This will open a new window. Drag and drop "wokSetup" folder from this window at the location in the Finder where you want to install WOK, i.e. <WOK_INSTALL_DIR>.
+  
+  * Browse in the Finder to the folder <WOK_INSTALL_DIR>/site and double click on WokConfig. This will open a window with additional search path settings. Define all necessary paths to third-party products in the dialog window:
+  
+  ![](/devs_guide/wok/images/wok_image004.jpg "")
+ 
+  * Run the following commands to create WOK LOC factory:
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  cd <WOK_INSTALL_DIR>/site
+  wok_init.sh
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  
+  * Your installation procedure is over. To run WOK in Emacs navigate in the Finder to the folder <WOK_INSTALL_DIR>/site and double click on WokEmacs.
+
+
+@section wok2 Initialization of Workbench
+
+  To start working with OCCT, clone the OCCT Git repository from the server (see http://dev.opencascade.org/index.php?q=home/resources for details) or unpack the source archive. 
+  
+  Then create a WOK workbench (command wcreate) setting its Home to the directory, where the repository is created ($CASROOT variable). The workbench should have the same name as that directory. 
+  
+  For example, assuming that OCCT repository has been cloned into D:/occt folder: 
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  LOC:dev> wcreate occt -DHome=D:/occt
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+  Note: $CASROOT is equal to D:/occt now
+
+  Then you can work with this workbench using normal WOK functionality (wprocess, umake, etc.; see WOK User<65>s Guide for details) or use it only for generation of derived sources and project files, and build OCCT with Visual Studio on Windows or make command on Linux, as described below.
+  
+@section wok3 Generation of building projects
+
+  Use command wgenproj in WOK to generate derived headers, source and building projects files: 
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  LOC:dev> wokcd occt
+  LOC:dev:occt> wgenproj [ -target=<TARGET> ] [ -no_wprocess ]
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TARGET:
+  * vc8 - Visual Studio 2005
+  * vc9 - Visual Studio 2008
+  * vc10 - Visual Studio 2010
+  * vc11 - Visual Studio 2012
+  * cbp - CodeBlocks
+  * cmake - CMake
+  * amk - AutoMake
+  * xcd - Xcode
+-no_wprocess - skip generation of derived headers and source files
+
+Note that this command takes several minutes to complete at the first call. 
+
+Re-execute this step to generate derived headers, source and building projects files if some CDL files in OCCT have been modified (either by you directly, or due to updates in the repository). Note that in some cases WOK may fail to update correctly; in such case remove sub-directories drv and .adm and repeat the command. 
+
+To regenerate derived headers and source files without regeneration of projects use command:
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  LOC:dev> wokcd occt
+  LOC:dev:occt> wprocess -DGroups=Src,Xcpp
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The generated building project has been placed into $CASROOT/adm folder:
+  * for vc8 - $CASROOT/adm/msvc/vc8
+  * for vc9 - $CASROOT/adm/msvc/vc9
+  * for vc10 - $CASROOT/adm/msvc/vc10
+  * for vc11 - $CASROOT/adm/msvc/vc11
+  * for cbp - $CASROOT/adm/<OS> /cbp
+  * for cmake - $CASROOT/adm/cmake
+  * for amk - $CASROOT/adm/lin/amk
+  * xcd - $CASROOT/adm/<OS>/xcd
+
+@section wok4  Generation of documentation
+
+  Use command wgendoc in WOK to generate reference documentation: 
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
+  :LOC:dev> wokcd occt
+  :LOC:dev:occt> wgendoc 
+  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following options can be used: 
+  * -wb=< workbench name >  the name of OCCT workbench (the current one by default);
+  * -m=< list of modules > the list of modules that will be contained in the documentation;
+  * -outdir=< path > the output directory for the documentation;
+  * -chm  the option to generate CHM file;
+  * -hhc=< path > the path to HTML Help Compiler (hhc.exe) or equivalent;
+  * -qthelp=< path > the option to generate Qt Help file, it is necessary to specify the path to qthelpgenerator executable;
+  * -doxygen=< path > the path to Doxygen executable
+  * -dot=< path > the path to GraphViz dot executable