Merge branch 'main' of https://github01.hclpnp.com/Modeling/rtistic-p…

…ub-doc

docs-sources/draft-documentation.md

@@ -0,0 +1,64 @@
+Draft documentation, not yet included in the product
+====================================================
+**The Art Language - State Machine - Transition - Frequent Transition**
+
+#### Frequent Transition
+Sometimes you may have a state where one or a few outgoing transitions can be expected to execute much more frequently than others. You can then set a `frequent` [property](#property) on the transition trigger that you expect will trigger the transition frequently. The Art compiler uses this information to optimize generated C++ code so that such transition triggers are evaluated before other triggers that are expected to trigger the transition less frequently. 
+
+``` art
+interrupted: Working -> Stopped on [[rt::properties(
+            frequent=true
+        )]] external.interrupt
+        `
+            // Interrupted while working...
+        `;
+```
+
+!!! note 
+    The frequent property relies on optimization features in the C++ compiler that may or may not be available depending on which target compiler that is used. Only use frequent transitions if profiling has shown that you have a need to do this optimization.
+
+========================================================
+**The Art Language - Template**
+
+## Template
+A template is a type that is parameterized by means of template parameters to make it more generic. When a template is used (a.k.a. instantiated), actual template parameters must be provided that match the formal template parameters defined in the template. Both [capsules](#capsule) and [classes](#class-with-state-machine) can have template parameters. Just like in C++ two kinds of template parameters are supported:
+
+* **Type template parameter**
+
+Replaced with a type when the template is instantiated.
+
+* **Non-type template parameters**
+
+Replaced with a non-type, for example a constant value, when the template is instantiated.
+
+Template parameters may have defaults that will be used if a matching actual template parameter is not provided when instantiating the template.
+
+Below is an example of a capsule and a class with template parameters, some of which have defaults specified. The keywords `typename` and `class` can both be used for defining a type template parameter. A non-type template parameter is defined by specifying its type as a C++ code snippet.
+
+``` art
+template <typename T = `int`, `int` p1 = `5`>
+capsule TemplateCapsule { 
+    [[rt::decl]]
+    `
+        void func(T arg1) {
+            // impl
+        }
+    `
+
+    service port mp : MachineEvents[`p1`];
+
+    statemachine {
+        state State;
+        initial -> State;
+    };
+};
+
+template <typename T, class U, `int` p1>
+class TemplateClass : `Base<T,U,p1>` {
+    statemachine {
+        state State;
+        initial -> State;
+    };
+};
+```
+Template parameters can only be used from C++ code snippets, and above you see some examples of how they can be used. It's not possible to instantiate a template in Art itself. For example, even if class `Base` above was defined as an Art class, a C++ code snippet has to be used since it has template parameters.

docs-sources/installing.md

@@ -34,7 +34,7 @@ Another way to install {$product.name$} is to use a .vsix file. This can be usef
 
 3) In the file dialog that appears, select the .vsix file to install.
 
-If the installation completes successfully you should see the following message (the "Reload Now" button will only show if you already had another version of {$product.name$} installed):
+If the installation completes successfully you should see the following message:
 
 ![](images/vsix_installation_completed.png)
 
@@ -63,7 +63,7 @@ You can also see the version and the exact date of the installed {$product.name$
 ![](images/extension_changelog.png)
 
 ### Portable Mode Installation
-You can install multiple versions of {$product.name$} by using the portable mode of Visual Studio Code. See [Portable Mode](https://code.visualstudio.com/docs/editor/portable) for how to install Visual Studio code in portable mode, which will allow you to install a version of {$product.name$} that won't affect other Visual Studio Code installations on the machine. Portable mode also allows to move or copy an installation from one machine to another, which makes it useful in scenarios where installs should be centralized in an organization.
+You can install multiple versions of {$product.name$} by using the portable mode of Visual Studio Code. See [Portable Mode](https://code.visualstudio.com/docs/editor/portable) for how to install Visual Studio Code in portable mode, which will allow you to install a version of {$product.name$} that won't affect other Visual Studio Code installations on the machine. Portable mode also allows to move or copy an installation from one machine to another, which makes it useful in scenarios where installs should be centralized in an organization.
 
 ### Post-Installation Configuration
 After a successful installation you need to perform a few configuration steps before you can start to use {$product.name$}.
@@ -105,7 +105,7 @@ To uninstall {$product.name$} follow these steps:
 
 ![](images/extensions_in_sidebar.png)
 
-1) Find the {$product.name$} extension in the "Installed" section and invoke the "Uninstall" command (in Visual Studio code the command is available in the context menu, while in Theia it shows up as a button to click).
+1) Find the {$product.name$} extension in the "Installed" section and invoke the "Uninstall" command (in Visual Studio Code the command is available in the context menu, while in Theia it shows up as a button to click).
 
 ![](images/uninstall.png)
 

docs-sources/overview.md

@@ -2,7 +2,7 @@
 
 It runs as an extension of Visual Studio Code or Eclipse Theia. Follow the [installation instructions](../installing) for installing it.
 
-{$product.name$} supports the [Art language](../art-lang) which is an extension of the C++ language. It provides high-level concepts useful when designing stateful, event-driven realtime applications, such as capsules, state machines and protocols. It is a textual language, but also provides a graphical notation that includes class, state and structure diagrams.
+{$product.name$} supports the [Art language](../art-lang) which extends the C++ language with high-level concepts useful when designing stateful, event-driven realtime applications, such as capsules, state machines and protocols. It is a textual language, but also provides a graphical notation that includes class, state and structure diagrams.
 
 {$product.name$} translates Art files into efficient C++ code which can be compiled on any target system. The generated code makes use of the [Target RunTime System](../target-rts) which is a C++ library that implements the concepts of the Art language.
 
@@ -13,8 +13,8 @@ The Art language as implemented in {$product.name$} builds on a foundation with
 
 In 2000 ObjectTime was acquired by Rational Software and ObjecTime Developer was merged with Rational Rose, a UML modeling tool. The result was Rational Rose RealTime (Rose RT). At the same time many of the ROOM language concepts made its way into the, by then, new modeling language called UML-RealTime.
 
-In 2003 Rational Software was acquired by IBM which at the time was investing heavily in the Eclipse platform. As a result work started to create an Eclipse-based tool as the successor of Rose RT. This new product got the name Rational Software Architect RealTime Edition ([RSARTE](https://rsarte.hcldoc.com/help/topic/com.ibm.xtools.rsarte.webdoc/users-guide/overview.html?cp=26_0)) and was first released in 2007.
+In 2003 Rational Software was acquired by IBM which at the time was investing heavily in the Eclipse platform. As a result work started to create an Eclipse-based tool as the successor of Rose RT. This new product got the name Rational Software Architect RealTime Edition (RSARTE) and was first released in 2007.
 
-In 2016 HCL entered a partnership with IBM, which led to a rebranded version of RSARTE called HCL RTist. Later both RSARTE and RTist was renamed to DevOps Model RealTime.
+In 2016 HCL entered a partnership with IBM, which led to a rebranded version of RSARTE called HCL RTist. A few years later both RSARTE and RTist were renamed to [DevOps Model RealTime](https://model-realtime.hcldoc.com/help/topic/com.ibm.xtools.rsarte.webdoc/users-guide/overview.html).
 
 Work on {$product.name$} began in 2020 with the aim of supporting other IDEs than Eclipse. As part of this effort a textual language syntax, Art, was developed. Hence it's fair to describe the Art language as a new syntax for concepts that have a rather old history and have already been used in the industry for more than 30 years. It should also be mentioned that the [Target RunTime System](../target-rts) used in {$product.name$} is the same as is used in Model RealTime. In fact, the implementation of this C++ library started with ObjectTime Developer and has since then been gradually extended and modernized.

docs-sources/targetrts-api/_r_t_injector_8h_source.html

@@ -124,21 +124,21 @@
 <div class="line"><a id="l00075" name="l00075"></a><span class="lineno">   75</span> </div>
 <div class="line"><a id="l00081" name="l00081"></a><span class="lineno"><a class="line" href="class_r_t_injector.html#aaa9b5ed1aada6e6fa00574b839cde6fe">   81</a></span>    std::function&lt;<a class="code hl_class" href="class_r_t_actor.html">RTActor</a>* (<a class="code hl_class" href="class_r_t_controller.html">RTController</a> *, <a class="code hl_class" href="class_r_t_actor_ref.html">RTActorRef</a> *, int)&gt; <a class="code hl_function" href="class_r_t_injector.html#aaa9b5ed1aada6e6fa00574b839cde6fe">getCreateFunction</a>(<span class="keyword">const</span> std::string&amp; <span class="keywordtype">id</span>);</div>
 <div class="line"><a id="l00082" name="l00082"></a><span class="lineno">   82</span> </div>
-<div class="line"><a id="l00091" name="l00091"></a><span class="lineno"><a class="line" href="class_r_t_injector.html#a23f2c45bc802443918532174bc4708b0">   91</a></span>    <a class="code hl_class" href="class_r_t_actor.html">RTActor</a>* <a class="code hl_function" href="class_r_t_injector.html#a23f2c45bc802443918532174bc4708b0">create</a>(<a class="code hl_class" href="class_r_t_controller.html">RTController</a> *rts, <a class="code hl_class" href="class_r_t_actor_ref.html">RTActorRef</a> *ref, <span class="keywordtype">int</span> index);</div>
-<div class="line"><a id="l00092" name="l00092"></a><span class="lineno">   92</span> </div>
-<div class="line"><a id="l00093" name="l00093"></a><span class="lineno">   93</span>    <a class="code hl_class" href="class_r_t_injector.html">RTInjector</a>(<a class="code hl_class" href="class_r_t_injector.html">RTInjector</a> <span class="keyword">const</span>&amp;) = <span class="keyword">delete</span>;</div>
-<div class="line"><a id="l00094" name="l00094"></a><span class="lineno">   94</span>    <span class="keywordtype">void</span> operator=(<a class="code hl_class" href="class_r_t_injector.html">RTInjector</a> <span class="keyword">const</span>&amp;) = <span class="keyword">delete</span>;</div>
-<div class="line"><a id="l00095" name="l00095"></a><span class="lineno">   95</span> </div>
-<div class="line"><a id="l00096" name="l00096"></a><span class="lineno">   96</span><span class="keyword">private</span>:</div>
-<div class="line"><a id="l00097" name="l00097"></a><span class="lineno">   97</span> </div>
-<div class="line"><a id="l00098" name="l00098"></a><span class="lineno">   98</span>    std::unordered_map&lt;std::string, std::function&lt;<a class="code hl_class" href="class_r_t_actor.html">RTActor</a>* (<a class="code hl_class" href="class_r_t_controller.html">RTController</a> *, <a class="code hl_class" href="class_r_t_actor_ref.html">RTActorRef</a> *, int)&gt; &gt; createFuncRegistry;</div>
-<div class="line"><a id="l00099" name="l00099"></a><span class="lineno">   99</span><span class="preprocessor">#if USE_THREADS</span></div>
-<div class="line"><a id="l00100" name="l00100"></a><span class="lineno">  100</span>    RTMutex* _mutex;</div>
-<div class="line"><a id="l00101" name="l00101"></a><span class="lineno">  101</span><span class="preprocessor">#endif</span></div>
-<div class="line"><a id="l00102" name="l00102"></a><span class="lineno">  102</span> </div>
-<div class="line"><a id="l00103" name="l00103"></a><span class="lineno">  103</span>};</div>
-<div class="line"><a id="l00104" name="l00104"></a><span class="lineno">  104</span> </div>
-<div class="line"><a id="l00105" name="l00105"></a><span class="lineno">  105</span><span class="preprocessor">#endif </span><span class="comment">// __RTInjector_h__</span></div>
+<div class="line"><a id="l00092" name="l00092"></a><span class="lineno"><a class="line" href="class_r_t_injector.html#a23f2c45bc802443918532174bc4708b0">   92</a></span>    <a class="code hl_class" href="class_r_t_actor.html">RTActor</a>* <a class="code hl_function" href="class_r_t_injector.html#a23f2c45bc802443918532174bc4708b0">create</a>(<a class="code hl_class" href="class_r_t_controller.html">RTController</a> *rts, <a class="code hl_class" href="class_r_t_actor_ref.html">RTActorRef</a> *ref, <span class="keywordtype">int</span> index);</div>
+<div class="line"><a id="l00093" name="l00093"></a><span class="lineno">   93</span> </div>
+<div class="line"><a id="l00094" name="l00094"></a><span class="lineno">   94</span>    <a class="code hl_class" href="class_r_t_injector.html">RTInjector</a>(<a class="code hl_class" href="class_r_t_injector.html">RTInjector</a> <span class="keyword">const</span>&amp;) = <span class="keyword">delete</span>;</div>
+<div class="line"><a id="l00095" name="l00095"></a><span class="lineno">   95</span>    <span class="keywordtype">void</span> operator=(<a class="code hl_class" href="class_r_t_injector.html">RTInjector</a> <span class="keyword">const</span>&amp;) = <span class="keyword">delete</span>;</div>
+<div class="line"><a id="l00096" name="l00096"></a><span class="lineno">   96</span> </div>
+<div class="line"><a id="l00097" name="l00097"></a><span class="lineno">   97</span><span class="keyword">private</span>:</div>
+<div class="line"><a id="l00098" name="l00098"></a><span class="lineno">   98</span> </div>
+<div class="line"><a id="l00099" name="l00099"></a><span class="lineno">   99</span>    std::unordered_map&lt;std::string, std::function&lt;<a class="code hl_class" href="class_r_t_actor.html">RTActor</a>* (<a class="code hl_class" href="class_r_t_controller.html">RTController</a> *, <a class="code hl_class" href="class_r_t_actor_ref.html">RTActorRef</a> *, int)&gt; &gt; createFuncRegistry;</div>
+<div class="line"><a id="l00100" name="l00100"></a><span class="lineno">  100</span><span class="preprocessor">#if USE_THREADS</span></div>
+<div class="line"><a id="l00101" name="l00101"></a><span class="lineno">  101</span>    RTMutex* _mutex;</div>
+<div class="line"><a id="l00102" name="l00102"></a><span class="lineno">  102</span><span class="preprocessor">#endif</span></div>
+<div class="line"><a id="l00103" name="l00103"></a><span class="lineno">  103</span> </div>
+<div class="line"><a id="l00104" name="l00104"></a><span class="lineno">  104</span>};</div>
+<div class="line"><a id="l00105" name="l00105"></a><span class="lineno">  105</span> </div>
+<div class="line"><a id="l00106" name="l00106"></a><span class="lineno">  106</span><span class="preprocessor">#endif </span><span class="comment">// __RTInjector_h__</span></div>
 <div class="ttc" id="aclass_r_t_actor_html"><div class="ttname"><a href="class_r_t_actor.html">RTActor</a></div><div class="ttdoc">An instance of this class represents a capsule instance.</div><div class="ttdef"><b>Definition:</b> RTActor.h:44</div></div>
 <div class="ttc" id="aclass_r_t_actor_ref_html"><div class="ttname"><a href="class_r_t_actor_ref.html">RTActorRef</a></div><div class="ttdoc">Represents a capsule part.</div><div class="ttdef"><b>Definition:</b> RTActorRef.h:39</div></div>
 <div class="ttc" id="aclass_r_t_controller_html"><div class="ttname"><a href="class_r_t_controller.html">RTController</a></div><div class="ttdoc">A controller manages a group of capsule instances that all run in the same physical thread (i....</div><div class="ttdef"><b>Definition:</b> RTController.h:54</div></div>

docs-sources/targetrts-api/class_r_t_injector.html

@@ -149,15 +149,15 @@ <h2 class="memtitle"><span class="permalink"><a href="#a23f2c45bc802443918532174
 </div><div class="memdoc">
 
 <p>Create a capsule instance. </p>
-<p>If a create function has been registered for the specified capsule part it will be used. Otherwise, the default create function of the capsule will be used. </p><dl class="params"><dt>Parameters</dt><dd>
+<p>If a create function has been registered for the specified capsule part it will be used for creating the capsule instance. Otherwise nullptr will be returned, to allow the capsule instance to be created as default (if possible). </p><dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">rts</td><td>Default controller thread to run the created capsule instance (a registered create function may override this) </td></tr>
     <tr><td class="paramname">ref</td><td>Capsule part to host the created capsule instance </td></tr>
     <tr><td class="paramname">index</td><td>Index where to insert the created capsule instance in the capsule part </td></tr>
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>Capsule instance, or nullptr in case a capsule instance couldn't be created </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>Created capsule instance, or nullptr in case no capsule instance was created </dd></dl>
 
 </div>
 </div>

theme_overrides/home.html

@@ -160,6 +160,7 @@ <h2>
     <div class="md-footer-meta md-typeset">
         <div class="md-footer-meta__inner md-grid">
             <!-- Copyright and theme information -->
+            <div><p>If you encounter any issues while using Code RealTime or have questions or suggestions about its features, feel free to contact us at <a href="mailto:[email protected]">[email protected]</a>. We're here to assist you!</p></div>
             <div class="md-footer-copyright">
                 <a href=" https://www.hcltechsw.com/ " title="MkDocs">{{ config.copyright }}</a>
                 <br>Made with