Merge pull request #1411 from Yakindu/issue/1395_write_sctunit_documentation

SCTUnit documentation

plugins/org.yakindu.sct.doc.user/build.xml

@@ -322,7 +322,7 @@
                         <file name="user-guide/statechart_language.textile" />
                         <file name="user-guide/generating_code.textile" />
                         <file name="user-guide/generating_code_headless.textile" />
-                        <!-- <file name="user-guide/sctunit.textile" /> -->
+                        <file name="user-guide/sctunit.textile" />
                     </filelist>
                 </textile-files>
                 <image-files>

plugins/org.yakindu.sct.doc.user/css/yakindu.css

@@ -247,3 +247,16 @@ body.eclipsehelp {
     content: "";
     counter-increment: none
 }
+
+.body-container .primary .example {
+    border-style: solid;
+    border-width: 1px;
+    border-color: #cccccc;
+    border-radius: 4px;
+    background-color: #e8f2fe;
+    padding-top: 1ex;
+    padding-bottom: 0.5ex;
+    padding-right: 1em;
+    padding-left: 1em;
+    margin-bottom: 1ex;
+}

plugins/org.yakindu.sct.doc.user/image-tools/create_grammar_images.sh

@@ -1,14 +1,58 @@
 #!/bin/sh
 
-# Path + prefix of non-terminal symbols image files (PNG):
-nti="../src/user-guide/images/docu_grammar_020_"
+# This script assembles aggregated railway graph images from logically
+# (basic) related railway graph images.
+#
+# 1. Railway graph images *.png should exist.
+# 2. The script crops all these images, puts a white border around them, and writes
+#    them into a working directory as PPM files. That is, the user does not have to
+#    provide properly cropped images, but just rough cuts of individual productions
+#    from an Xtext syntax graph.
+# 3. The script creates images of groups of related railway graph images by calling
+#    the (internally defined) "create_grammar_image" command. For example, running
+#    the command
+#
+#        create_grammar_image reaction-effect \
+#            reactioneffect \
+#            eventraisingexpression
+#
+#    expects the files "docu_grammar_020_reactioneffect.ppm" and
+#    "docu_grammar_020_eventraisingexpression.ppm" to exist in the working directory.
+#    These images are concatenated top to bottom in the given order, i.e. "reactioneffect"
+#    on top, "eventraisingexpression" below, and the result will be written to the
+#    file "${docuAgi}reaction-effect.png".
 
-# Path + prefix of aggregated image files (PNG):
-agi="../src/user-guide/images/docu_grammar_030_"
 
-# Working directory containing PPM version of grammar image files:
+# Working directory containing PPM versions of grammar image files:
 wd="work"
 
+# Prefix of statechart language non-terminal symbols image files:
+docuNtiPrefix="docu_grammar_020_"
+
+# Prefix of statechart language aggregated symbols image files:
+docuAgiPrefix="docu_grammar_030_"
+
+# Path + prefix of statechart language non-terminal symbols image files (PNG):
+docuNti="../src/user-guide/images/${docuNtiPrefix}"
+
+# Path + prefix of statechart language aggregated image files (PNG):
+docuAgi="../src/user-guide/images/${docuAgiPrefix}"
+
+
+# Prefix of statechart language non-terminal symbols image files:
+sctunitNtiPrefix="sctunit_grammar_020_"
+
+# Prefix of statechart language aggregated symbols image files:
+sctunitAgiPrefix="sctunit_grammar_030_"
+
+# Path + prefix of statechart language non-terminal symbols image files (PNG):
+sctunitNti="../src/user-guide/images/${sctunitNtiPrefix}"
+
+# Path + prefix of statechart language aggregated image files (PNG):
+sctunitAgi="../src/user-guide/images/${sctunitAgiPrefix}"
+
+
+
 setup_workdir()
 {
     if [ \! -e ${wd} ]
@@ -16,24 +60,27 @@ setup_workdir()
 	echo "Creating working directory ${wd}."
 	mkdir -p ${wd}
 	echo "Populating working directory with PPM images."
-	for i in ${nti}*.png
+	for i in ${docuNti}*.png ${sctunitNti}*.png
 	do
-	    pngtopnm ${i} | pnmcrop | pnmmargin -white 10 >"${wd}/`basename $i .png`.ppm"
+	    ppmWorkFile="${wd}/`basename $i .png`.ppm"
+	    pngWorkFile="${wd}/`basename $i`"
+	    pngtopnm ${i} | pnmcrop | pnmmargin -white 10 >"${ppmWorkFile}"
+	    pnmtopng -compression 9 "${ppmWorkFile}" >"${pngWorkFile}"
 	done
     fi
 }
 
 create_grammar_image()
 {
-    local targetName="$1";
+    local targetName="$1"
     shift
     n=""
     for i in $*
     do
-	n="${n} ${wd}/docu_grammar_020_${i}.ppm"
+	n="${n} ${wd}/${ntiPrefix}${i}.ppm"
     done
     local outputFile="${agi}${targetName}.png"
-    echo "Creating grammar image file ${outputFile}."
+    echo "Creating grammar image file ${outputFile}"
     pnmcat -topbottom -jleft ${n} | \
 	pnmtopng -compression 9 >"${outputFile}"
 }
@@ -41,6 +88,10 @@ create_grammar_image()
 
 setup_workdir
 
+ntiPrefix="${docuNtiPrefix}"
+agiPrefix="${docuAgiPrefix}"
+agi="${docuAgi}"
+
 # Transition: overview
 create_grammar_image transition-overview \
     transitionreaction \
@@ -114,3 +165,36 @@ create_grammar_image event-specification-overview \
 create_grammar_image guard-condition-overview \
     reactiontrigger \
     guard
+
+
+
+#
+# SCTUnit grammar
+#
+
+ntiPrefix="${sctunitNtiPrefix}"
+agiPrefix="${sctunitAgiPrefix}"
+agi="${sctunitAgi}"
+
+# Test package
+create_grammar_image test_unit \
+    testpackage \
+    packageimport \
+    namedsctunitelement \
+    sctunitelement
+
+# Operation
+create_grammar_image operation \
+    sctunitoperation \
+    statementblock \
+    teststatement
+
+# Assertion
+create_grammar_image assertion \
+    assertionstatement \
+    verifystatement
+
+# Process
+create_grammar_image proceed \
+    proceedexpression \
+    proceedunit

plugins/org.yakindu.sct.doc.user/misc/checkLinks.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+
+# Check links in the generated documentation. This script runs on Linux and
+# assumes the "linkchecker" program to be installed.
+#
+
+requiredBaseDir="org.yakindu.sct.doc.user"
+
+
+
+#
+# Check whether this script is executed in the required base directory.
+#
+dir=`pwd`
+basedir=`basename ${dir}`
+if [ "${basedir}" != "${requiredBaseDir}" ]
+then
+    echo "This script must be executed in the …/${requiredBaseDir} directory."
+    echo "Please \"cd\" to the …/${requiredBaseDir} directory and retry!"
+    exit 1
+fi
+
+
+#
+# Common options for both linkchecker runs:
+#
+commonOptions="--anchors --check-css --check-extern --check-html --recursion-level=1 --stdin"
+
+
+
+if [ "$1" = "--website" -o "$1" = "--both" ]
+then
+
+    # Check links in the website documentation:
+
+    find website -name "*.html" | \
+        linkchecker ${commonOptions} \
+        --ignore-url="PLUGINS_ROOT/org\.eclipse\.platform\.doc\.user/gettingStarted/qs-01\.htm" \
+        --ignore-url="file:///.+com\.yakindu\.traceability\.help/website/fonts/" \
+        --ignore-url="file://static.hsappstatic.net/social_shared/static-2.2815/img/followme/icon_twitter.png" \
+        --ignore-url="file:///_hcms/raw-resource" \
+        --ignore-url="file://info\.itemis\.com/hs-fs/hubfs/itemis_Logos/itemis-Marke-200.png" \
+        --ignore-url="file://info.itemis.com/hs-fs/hubfs/Yakindu-Bildmarke.png" \
+        --ignore-url="file://static.hsappstatic.net/social_shared/static-2.2815/img/.*" \
+        --ignore-url="file://cdn2.hubspot.net/hub/" \
+        --ignore-url="file://.+/com.yakindu.traceability.help/website/%7B%7B%20site_settings.favicon_src%20%7D%7D" \
+        --ignore-url="file://.+/com.yakindu.traceability.help/website/%7B%7B%20get_public_template_url" \
+        --ignore-url="file://.+/com.yakindu.traceability.help/user-guide/"
+elif [ "$1" = "--eclipsehelp" -o "$1" = "--both" ]
+then
+
+    # Check links in the Eclipsehelp documentation:
+
+    find help -name "*.html" | \
+        linkchecker ${commonOptions} \
+        --ignore-url="PLUGINS_ROOT/org\.eclipse\.platform\.doc\.user/gettingStarted/qs-01\.htm"
+else
+    echo "Usage: $0 [ --website | --eclipsehelp | --both ]"
+fi

plugins/org.yakindu.sct.doc.user/src/user-guide/c-domain.textile

@@ -5,7 +5,7 @@ p.
 
 p(edit-on-github). "Edit on GitHub":https://github.com/Yakindu/statecharts/edit/master/plugins/org.yakindu.sct.doc.user/src/user-guide/c-domain.textile
 
-h1(#cdom_deep-c-integration). Deep C Integration: Integrating your C source code with your state machines
+h1(#cdom_deep-c-integration). Deep C integration: Integrating your C source code with your state machines
 
 h2(#cdom_introduction). Introduction