Code generation documentation split into multiple Textile files (#1915)

* Intermediate results

* Chapter numbering fixed.

* Code generation documentation split into multiple files; Eclipse help restructured.

* Bug fixed.

* Documentation of SGen features are now looked for in ALL documentation files.

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

@@ -197,7 +197,12 @@
                 <include name="user-guide/c-domain.textile" />
                 <!-- include name="user-guide/typescript-domain.textile" / -->
                 <include name="user-guide/statechart_language.textile" />
-                <include name="user-guide/generating_code.textile" />
+                <include name="user-guide/code_generation_intro.textile" />
+                <include name="user-guide/code_generation_c.textile" />
+                <include name="user-guide/code_generation_cpp.textile" />
+                <include name="user-guide/code_generation_java.textile" />
+                <include name="user-guide/code_generation_statechart_image.textile" />
+                <include name="user-guide/code_generation_custom.textile" />
                 <include name="user-guide/generating_code_headless.textile" />
                 <include name="user-guide/sctunit.textile" />
                 <!-- <include name="user-guide/glossary.textile" /> -->
@@ -206,7 +211,7 @@
             <!-- Check whether we have all the expected textile source files – no more, no less: -->
             <fail message="Number of textile source file(s) doesn't match.">
                 <condition>
-                    <resourcecount refid="fileset.eclipsehelp" when="ne" count="10" />
+                    <resourcecount refid="fileset.eclipsehelp" when="ne" count="15" />
                 </condition>
             </fail>
 
@@ -392,7 +397,12 @@
                         <file name="user-guide/c-domain.textile" />
                         <!-- file name="user-guide/typescript-domain.textile" /-->
                         <file name="user-guide/statechart_language.textile" />
-                        <file name="user-guide/generating_code.textile" />
+                        <file name="user-guide/code_generation_intro.textile" />
+                        <file name="user-guide/code_generation_c.textile" />
+                        <file name="user-guide/code_generation_cpp.textile" />
+                        <file name="user-guide/code_generation_java.textile" />
+                        <file name="user-guide/code_generation_statechart_image.textile" />
+                        <file name="user-guide/code_generation_custom.textile" />
                         <file name="user-guide/generating_code_headless.textile" />
                         <file name="user-guide/sctunit.textile" />
                         <!-- file name="user-guide/glossary.textile" / -->

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

@@ -4,8 +4,8 @@
    <context id="sc_properties_entry_entrykind" title="Entry">
       <description>An entry, possibly with a shallow or deep history, defines which state is to be activated first in a state machine or region.</description>
       <topic href="help/user-guide/statechart_language.html#entry" label="Entry"/>
-      <topic href="help/user-guide/statechart_language.html#shallow-history" label="Shallow History state"/>
-        <topic href="help/user-guide/statechart_language.html#deep-history" label="Deep History state"/>
+      <topic href="help/user-guide/statechart_language.html#shallow-history" label="Shallow history state"/>
+        <topic href="help/user-guide/statechart_language.html#deep-history" label="Deep history state"/>
    </context>
    <context id="sc_properties_state_expression" title="State">
       <description>States are central elements of a state machine.</description>
@@ -20,15 +20,15 @@
       <topic href="help/user-guide/statechart_language.html#transition" label="Transition reference"/>
    </context>
    <context id="sgen_feature" title="Genmodel Features">
-      <topic href="help/user-guide/generating_code.html" label="Generating state machine code"/>
+      <topic href="help/user-guide/code_generation_intro.html" label="Generating state machine code"/>
    </context>
    <context id="headless_feature" title="Headless Features">
-      <topic href="help/user-guide/generating_code_headless.html" label="Headless Generating"/>
+      <topic href="help/user-guide/generating_code_headless.html" label="Headless code generation"/>
    </context>
    <context id="stext_keyword">
-      <topic href="help/user-guide/statechart_language.html" label="YAKINDU Statechart Tools User Guide"/>
+      <topic href="help/user-guide/statechart_language.html" label="YAKINDU Statechart Tools user guide"/>
    </context>
    <context id="sctunit_keyword">
-      <topic href="help/user-guide/sctunit.html" label="YAKINDU Statechart Tools SCT Unit"/>
+      <topic href="help/user-guide/sctunit.html" label="YAKINDU Statechart Tools SCTUnit"/>
    </context>
 </contexts>

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

@@ -45,16 +45,23 @@ do
     esac
 done
 
+commonExcludes="https://github.com/Yakindu/.*|mailto:.*|https://itemisag.wistia.com/medias/9ek8usz18r|https://bugs.eclipse.org/.*"
 if [ "${target}" == "eclipsehelp" ]
 then
     checklink --broken --dir-redirects \
 	--recursive --depth 1 \
-	--exclude https://github.com/Yakindu/.* \
+	--exclude "${commonExcludes}" \
 	${prefix}user-guide/c-domain.html \
+	${prefix}user-guide/code_generation_cpp.textile \
+	${prefix}user-guide/code_generation_c.textile \
+	${prefix}user-guide/code_generation_custom.textile \
+	${prefix}user-guide/code_generation_intro.textile \
+	${prefix}user-guide/code_generation_java.textile \
+	${prefix}user-guide/code_generation_statechart_image.textile \
 	${prefix}user-guide/editing_statecharts.html \
 	${prefix}user-guide/generating_code_headless.html \
-	${prefix}user-guide/generating_code.html \
 	${prefix}user-guide/glossary.html \
+	${prefix}user-guide/installation.html \
 	${prefix}user-guide/overview.html \
 	${prefix}user-guide/sctunit.html \
 	${prefix}user-guide/simulating_statecharts.html \
@@ -65,7 +72,7 @@ elif [ "${target}" == "web" ]
 then
     checklink --broken --dir-redirects \
 	--recursive --depth 1 \
-	--exclude 'https://github.com/Yakindu/.*|http://groups.google.com/.*|javascript:.*|tel:.*|mailto:.*|https://cta-redirect.hubspot.com/' \
+	--exclude "${commonExcludes}"'|http://groups.google.com/.*|javascript:.*|tel:.*|https://cta-redirect.hubspot.com/' \
 	https://www.itemis.com/en/yakindu/state-machine/documentation/user-guide/ \
 	https://www.itemis.com/en/yakindu/state-machine/documentation/tutorials/ \
         2>&1 | tee log.txt

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

@@ -13,7 +13,12 @@
         <toc file="help/user-guide/c-domain-toc.xml" primary="false"/>
         <!-- <toc file="help/user-guide/typescript-domain-toc.xml" primary="false"/> -->
         <toc file="help/user-guide/statechart_language-toc.xml" primary="false"/>
-        <toc file="help/user-guide/generating_code-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_intro-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_c-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_cpp-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_java-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_statechart_image-toc.xml" primary="false"/>
+        <toc file="help/user-guide/code_generation_custom-toc.xml" primary="false"/>
         <toc file="help/user-guide/generating_code_headless-toc.xml" primary="false"/>
         <toc file="help/user-guide/sctunit-toc.xml" primary="false"/>
         <toc file="help/user-guide/installation-toc.xml" primary="false"/>

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

@@ -1,6 +1,8 @@
 
 h1{%EARLY_SEPARATOR%}. 
 
+==<div style="counter-reset: h1 4">==
+
 ==<div class="pro-feature">==
 
 h1(#cdom_deep_c_integration). Deep C/C++ Integration: Integrating your C/C++ source code with your state machines
@@ -818,3 +820,5 @@ h3(#cdom_please_get_in_touch_with_us). Please get in touch with us
 Please note that the preceding list of restrictions might not be complete. If you discover any further problems, please do not hesitate to contact us! Your feedback is highly appreciated!
 
 ==</div>==
+
+==</div>==

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

@@ -0,0 +1,65 @@
+
+p. 
+
+==<div style="counter-reset: h1 7 h2 7">==
+
+==<div class="pro-feature">==
+
+h2(#codegen_statechart_images_generator). Statechart image generator
+
+The statechart image generator renders a statechart and all its subdiagrams, if any, as image files. The generator supports several pixel-based and vector-based image formats, subject to the capabilities of the Java implementation you are using.
+
+
+h3(#codegen_statechart_images_sample_generator_model). Sample statechart image generator model
+
+The following example is a generator model to create SVG vector images of the _turbineControl_ statechart. The generated images are placed in the _images_ folder, which is located in the _powerPlant_ project.
+
+==<div class="example">==
+
+bc.. GeneratorModel for yakindu::images {
+
+    statechart turbineControl {
+
+        feature Outlet {
+            targetProject = "powerPlant"
+            targetFolder = "images"
+        }
+
+        feature Renderer {
+            format = "svg"
+        }
+    }
+}
+
+p. 
+
+==</div>==
+
+
+h3(#codegen_statechart_images_generator_id). Statechart image generator ID
+
+The statechart image generator's ID is *yakindu::images*. If you are using the YAKINDU generator model configuration wizard to create a generator model, select the _YAKINDU Image Generator_ to place the generator ID into the _.sgen_ file.
+
+
+h3(#codegen_statechart_images_generator_features). Statechart image generator features
+
+h4(#codegen_statechart_images_outlet_feature). Outlet feature
+
+The mandatory *Outlet* feature specifies the project and folder the statechart images will be written to. See section "&quot;Outlet feature&quot;":../user-guide/code_generation_intro.html#codegen_outlet_feature for details.
+
+bq. *Please note:* The image generator supports the *Outlet* feature's _targetProject_ and _targetFolder_ parameters only.
+
+
+==<!-- Start-pro sgen_feature_renderer -->==
+
+h4(#codegen_statechart_images_renderer_feature). Renderer feature
+
+The mandatory *Renderer* feature controls the rendering of the images.
+
+* _format_ (String, required): Format of the generated images. Supported image formats are listed in section "&quot;Exporting_a_statechart_as_an_image_file&quot;":../user-guide/editing_statecharts.html#edit_exporting_a_statechart_as_an_image_file.
+
+==<!-- End-pro sgen_feature_renderer -->==
+
+==</div>==
+
+==</div>==

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

@@ -1,4 +1,8 @@
 
+p. 
+
+==<div style="counter-reset: h1 2">==
+
 h1(#edit_editing_statecharts). Editing statecharts
 
 h2(#edit_creating_and_deleting_statecharts). Creating and deleting statecharts
@@ -944,3 +948,5 @@ p(#edit_fig_preferences_simulation).
 p=. Preferences: Simulation
 
 Set your color preferences for the statechart simulator on this preference page.
+
+==</div>==

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

@@ -1,4 +1,8 @@
 
+p. 
+
+==<div style="counter-reset: h1 1">==
+
 h1(#inst_installing_yakindu_statechart_tools). Installing YAKINDU Statechart Tools
 
 In order to start working with YAKINDU Statechart Tools, you have to install the software on your computer. We are assuming you have downloaded the software package and stored it somewhere on your machine.
@@ -571,3 +575,4 @@ If the list of installed JREs is empty, you are affected by the problem and will
 
 p=. Installed JREs
 
+==</div>==

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

@@ -1,4 +1,8 @@
 
+p. 
+
+==<div style="counter-reset: h1 3">==
+
 h1(#simu_simulating_statecharts). Simulating statecharts
 
 Simulating a statechart model means to execute it, raise events manually, have time-based and other events being triggered automatically, and observe the model's behavior.
@@ -417,3 +421,5 @@ h4(#advsim_deleting_a_snapshot). Deleting a snapshot
 * To delete _all_ snapshots, click at the _remove all_ button !(inlinemediaobject)images/advsim_button_remove_all.png(Button: Remove all)!.
 
 ==</div>==
+
+==</div>==

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

@@ -1,4 +1,8 @@
 
+p. 
+
+==<div style="counter-reset: h1 5">==
+
 h1(#sclang_statechart_language_reference). Statechart language reference
 
 The statechart language is used to describe statecharts. It consists both of graphical and of textual elements.
@@ -479,7 +483,7 @@ The *definition section* is a text area. Per default, it is located to the left
 
 In the definition section, you have to define entities you want to use in your statechart. This includes "variables":#sclang_variables, "events":#sclang_events, and "operations":#sclang_operations. Variables and events have to be defined in the scope of a "named interface":#sclang_interface_scopes or the "internal interface":#sclang_internal_scope. Especially useful for larger parts of a statechart model is the possibility to use "namespaces":#sclang_namespaces.
 
-When it comes to "code generation":../user-guide/generating_code.html#codegen_generating_state_machine_code all these elements are properly reflected in the generated source code as far as the respective target language supports it.
+When it comes to "code generation":../user-guide/code_generation_intro.html#codegen_generating_state_machine_code all these elements are properly reflected in the generated source code as far as the respective target language supports it.
 
 ###. FIXME (RK): Example needed!
 
@@ -662,7 +666,7 @@ Consider, for example, a C function @float read_sensor()@ that should be called
 
 ==</div>==
 
-It is the purpose of a code generator to create a suitable construct in the respective target language for the procedure call. For details on code generation, please see section "&quot;Generating state machine code&quot;":../user-guide/generating_code.html.
+It is the purpose of a code generator to create a suitable construct in the respective target language for the procedure call. For details on code generation, please see section "&quot;Generating state machine code&quot;":../user-guide/code_generation_intro.html#codegen_generating_state_machine_code.
 
 Operations can have none, one, or multiple parameters. A parameter is declared with a name and a type. An operation may have a single or no return type similar to usual programming languages. Please see section "&quot;Types&quot;":#sclang_types for details.
 
@@ -705,7 +709,7 @@ Annotations are metadata that you can add to the definition section of your stat
 
 h4(#sclang_cyclebased). @CycleBased
 
-The <code>@CycleBased</code> annotation specifies that the "_cycle-based execution scheme_":../user-guide/generating_code.html#codegen_execution_schemes is to be used.
+The <code>@CycleBased</code> annotation specifies that the "_cycle-based execution scheme_":../user-guide/code_generation_intro.html#codegen_execution_schemes is to be used.
 
 Synopsis: <code>@CycleBased(</code>_period_<code>)</code>
 
@@ -733,7 +737,7 @@ p.
 
 h4(#sclang_eventdriven). @EventDriven
 
-The <code>@EventDriven</code> annotation specifies that the "_event-driven execution scheme_":../user-guide/generating_code.html#codegen_execution_schemes is to be used.
+The <code>@EventDriven</code> annotation specifies that the "_event-driven execution scheme_":../user-guide/code_generation_intro.html#codegen_execution_schemes is to be used.
 
 Synopsis: <code>@EventDriven</code>
 
@@ -1566,3 +1570,5 @@ p(#sclang_fig_expressions_grammar).
 !images/docu_grammar_010_expressions.png(Expressions grammar)!
 
 p=. Expressions grammar
+
+==</div>==

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

@@ -1,27 +1,30 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>
 
-<toc label="YAKINDU Statechart Tools Documentation">
+<toc label="YAKINDU Statechart Tools documentation">
 
-    <topic label="Overview">
-        <link toc="help/user-guide/overview-toc.xml"/>
+    <topic label="User guide">
+    <link toc="help/user-guide/overview-toc.xml"/>
+    <link toc="help/user-guide/installation-toc.xml"/>
+    <link toc="help/user-guide/editing_statecharts-toc.xml"/>
+    <link toc="help/user-guide/simulating_statecharts-toc.xml"/>
+    <link toc="help/user-guide/c-domain-toc.xml"/>
+    <!-- <link toc="help/user-guide/typescript-domain-toc.xml"/> -->
+    <link toc="help/user-guide/statechart_language-toc.xml"/>
+    <topic label="Generating code" href="help/user-guide/code_generation_intro.html">
+        <link toc="help/user-guide/code_generation_intro-toc.xml"/>
+        <link toc="help/user-guide/code_generation_c-toc.xml"/>
+        <link toc="help/user-guide/code_generation_cpp-toc.xml"/>
+        <link toc="help/user-guide/code_generation_java-toc.xml"/>
+        <link toc="help/user-guide/code_generation_statechart_image-toc.xml"/>
+        <link toc="help/user-guide/code_generation_custom-toc.xml"/>
+        <link toc="help/user-guide/generating_code_headless-toc.xml"/>
+    </topic>
+    <link toc="help/user-guide/sctunit-toc.xml"/>
     </topic>
 
     <topic label="Tutorials">
         <link toc="help/tutorials/tutorials-toc.xml"/>
     </topic>
 
-    <topic label="User Guide">
-        <link toc="help/user-guide/editing_statecharts-toc.xml"/>
-        <link toc="help/user-guide/simulating_statecharts-toc.xml"/>
-        <link toc="help/user-guide/c-domain-toc.xml"/>
-        <!-- <link toc="help/user-guide/typescript-domain-toc.xml"/> -->
-        <link toc="help/user-guide/statechart_language-toc.xml"/>
-        <link toc="help/user-guide/generating_code-toc.xml"/>
-        <link toc="help/user-guide/generating_code_headless-toc.xml"/>
-        <link toc="help/user-guide/sctunit-toc.xml"/>
-    </topic>
-
-    <link toc="help/user-guide/installation-toc.xml"/>
-
 </toc>

plugins/org.yakindu.sct.generator.genmodel.ui/src/org/yakindu/sct/generator/genmodel/ui/help/SGenUserHelpDocumentationProvider.java

@@ -10,11 +10,21 @@
  */
 package org.yakindu.sct.generator.genmodel.ui.help;
 
+import java.net.MalformedURLException;
+import java.net.URL;
 import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.WeakHashMap;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
 import org.eclipse.emf.ecore.EObject;
+import org.eclipse.help.HelpSystem;
+import org.eclipse.help.IToc;
+import org.eclipse.help.ITopic;
+import org.eclipse.help.IUAElement;
 import org.eclipse.xtext.documentation.IEObjectDocumentationProvider;
 import org.yakindu.base.utils.jface.help.AbstractUserHelpDocumentationProvider;
 import org.yakindu.sct.model.sgen.FeatureConfiguration;
@@ -26,11 +36,19 @@ import org.yakindu.sct.model.sgen.FeatureType;
  * @author andreas muelder - Initial contribution and API
  * 
  */
-public class SGenUserHelpDocumentationProvider extends AbstractUserHelpDocumentationProvider implements
-		IEObjectDocumentationProvider {
+public class SGenUserHelpDocumentationProvider extends AbstractUserHelpDocumentationProvider
+		implements
+			IEObjectDocumentationProvider {
 
 	private static final String PLUGIN_ID = "org.yakindu.sct.ui.editor";
 	private static final String CONTEXT_ID = "sgen_feature";
+	private static final String YSCT_LABEL = "YAKINDU Statechart Tools";
+
+	/*
+	 * Documentation cache, maps the resource URL of an HTML file to its actual
+	 * contents:
+	 */
+	private static final Map<String, String> docuCache = new WeakHashMap<String, String>();
 
 	public String getDocumentation(EObject o) {
 		if (o instanceof FeatureConfiguration) {
@@ -52,17 +70,64 @@ public class SGenUserHelpDocumentationProvider extends AbstractUserHelpDocumenta
 		return EMPTY_DOCUMENTATION;
 	}
 
+	/**
+	 * <p>
+	 * Looks up the documentation snippet of an SGen feature <em>name</em> by
+	 * searching all documentation files.
+	 * </p>
+	 * 
+	 * @param name
+	 *            The feature to look for.
+	 * @return the documentation snippet as HTML code.
+	 */
 	protected String getFeatureTypeDocumentation(String name) {
 		name = CONTEXT_ID + "_" + name.toLowerCase();
-		String userHelp = getHelp(PLUGIN_ID + "." + CONTEXT_ID);
-		int beginIndex = userHelp.indexOf("<!-- Start " + name + " -->");
-		int endIndex = userHelp.indexOf("<!-- End " + name + " -->");
-		if (beginIndex >= 0 && endIndex >= 0 && endIndex > beginIndex) {
-			return userHelp.substring(beginIndex, endIndex);
+
+		/* Lookup all help resources, i.e., files containing documentation: */
+		final IToc[] tocs = HelpSystem.getTocs();
+		IToc ysctToc = null;
+		for (final IToc toc : tocs) {
+			final String label = toc.getLabel();
+			if (label.contains(YSCT_LABEL)) {
+				ysctToc = toc;
+				break;
+			}
+		}
+		if (ysctToc == null)
+			return EMPTY_DOCUMENTATION;
+		final Set<String> helpResources = getHelpResources(ysctToc);
+
+		/* Search the help resources found for the feature we ar looking for: */
+		for (final String helpResource : helpResources) {
+			final String href = helpResource.substring(1);
+			String userHelp = docuCache.get(href);
+			if (userHelp == null) {
+				URL url;
+				try {
+					url = new URL("platform:/plugin/" + href);
+				} catch (MalformedURLException e) {
+					e.printStackTrace();
+					continue;
+				}
+				try {
+					userHelp = convertStreamToString(url.openConnection().getInputStream());
+					docuCache.put(href, userHelp);
+				} catch (Exception e) {
+					e.printStackTrace();
+					continue;
+				}
+			}
+
+			int beginIndex = userHelp.indexOf("<!-- Start " + name + " -->");
+			int endIndex = userHelp.indexOf("<!-- End " + name + " -->");
+			if (beginIndex >= 0 && endIndex >= 0 && endIndex > beginIndex) {
+				return userHelp.substring(beginIndex, endIndex);
+			}
 		}
+
 		return EMPTY_DOCUMENTATION;
 	}
-	
+
 	public ArrayList<String> getDocumentedFeatures() {
 		ArrayList<String> features = new ArrayList<String>();
 		String userHelp = getHelp(PLUGIN_ID + "." + CONTEXT_ID);
@@ -77,4 +142,40 @@ public class SGenUserHelpDocumentationProvider extends AbstractUserHelpDocumenta
 
 		return features;
 	}
+
+	/**
+	 * <p>
+	 * Recursively traverses a table of contents and returns a set containing
+	 * all file resource URLs found in the tree.
+	 * </p>
+	 *
+	 * @param toc
+	 *            The {@link IToc} to start at.
+	 * @return see above.
+	 */
+	private Set<String> getHelpResources(final IToc toc) {
+		final Set<String> helpResources = new HashSet<String>();
+		final IUAElement[] children = toc.getChildren();
+		for (final IUAElement e : children) {
+			addHelpResources(helpResources, e);
+		}
+		return helpResources;
+	}
+
+	private void addHelpResources(final Set<String> helpResources, final IUAElement e) {
+		if (e instanceof ITopic) {
+			final ITopic c = (ITopic) e;
+			String href = c.getHref();
+			if (href != null) {
+				int hashPos = href.indexOf('#');
+				if (hashPos > 0)
+					href = href.substring(0, hashPos);
+				helpResources.add(href);
+			}
+			for (final IUAElement e1 : c.getChildren()) {
+				addHelpResources(helpResources, e1);
+			}
+		}
+	}
+
 }