Moritz_2.FPG

Moritz
the Nassi-Shneiderman Diagram-Generator
for Doxygen

Sponsors






Purpose

If you have something like this:

TYPE modell_CommentsBehind__function(TYPE Parameter)
// this is the modell of a function
// with comments behind of the commands
{
 TYPE   ReturnValue;                         //comment ReturnValue
 TYPE_A LokalVariable_1 = Value1;            //variable-comment 1
 TYPE_A LokalVariable_2;                     //variable-comment 2
 TYPE_Z LokalVariable_N = ValueN;            //variable-comment N
 operation_1( & LokalVariable_1,Parameter);  //operation-comment 1
 LokalVariable_2 = operation_2(LokalVariable_N);
                                             //operation-comment 2
 if(LokalVariable_1 == LokalVariable_2)
                                             //statement-comment for true
 {
  ReturnValue = DefaultValue;                //operation-comment for true
 }
 else                                        //statement-comment for false
 {
  while(ParameterStatment)                   //loop-comment
   ReturnValue = operation_3();              //operation-comment 3
 };
 return(ReturnValue);                        //comment return-line
}

Moritz will traditionaly generate something like this:



modell_CommentsBehind__function ( TYPE Parameter)


TYPE modell_CommentsBehind__function ( TYPE Parameter)
this is the modell of a function with comments behind of the commands
TYPE ReturnValue
comment ReturnValue
TYPE_A LokalVariable 1= Value1
variable-comment 1
TYPE_A LokalVariable 2
variable-comment 2
TYPE_Z LokalVariable N= ValueN
variable-comment N
operation_1( & LokalVariable_1, Parameter)
operation-comment 1
LokalVariable_2 = operation_2( LokalVariable_N)
operation-comment 2
if( LokalVariable_1== LokalVariable_2)
statement-comment for true
ReturnValue = DefaultValue
operation-comment for true
else
statement-comment for false
while( ParameterStatment)
loop-comment
ReturnValue = operation_3()
operation-comment 3

return ( ReturnValue)
comment return-line

But with the new Moritz 2 will it is also possible to get something like this:

dot_samples_cpp_F_modell_CommentsBehind__function.JPG






Introduction

As help-tool for Doxygen Moritz is designed as a source-code analysing program that generates algorithm describing diagrams of the functions and methods written in different programming languages. Natively this diagrams are generated as html-files for example the nassi schneiderman diagrams. But today other output-formats are possible also for uml activity diagrams are generated as dot-scripts. Moritz 2 has now an own source parser and uses the xml-output of Doxygen as additional information-base to get information about link-destionations located in the documents generated by Doxygen. The output of Moritz may be included in a documentation generated by Doxygen via the commands "htmlinclude" or "dotfile".
Moritz it self is splited in 2 console- or terminal-applications which have to be started via command-line. With configuration-files you may control the general style of the diagrams. You can also change this configuration for a function or a part of a function by using special commands in the source-code.


Moritz is designed as one tool in a chain of tools. It could not be used as stand-alone application. Even Moritz 2 comes along with an own source-parser it doesn't create graphic files directly.

GeneralFlow.jpg

To parse the sources written in a programming language like C/C++, Phyton, Matlab or Pascal a parser tool called abc2xml is used to create a xml-database that has an own project called MuLanPa . This tool creates for every source an xml-file that contains a so called parser tree that describes the algorithm- structure. This xml-file may be also used as input for other analytic tools. The Moritz binary xml2abc analyses this system of xml-files and creates several script-files to describe the diagrams. To get a graphical output a script-interpreting tool has to be used.
GeneralFlow2.jpg
The native script-format of Moritz is html. So every common html-browser may be used to view the diagrams as screen-output. But since today the dot-language is used to create dot-files for describing uml activity diagrms, the tool Dot has to be used to create real graphics like a jpg.

To control the whole process of generating the xml-scripts with Doxygen and generating the diagram-scripts with Moritz several files are used. To control the whole process of generating the xml-scripts with abc2xml and xml2abc several files are used.

FileDependency.jpg
  • First of all the user starts a batch-file or terminal-script wich calls abc2xml, xml2abc and perhaps additional tools to interprete the output of xml2abc sequentially.
  • The parser abc2xml neads an own configuration file in xml-format. To learn more about abc2xml is recommended to read its manual at MuLanPa .
  • The generator xml2abc neads an own configuration file in xml-format also.
  • It is possible to split the configurations of both tools in a user-file and some more detailed configurations.
    In the distribution you will find the folder cfg where the configurations for the comon user are placed. For example you place here the information about the files you wish to analyse
    The folder LangPack contains for every supported programming language an own sub-folder used as location for the detailed configuration. In parallel to the detailed xml-configurations you will find in addition some other files. The a2x-files contain the grammar descripition of the programming-language and the x2a-files the script-snipets used to assemble the diagram-parts.
    • Additionaly used tools may need own configuration-files. To learn more about it is recommended to use the manual of them.






Controlling Moritz via Shell- or Batch-Scripts

This is a possible algorithm for the controlling terminal-script
This bash-script shows how to use Moritz together with the program doxygen (www.doxygen.org).
In this file only command-line parameters are defined. Other important adjustments are made in the configuration-files.
voidscrHTMim ( void)
parameter-settings
XMLPATH = "./xml/"
path of the xml-sources with the input for moritz
DESTINATIONPATH_HTM = "./nsd/"
path for the diagrams made by moritz
DESTINATIONPATH_DOT = "./nsd/"
path for the diagrams made by moritz
DESCRIPTIONPATH = "./des/"
path for additional content created by moritz
CONFIGURATION_XML = "./cfg/abc2xml_cfg.xml"
configuration of abc2xml to transfer the source-files to xml-files
CONFIGURATION_NSD = "./cfg/xml2abc_cfg_nsd.xml"
configuration of xml2abc to transfer the xml-files to xml-files nassi shneiderman diagrams
CONFIGURATION_UAD = "./cfg/xml2abc_cfg_uad.xml"
configuration of xml2abc to transfer the xml-files to xml-files uml activity diagrams
MORITZPATH = "./bin/"
location of Moritz
delete old outputs of doxygen and moritz
removeDirectoryContent ( XMLPATH, "*.xml")
old output of abc2xml
removeDirectoryContent ( DESTINATIONPATH_HTM, "*.html")
old output of xml2abc
removeDirectoryContent ( DESTINATIONPATH_DOT, "*.dt")
old output of xml2abc
removeDirectoryContent ( DESCRIPTIONPATH, "*.htm")
old output of xml2abc
doxygen and moritz in action
doxygen ( "./doxygen/Doxyfile_xml")
run doxygen to generate doxygen associated xml-sources for moritz
( MORITZPATH ) abc2xml CFCONFIGURATION_XML
run abc2xml to generate xml-files wich contain the algorithm-structure
( MORITZPATH ) xml2abc CFCONFIGURATION_NSD
run xml2abc to generate files wich contain nassi-shneiderman diagrams
( MORITZPATH ) xml2abc CFCONFIGURATION_UAD
run xml2abc to generate files wich contain uml activity diagrams
doxygen ( "./doxygen/Doxyfile_html")
run doxygen to generate the whole documentation that contains all diagrams
(note, this diagram contains no valid script-text, it should only describe the sequence-steps)


This is is a possible content of the controlling terminal-script: 
rem ****************************************************************************
rem *            Example-batch to demonstrate how to use moritz
rem *
rem * This batch-file shows how to use moritz together with the program doxygen
rem * (www.doxygen.org) to create image-based html-diagrams.
rem *
rem * In this file only command-line parameters are defined. Other important
rem * adjustments are made in the configuration-files. They may be also
rem * responsible for problems.
rem * Use the commented pause-commands if you are looking for sources of
rem * trouble.
rem ****************************************************************************



rem ****************************************************************************
rem parameter-settings
rem ****************************************************************************


rem path of the xml-sources generated by abc2xml
set DESTINATION_XML=.\xml\
rem Pause

rem path for the nassi shneiderman diagrams generated by xml2abc
set DESTINATION_HTM=.\nsd\
rem Pause

rem path for the nassi uml activity diagrams generated by xml2abc
set DESTINATION_DOT=.\dot\
rem Pause

rem path for additional files generated by xml2abc
set DESCRIPTION=.\des\
rem Pause

rem abc2xml-configuration to generate xml files
set CONFIGURATION_XML=.\cfg\abc2xml_cfg.xml
rem Pause

rem xml2abc-configuration to generate nassi shneiderman diagrams
set CONFIGURATION_NSD=.\cfg\xml2abc_cfg_nsd.xml
rem Pause

rem xml2abc-configuration to generate uml activity diagrams
set CONFIGURATION_UAD=.\cfg\xml2abc_cfg_uad.xml
rem Pause


rem location of Moritz
set MORITZPATH=.\bin\
rem Pause



rem ****************************************************************************
rem delete old outputs of doxygen and moritz
rem ****************************************************************************


rem old ouput-sources of abc2xml
del %DESTINATION_XML%*.xml
rem Pause

rem outputs of moritz
del %DESCRIPTION%*.html
del %DESTINATION_HTM%*.html
del %DESTINATION_HTM%*.xml
del %DESTINATION_DOT%*.dt
del %DESTINATION_DOT%*.html


rem Pause



rem ****************************************************************************
rem doxygen and moritz in action
rem ****************************************************************************

rem run doxygen to generate doxygen associated xml-sources for moritz
doxygen.exe .\doxygen .\cfg\Doxyfile_xml
rem pause


rem run abc2xml to generate transfer the souce-files into xml-files
%MORITZPATH%abc2xml  CF%CONFIGURATION_XML%
rem >>log.txt
rem Pause

rem run moritz to generate files wich contain nassi shneiderman diagrams
%MORITZPATH%xml2abc  CF%CONFIGURATION_NSD%
rem >>log.txt
rem Pause

rem run moritz to generate files wich contain uml activity diagrams
%MORITZPATH%xml2abc  CF%CONFIGURATION_UAD%
rem >>log.txt
rem Pause

rem run doxygen to generate the whole documentation that contains all diagrams
doxygen.exe .\doxygen .\cfg\Doxyfile_html
rem pause







MRTZ-Commands

To control the generation of the diagrams it is possible to use commands in the source-code which are used as special-comments.
Command Purpose Description Moritz 1 Moritz 2
MRTZ_ Common Purpose prefix of every commands of the nsd-generation Yes No Change
beginBlock Common Purpose defines the begin of a command-block like { Yes No Change
endBlock Common Purpose defines the end of a command-block like } Yes No Change
errorResponse Common Purpose changes the reaction if an source-error is noticed Yes Not reimplemented since parser-tool has changed
This command will be ignored
commentModel Handling Comments local change the comment-modell Yes No Change in use.
But will be processed by parser
independent Handling Comments print a comment as independent diagram-part Yes No Change
printComments Handling Comments print comments also if this was switched off before Yes No Change
hideComments Handling Comments print no comments also if this was switched on before Yes No Change
skip Cut Diagramms hiding a source-part in the diagram without generation of an extra-diagram Yes No Change
exclude Cut Diagramms hiding a source-part in the diagram and generation of an extra-diagram Yes No Change
describe Cut Diagramms add a description of an excluded part-diagramm to the description-table of the function Yes No Change
include Cut Diagramms include the content of an external file Yes No Change
Condition Conditions and Preprocessor-Values condition to execute the following nsd-command Yes Implemntaion has changed since parser-tool has an own preprocessor mechanism to solve compilerswitches.
This command will be ignored
defineCondition Conditions and Preprocessor-Values define a condition to execute a nsd-command or a preprocessor-value Yes Implemntaion has changed since parser-tool has an own preprocessor mechanism where preprocessor-constants can be defined.
This command will be ignored
undefineCondition Conditions and Preprocessor-Values undefine a condition to execute a nsd-command or a preprocessor-value Yes Implemntaion has changed since parser-tool has an own preprocessor mechanism where preprocessor-constants can be undefined.
This command will be ignored
checkCompilerswitch Conditions and Preprocessor-Values check the rest of the function for occurrence of compiler-switches and control which variants should be analysed Yes Implemntaion has changed since parser-tool has an own preprocessor mechanism. to solve compilerswitches.
This command will be ignored
showSource Style of Diagram-Parts showing the a source-command as original source-line Yes No Change
pointOut Style of Diagram-Parts Block highlighting a source-part with an extra-titel and a background-color Yes No Change
printCommands Style of Diagram-Parts print all command-details also if this was switched off before Yes No Change
hideCommands Style of Diagram-Parts print not all command-details also if this was switched on before Yes No Change
ifElseChain Style of Diagram-Parts print a chain of "if else if else if ... else" like a switch-structure Yes Not reimplemented since all decision-structures will be shown in the same way.
This command will be ignored
changeSwitch Style of Diagram-Parts define if switch-structures are generated as table or in list-form No No
This command will be ignored
automaticLink Referencing other Documents define if links to other parts of the documentation should be generated automaticly, if the xml-source provides the necessary information Yes No Change
insertLink Referencing other Documents insert a link to an other document Yes No Change



To avoid conflicts with Doxygen it is recommended to use the normal recommended to use the normal comment-style that is not used to reserve a comment for doxygen ( for example in C/C++ only /* or // and not /*! or ///).

This is an example-function with a mix of commands for Doxygen and Moritz:
////////////////////////////////////////////////////////////////////////////////
/// function-description for doxygen
///
/// @param[in] Parameter    parameter-description for doxygen
///
/// @return                   return-description for doxygen
///
/// @htmlinclude dsc_samples_function_doxygen_moritz_mix.htm
////////////////////////////////////////////////////////////////////////////////
TYPE function_doxygen_moritz_mix(TYPE Parameter)
// function-description for moritz
// @MRTZ_describe function_doxygen_moritz_mix
// this is the modell of a function
// with comments behind of the commands
// @MRTZ_describe lokal_declarations
// declaration of local variables used by this function
{
//@MRTZ_exclude lokal_declarations
//@MRTZ_beginBlock
 TYPE   ReturnValue;                         //comment ReturnValue
 TYPE_A LokalVariable_1 = Value1;            //variable-comment 1
 TYPE_A LokalVariable_2;                     //variable-comment 2
 TYPE_Z LokalVariable_N = ValueN;            //variable-comment N
//@MRTZ_endBlock
 operation_1( & LokalVariable_1,Parameter);  //operation-comment 1
 LokalVariable_2 = operation_2(LokalVariable_N);
                                             //operation-comment 2
 if(LokalVariable_1 == LokalVariable_2)
                                             //statement-comment for true
 {
  ReturnValue = DefaultValue;                //operation-comment for true
 }
 else                                        //statement-comment for false
 {
  while(ParameterStatment)                   //loop-comment
   ReturnValue = operation_3();              //operation-comment 3
 };
 return(ReturnValue);                        //comment return-line
}

Pay attention to the difference between the comment for Doxygen (gray) and the comment for Moritz green.

You may also use / * @MRTZ_command * / for Moritz-commands but avoid to use / * ! MRTZ_command * /. If you want, that the normal source-comments are part of the diagrams also, you have also use normal comments not comments reseved for doxygen.

Every command starts with an @ or a \ followed by the prefix MRTZ_. The interpreter is case sensitive. Most of the commands has to be written in one line with all their parameters. Only the first source-command or block after the Moritz-command is affected. If more than one command should be affected all commands have to be part of a block.

Every command has to be put over the source-line or source-block that should be affected by the command. If the affected source-command contains a source-block with sub-commands like loop-commands or decision-commands the sub-commands are also affected. If a moritz-command is inserted over a block of lines ( for example in C/C++ over a{ ) all source-lines of the block ( for example in C/C++ between { and } ) are affected. But it is not recommended to use normal block-building technics of your programming-language ( for example in C/C++ using { and } ) to create a command-block for Moritz only. Use the spezial-commands MRTZ_beginBlock and MRTZ_endBlock instead.






Files available to Download

If you take a look to the download-section of Moritz you will find several files in the main-release of Moritz 2:

  • Moritz2_WIN32_YYYY_MM_DD.zip / Moritz2_Linux_YYYY_MM_DD.zip

    This are the distributions for windows and Linux (Suse-Linux was used to build the Linux-version. But its only a terminal-program so it should work on other Linux-distributions also I hope).
    If you unzip the files you will get a directory that contains several sub-directories:
    bin binaries of Moritz :
    • abc2xml; parser-tool to transfer the source-content into an xml parser-tree
    • xml2abc; generator-tool to create the diagram decribing scripts
    cfg user-configuration of Moritz and doxygen
    src example sources
    xml output-files of abc2xml witch are the inputput-files for xml2abc
    nsd html nassi shneiderman diagram output of Moritz
    des description-tables made by Moritz
    dot uml activity diagram-output of Moritz
    AddTxt and picture additional input-files for Doxygen to create the user documentation
    html and chm user documentation created by Doxygen

    The batch-file "xyz_create.bat" or the shell-script "xyz_create.sh" controls the generation of the diagrams by Moritz for the programming-language xyz and the generation of a documentation by Doxygen .

  • Moritz2_UserProject_YYYY_MM_DD.zip

    This archive contains only a supset of folders and configuration-files available in the real distribution. But it can be used as a project-template. Te idea behind is to have the distributen only onetimes in your system and to use several copies of the user-project folder for several source-projects.

    The user-project contains templates of all necessary configuration-files used by commonly to define the files to analyse and the basic behavior of Moritz. Furthermore it contains all folders necessary to store the results.

    Thus the distribution itself contaims no parts associated with a special source-project. But it contains all parts wich are used for all projects in the same way.

  • Moritz2_UserDoku_xyz_YYYY_MM_DD.chm / Moritz2_UserDoku_xyz_YYYY_MM_DD.zip

    This is the user-documentation where the examples are written in the programmimg-language xyz. On windows you may prefer the chm-file for all others operation-systems use the zip-file it contains the documentation in html-format.

  • ReadMe_YYYY_MM_DD.txt

    This text-file contains a short introduction and the latest user information some info to build it from the sources and the change-history of Moritz.

  • src_Moritz2_YYYY_MM_DD.zip

    The zip-file contains the source-files of abc2xml if you want to build Moritz by your self. In addition you will find in the latest versions a project-file for the freeware IDE Code::Blocks . If you want to build the parser-tool also by your own please download its source files at MuLanPa . The download-structure of this project is similar to the one of Moritz.

    Note! Since both binaries are using the parser-library Spirit that is part of the huge boost-package you have to download it from boost extra. Once you extracted boost, you have to correct the search-path inside the Code::Blocks project-file.

    If you build abc2xml and xml2abc you will only get this binaries. Thus you have to download on of zip-distributions also to get the base-version of the configuration-files. Without this file Moritz will not work.


(Note the postfix "_YYYY_MM_DD" is the date of creation in the format Year,Month,Day)



Some releases contain developer-documentation also. This are the results if you use Doxygen and Moritz together to document the code of Moritz. Some release-steps makes it necessary to redesign the code to make the sources less complex. In this cases there will no developer-documentations added to the release because they are no good examples. If you are interested in, please download the developer-documentation of an older release or make the documentation by your self.



There is also a package with the name "Moritz_User_AddOns". This is the place where user-contributions will be available. Every contribution will get an own "release". If the contribution is updated the new file will be added to the release. Part of the file-name will be the date in the formate "_YYYY_MM_DD".



Even the older Moritz 1 downloads are stil available a new user should always download the latest Version of Moritz 2. Moritz 1 is only able to deal with the programming-laguage C/C++. And it will not be suported anymore. Thus older users are recomended to change also.






Content

Purpose
Introduction
Controlling Scripts
MRTZ Commands
Download


Project Links

Sourceforge Project Page
Discussion
Bugs and Requests
Download Files
MuLanPa


Additional Links

Doxygen
Graphviz (Dot)
boost
Spirit
TinyXml
Code::Blocks
m2cpp.pl doxygen-filter for matlab
pas2dox.exe doxygen-filter for pascal