Moritz Files

   Moritz 2.1.0 Distribution

Copyright (C) 2004-2020 by Eckard Klotz.

Permission to use, copy, modify, and distribute this software and its
documentation under the terms of the GNU General Public License is hereby
granted. No representations are made about the suitability of this software for
any purpose. It is provided "as is" without express or implied warranty.
See the GNU General Public License for more details.

Documents produced by Moritz are derivative works derived from the input used in
their production; they are not affected by this license.

As help-tool for Doxygen (www.Doxygen.org) Moritz was original designed as a
source-code analysing program that generates nassi-shneiderman diagrams of the
functions and methods. But this version may also be used to analyse other
xml-content to generate data-tables or other files.

Natively this diagrams are stored as html-files. Moritz may be also used to
generate dot-scripts. Thus it is possible to generate real graphics by using dot
from the graphviz-toolkit (www.graphviz.org). The output of Moritz may be
included in a documentation generated by Doxygen via commands like htmlinclude
or dotfile.

The old Moritz has no  own source parser and uses the xml-output of an other parser-
program as base-information. But this new designed version of Moritz comes along
with on own parser-tool named abc2xml formally known as MuLanPa
(www.sourceforge.net/projects/mulanpa/) that analyses the source-code to generate
xml-files which represent the algorithm and data-structure of the source.
abc2xml will be configured by external grammar-description. Thus it may be may be
used for several programming-languages. the binary of Moritz itself has also a new
name xml2abc to make clearer what it does

abc2xml and xml2abc are console or terminal application which have to be started
via command line. Both programs are controlled by an external configuration-
files like a grammar specification that describes the programming-language, a
snippet-specification that describes the diagram-scripts and xml-defined
configurations of the behaviour-details.

You can find more information under "www.sourceforge.net/projects/Moritz/"
use the forum.


The windows version was build by using libraries from the "mingw-w64 project". Since this libraries are distributed not under GPL but under as BSD like licence I have to include their licence agreement here also:


////////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2011 mingw-w64 project
// 
// Permission is hereby granted, free of charge, to any person obtaining a
// copy of this software and associated documentation files (the "Software"),
// to deal in the Software without restriction, including without limitation
// the rights to use, copy, modify, merge, publish, distribute, sublicense,
// and/or sell copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
// 
// 
// /*
//  * Parts of this library are derived by:
//  *
//  * Posix Threads library for Microsoft Windows
//  *
//  * Use at own risk, there is no implied warranty to this code.
//  * It uses undocumented features of Microsoft Windows that can change
//  * at any time in the future.
//  *
//  * (C) 2010 Lockless Inc.
//  * All rights reserved.
//  *
//  * Redistribution and use in source and binary forms, with or without modification,
//  * are permitted provided that the following conditions are met:
//  *
//  *
//  *  * Redistributions of source code must retain the above copyright notice,
//  *    this list of conditions and the following disclaimer.
//  *  * Redistributions in binary form must reproduce the above copyright notice,
//  *    this list of conditions and the following disclaimer in the documentation
//  *    and/or other materials provided with the distribution.
//  *  * Neither the name of Lockless Inc. nor the names of its contributors may be
//  *    used to endorse or promote products derived from this software without
//  *    specific prior written permission.
//  *
//  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AN
//  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
//  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
//  * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
//  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
//  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
//  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
//  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
//  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
//  * OF THE POSSIBILITY OF SUCH DAMAGE.
//  */
////////////////////////////////////////////////////////////////////////////////


First Steps

    Start the bat/sh-file named MxMrtz. It should a start demo-run of abc2xml and
    xml2abc. If this process ends successfully you can find an xml-output of
    abc2xml in the folder xml, the html-output of xml2abc in the folder nsd
    and the dot-output of xml2abc in the folder dot.

    Copy your own sources in to the folder src and delete the original example-
    sources or rename their file-attachments. Look in to the folder nsd to watch
    the results.

Command-Line Arguments

Command-Line arguments are used to give Moritz some base-informations about the
directories and file which should be used .

The following argument tells the both binaries to use another configuration-file:
CF[configuration-file] file with detail-configurations default are abc2xml_cfg.xml
and xml2abc_cfg.xml

The following argument may be used to override the equal information in the
used configuration-file:
DP[destination-path] destination-path of the created diagrams


Here are some examples:

abc2xml DP.\xml\ CFabc2xml_cfg.xml > abc2xml.txt
xml2abc DP.\nsd\ CFxml2abc_cfg.xm > xml2abc.txt

This win32-example starts abc2xml to create xml-files at "ROOT\xml" and
xml2abc to create nassi-sheiderman-files at "ROOT\nsd". The
resource-path is the home-directory of Moritz.

abc2xml CFhome:/project/config/abc2xml_cfg.xml
xml2abc CFhome:/project/config/xml2abc_cfg.xml

This Linux-example starts abc2xml and xml2abc with the own configuration-files
in the directory "home:/project/config". All other informations are placed in
this configuration file.

If you have an other operation-system you have to download the source-files and
compile them on your system you have change the bat-file into a shell-script of
your system also.

Using the help argument of xml2abc

Moritz offers a help-argument to provide on-line information

xml2abc -> general program-information
xml2abc help -> shows this text
xml2abc help All -> shows all help-information (re route it into a file!)
xml2abc help Resources -> general overview about the needed resource-files
xml2abc help Arguments -> general overview about the command-line arguments
xml2abc help DP -> describes the destination-path argument
xml2abc help CF -> describes the configuration-file argument

To build xml2abc and abc2xml a unified source-package ais avilable parallel to the distribution.



abc2xml and xml2abc are common console-applications and now no special libraries are necessary.
 In the Moritz2 releases before Spirit: http://www.boost.org was used also. But starting with the version 2.0.90 Moritz is using a new self developed parser-module. Thus the extra download of the boost-library will not be necessary anymore.
 In the Moritz2 releases before TinyXml:http://sourceforge.net/projects/tinyxml was used also. But starting with version 2.0.93 Moritz is using a new self developed xml-module. 

Please note the exchange of the used parser-parts and xml-parts are not ment as a kind of mistrust in Spirit, boost or TinyXml. 

 Even there may be some points which I don't like with Spirit, I still think that Spirit is a very good parser library that is dooing its job as long as it is used in the way as specified by its autors. But especially the last point is not the case with Moritz since the parser-syntax is defined in a script-file that will be read by the too while its runtime. Furthermore the parser-output should be a xml-like parser tree.
 Thus I developed an own parser but I was able to do so since I learnd with Spirit how a parser works.

 The same is the case with TinyXml. But since the used flavour of TinyXml (2.x.y) will not be supported anymore I already had to extend it by my self in the past. Furthermore it creates a lot of warnings with static test tools. 
 Thus based on my own parser library I created my own xml library


I'm not very familiar with make-files and use an ide (DevC++, Code-Blocks,
MinGW Developer-Studio, ...) to manage the project and the compile process.

For me the steps to build is to:
 add the sources into the ide-project,
 add the h-paths as search-pathes
 define 3 over-all preprocessor-constants (wihout-values):

  1. either NO_SYSTEM_FOR_FOLDERCREATE or SYSTEM_FOR_FOLDERCREATE
  2. either WINDOWS or LINUX (depending on yotr operation-system,
                              you may define nothing or something else for others )
 and start the build-process
 the use of optimation-options can be reduce the size and/or speed it up
(The definition of "NO_SYSTEM_FOR_FOLDERCREATE" has to be used if the compiler
 supports the c-command "mkdir(c_string)". if not use "SYSTEM_FOR_FOLDERCREATE")

Since this distribution contains doxygen-configurations also and with the version 1.9.08 the languages Matlab and Pascal are supported also two third-party filters are added in the associated LangPack folders:

Matlab:
Filter: m2cpp.pl
Author: Fabrice
Internet: http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab

Pascal:
Filter: pas2dox.exe
Author: Darren Bowles
Internet: http://sourceforge.net/projects/pas2dox


The sources are maintained by using the Code::Blocks IDE
 Author:   code::blocks project 
 Internet: http://www.codeblocks.org/

The configuration scripts (a2x, x2a, xml) are maintained by using PSPad
 Author:   Jan Fiala 
 Internet: http://www.pspad.com/

Dynamic source test are done by using unittest-cpp
 Author:   Patrick Johnmeyer
 Internet: https://github.com/unittest-cpp/unittest-cpp

Static source analysis are done by using Cppcheck
 Author:   Daniel Marjamäki
 Internet: http://cppcheck.sourceforge.net/

The documentation is done by using:
 Doxygen
  Author:   Dimitri van Heesch.
  Internet: http://www.stack.nl/~dimitri/doxygen/ 
 Graphiz (Dot)
  Author:   AT&T
  Internet: http://www.graphviz.org/
 

The windows distribution was build by using MinGW in the "TDM-GCC Compiler Suite for Windows" 
 Author:   John E. / TDM 
 Internet: http://tdm-gcc.tdragon.net/
 
 This compiler suite contains links against libraries from the mingw-w64 project
  Author:   mingw-w64 project 
  Internet: http://mingw-w64.org/doku.php





 Change Log
Version 1.9.01 
 Alpha Release of Moritz2
Version 1.9.02 
 Debugging: Under linux pseudo paths "." and ".." produces pseudo output by using tag "FolderName" -> check of file attachment changed
 Refactoring: Renaming of the binary from Moritz in xml2abc. The new name stands for the conversion of a text written in xml  into (2) a defined language (abc).
 New feature: The new implementation of special commands to control the shape of the diagrams has stated
Version 1.9.03
 New feature: Grammar and snipets for c and c++. note compiler switches are not supported yet
Version 1.9.04
 Refactoring: The code of the formally generator class ("Generator_Nsd") is now relocated into new tool classes("SnippetExecution" and "Cmnd_XYZ") to make the code better understandable
 Refactoring: The evaluation of the snipet content will now be done before the diagram generation to make the generation process it self faster.
 New feature: It is now possible to split the xml configuration in separate files. Thus it is possible have a project depending user part and a more tool depending background part.
 New feature: The binary abc2xml is now able to check the change time of source and destination files to avoid an unnecessary analysis if the source has not changed. Thus a analysis of a folder content is faster if only some files have changed.
 New feature: The binary abc2xml tries to create directories for content to save in files if a simple save is not possible for example since the destination folder does not exist.
Version 1.9.05
 Refactoring: Moved some methods and attributes from between classes to eliminate include-cycles
 Refactoring: Introduced namespaces in sources
Version 1.9.06
 New feature: new snipet commands make it possible to construct temporary independent xml trees which contain copies or cutouts of the xml trees to analyse or trees defined by other snipets. This new xml trees can be used to create diagram parts like part trees of the xml trees to analyse. in the example distribution this will be used to insert links into the diagrams which refer to the documentation created by doxygen.
 Refactoring: help output in the console window is reduced now since the amount of program arguments is reduced.
Version 1.9.07
 Refactoring: As parser libry spirit 2.5.2 (now part of boost 1.52.0) or higher is used now instead of spirit 1.8.5. this change has no direct effect for the end-user but for those who want to build the binary by them own.
 Refactoring: The xml output of the parser structure (currently only used as internal part of xml2abc) contains now more information to enable a correct generation of rule-diagrams for documentation-purpose.
 Refactoring: To reduce the amount of sources the content of "notation_log.h" was moved into the files "notation.h" and "notation.cpp" 
 Debugging: sometimes newline characters in parser rules (currently only used as internal part of xml2abc) were used as part of identifier names and sometimes not, thus it was not possible to place a rule-name after a line change at the beginning of a new line. space character, newline, linefeed and tab characters will be replaced by an empty string in the rule name
Version 1.9.08
 New feature: As alternative to html based nassi*shneiderman diagrams moritz comes now with a an additional configuration to create dot based uml like activity diagrams.
 New feature: inside of macro sequences the replacement procedure can be used to replace part strings of the snipet that should be used as macro content. This replacements can be used like parameters of the macro where the first value of a replacement procedure defines the snipet part to replace and the second value the new text to use instead.
 New feature: Matlab an Pascal will now be supported with examples. Even the support of this programming languages is still under development it is stable enough to be tested by users. Please check it out and post problems or proposals in the forum. 
Version 1.9.09
 Refactoring: For making it easier to have one configuration for different operation systems (linux, windows, ...)  the use of a replacement mechanism for separators in path strings was implemented.  
 New feature: To enable a split between the distribution and the user project all file definitions inside the process konfiguration files located in the folders of LangPack contain now a new attribute called root that contains the name of a tag used in the user configuration located in the cfg folder this tag called LangPackPath defines a root path absolute or relative to the directory used to start the binary.
 New feature: To implement statistical outputs a new procedure is available to count in a xml sub tree child nodes with a special name.
Version 1.9.10
 New feature: To format the output text fortmat symbols can be used to control indent and unindent to insert tabyfining spaces or a constant number of spaces or special ascii characters.
Version 1.9.11
 New feature: To save time new procedures can be used to check if the result is already existing and valid to skip parts of analysis if not necessary.
 New feature: parser procedures makes it possible to parse textual parts of the input again to create more detailed xml content. 
Version 1.9.12
 Debugging: If a file contains only one line with out a line brake at the end the read loop is endless since end-of-file will not be detected. -> the read function reads now the file character for character and counts the read characters. The loop ends if the number reaches the file size or end-of-file will be detected.
 Debugging: XML comments lead to crash. -> XML iterations will be done by using TixmlNode instead of TiXmlElement, as first action in the loop a macro checks if the current element is a xml comment and forces immediatly the start of the next loop.
Version 1.9.13
 Refactoring: To increase speed of parsing process the parser rules will only initialized with debug action if debugging will really be used 
Version 2.0.0
 main release
Version 2.0.1
 As new feature the following xml procedures where added:
     xmlInsert       insert a new xml child treated as independent xml node
     xmlPrint        print a special part of the given xml element
     ifXmlEqual      define an equal to test on a current xml element to decide if the rest of the current sequence should be processed
     ifXmlUnequal    define an unequal to test on a current xml element to decide if the rest of the current sequence should be processed
     ifXmlExisting   define an equal to test on a current xml element to decide if the rest of the current sequence should be processed
     ifXmlMissing    define an unequal to test on a current xml element to decide if the rest of the current sequence should be processed
 Refactoring: changes in the internal use of name spaces to have a better display in ide symbol browsers
Version 2.0.2
 Debugging: First file in a new created folder will be saved by xml2abc without replacing format symbols -> in the associated function the command to format the output was moved to be used always
 Refactoring: As a preparation of creation of message sequents charts the all language package files where sorted into additional sub-folders to keep a kind of order.
  But for the user this makes it necessary to change the the configuration-files located in the cfg folder a little bit:

   The abc2xml configuration LANGUAGE_abc2xml_cfg.xml contains as last sub node :
    <Process includeFile="./LangPack/ansi_c/abc2xml_Process_LANGUAGE.xml"    root="LangPackPath"/>  
   Since the file abc2xml_Process_LANGUAGE.xml was moved into the sub folder a2x the includeFile has to be extended:
    <Process includeFile="./LangPack/ansi_c/a2x/abc2xml_Process_LANGUAGE.xml"    root="LangPackPath"/> 

   The xml2abc configuration LANGUAGE_xml2abc_cfg_XYZ.xml contains as last sub node :
    <GeneratorNSD includeFile="./LangPack/ansi_c/xml2abc_Process_LANGUAGE_XYZ.xml" root="LangPackPath" />  
   Since the file abc2xml_Process_LANGUAGE.xml was moved into the sub folder x2a_XYZ the includeFile has to be extended:
    <GeneratorNSD includeFile="./LangPack/ansi_c/x2a_nsd/xml2abc_Process_LANGUAGE_XYZ.xml" root="LangPackPath" /> 
    
 New feature: The user is able to define own application arguments which define the content of replacements inside the xml configuration.
 New feature: The destination will be created now if it is not already existing, thus the user has not to prepare it anymore. 
 New feature: For the programming language C/Cpp (other programming languages will follow) dot collections will be created as txt files which contain doxygen special c comments. This txt files can be used as doxygen input files but the file attachment txt has to be added in the FILE_PATTERNS.
 New feature: For the programming language C/Cpp (other programming languages will follow) a new xml2abc configuration package is added in the associated "LangPack" folder to support the generation of message sequence diagrams.
Version 2.0.90
 Refactoring: Exchange of the Spirit parser library by an own parser.
 Refactoring: Extension of the scripts to parse c/cpp file and generate output for them    
Version 2.0.91 
 Refactoring: Since the parser generates now doxygen associated comment scripts automaticaly the comments in the a2x-files are reduced. Furthermore old outcommented parts are removed. 
Version 2.0.92 
 Refactoring: Reduction of dependency against tiny xml in transform processes. The used Version of tynyxml is not supported anymore by its author. Thus it has to be replaced somewhen also  
Version 2.0.93 
 Refactoring: Complete replacement of tiny xml by own xml library.
Version 2.0.94
 Refactoring and debugging to prepare a new major release. The binaries are now buildable on Linux again.
Version 2.0.95
 Refactoring and debugging to prepare a new major release. Debugging and code optimization done. Windows distribution also done with a 64 bit compiler and not only with a 32 bit compiler.
Version 2.1.0 
 primary Windows binaries in bin folder compiled as 64 bit exe files with MinGW 9.2.0 published by TDM located in sub folder bin.
 secondary Windows binaries in bin folder compiled as 32 bit exe files with MinGW 9.2.0 published by TDM  located in sub folder bin_32.
 in the case of using the 32 bit binaries rename sub folder bin into bin_64 and sub folder bin_32 into bin.