add additional hints for Ad to Petri tasks

src/Modelling/ActivityDiagram/Auxiliary/Util.hs

@@ -1,4 +1,8 @@
+{-# LANGUAGE ApplicativeDo #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE QuasiQuotes #-}
 module Modelling.ActivityDiagram.Auxiliary.Util (
+  auxiliaryPlacesAdvice,
   weightedShuffle
   ) where
 
@@ -7,8 +11,17 @@ import Control.Monad.Random (
   fromList,
   )
 import Data.List (delete)
+import Data.String.Interpolate          (iii)
+import Control.Monad.Output (
+  LangM,
+  OutputMonad,
+  english,
+  german,
+  paragraph,
+  translate,
+  )
 
-{-
+{-|
   Shuffle a list of elements from type a based on given weights of type w,
   where higher weight indicates a bigger probability of the element occurring
   at a lower index of the list. The total weight of all elements must not be zero.
@@ -23,3 +36,58 @@ weightedShuffle xs = do
   a <- fromList rs
   ys <- weightedShuffle (delete a xs)
   return (fst a : ys)
+
+auxiliaryPlacesAdvice :: OutputMonad m => Bool -> LangM m
+auxiliaryPlacesAdvice withFinalTransitionAdvice = do
+  paragraph $ translate $ do
+    english [iii|
+      Please note:
+      On slides 217 and 219 it is still said that decision and merge nodes
+      are realised as "Hilfsstellen" (support/auxiliary places)
+      during the translation.
+      It is not actually intended this way.
+      The Stellen/places introduced for decision and merge nodes serve
+      a special purpose and are not "just" introduced to satisfy
+      the constraint mentioned in the first point on slide 218.
+      |]
+    german [iii|
+      Bitte beachten Sie:
+      Auf den Folien 217 und 219 wird noch immer gesagt,
+      dass Verzweigung- und Verbinundungsknoten bei der Übersetzung als
+      Hilfsstellen realisiert werden.
+      Das ist jedoch nicht so beabsichtigt.
+      Die für Verzweigungs- und Verbindungsknoten eingeführten Stellen
+      dienen einem besonderen Zweck und werden nicht "nur" eingeführt,
+      um die auf Folie 218 im ersten Punkt erwähnte Bedingung zu erfüllen.
+      |]
+  paragraph $ translate $ do
+    english $ [iii|
+      Hint on the translation to a Petri net:
+      For final nodes no additional places are introduced.
+      They are realised in a way that a token is consumed,
+      i.e. disappears from the net at that position.
+      |]
+      `appendExtendedAdvice`
+      [iii|
+      If an additional transition is required to realise this behavior
+      at a position in the diagram where there is a final node,
+      this transition does not count as support/auxiliary node.
+      |]
+    german $ [iii|
+      Hinweis zur Übersetzung in ein Petrinetz:
+      Für Endknoten  werden keine zusätzlichen Stellen eingeführt.
+      Sie werden so realisiert, dass ein Token verbraucht wird,
+      also an dieser Stelle aus dem Netz verschwindet.
+      |]
+      `appendExtendedAdvice`
+      [iii|
+      Falls eine zusätzliche Transition erforderlich ist,
+      um dieses Verhalten an einer Position im Diagramm zu realisieren,
+      an der sich ein Endknoten befindet,
+      zählt diese Transition nicht als Hilfsstelle.
+      |]
+  pure ()
+  where
+    appendExtendedAdvice x y
+      | withFinalTransitionAdvice = x ++ ' ' : y
+      | otherwise = x

src/Modelling/ActivityDiagram/FindSupportST.hs

@@ -35,6 +35,7 @@ import qualified Data.Map as M (
 
 import Capabilities.Alloy               (MonadAlloy, getInstances)
 import Capabilities.PlantUml            (MonadPlantUml)
+import Modelling.ActivityDiagram.Auxiliary.Util (auxiliaryPlacesAdvice)
 import Modelling.ActivityDiagram.Datatype (
   AdConnection (..),
   AdNode (..),
@@ -222,6 +223,7 @@ an Knoten (Stellen und Transitionen), die Anzahl der Hilfsstellen und die Anzahl
       english [i|In this example, the resulting net contains 10 nodes in total, of which 2 are auxiliary places and 3 are auxiliary transitions.|]
       german [i|In diesem Beispiel etwa enthält das entstehende Netz insgesamt 10 Knoten, davon 2 Hilfsstellen und 3 Hilfstransitionen.|]
     pure ()
+  auxiliaryPlacesAdvice True
   pure ()
 
 findSupportSTInitial :: FindSupportSTSolution

src/Modelling/ActivityDiagram/MatchPetri.hs

@@ -32,6 +32,7 @@ import Capabilities.Cache               (MonadCache)
 import Capabilities.Diagrams            (MonadDiagrams)
 import Capabilities.Graphviz            (MonadGraphviz)
 import Capabilities.PlantUml            (MonadPlantUml)
+import Modelling.ActivityDiagram.Auxiliary.Util (auxiliaryPlacesAdvice)
 import Modelling.ActivityDiagram.Datatype (
   UMLActivityDiagram(..),
   AdNode (..),
@@ -311,6 +312,7 @@ the Petri net nodes 5 and 7 correspond to decision nodes and the Petri net nodes
       german [i|In diesem Beispiel sind etwa die Aktionsknoten "A" und "B" den Petrinetzknoten 1 und 2 zugeordnet,
 die Petrinetzknoten 5 und 7 entsprechen Verzweigungsknoten und die Petrinetzknoten 13, 14 und 15 sind Hilfsstellen oder -transitionen.|]
     pure ()
+  auxiliaryPlacesAdvice True
   pure ()
 
 matchPetriInitial :: MatchPetriSolution

src/Modelling/ActivityDiagram/SelectPetri.hs

@@ -33,6 +33,10 @@ import qualified Modelling.ActivityDiagram.Datatype as Ad (AdNode(label))
 import qualified Modelling.ActivityDiagram.PetriNet as PK (PetriKey (label))
 
 import Modelling.ActivityDiagram.Alloy (modulePetriNet)
+import Modelling.ActivityDiagram.Auxiliary.Util (
+  auxiliaryPlacesAdvice,
+  weightedShuffle,
+  )
 import Modelling.ActivityDiagram.Config (
   AdConfig (..),
   adConfigToAlloy,
@@ -56,7 +60,6 @@ import Modelling.ActivityDiagram.PlantUMLConverter (
   drawAdToFile,
   )
 import Modelling.ActivityDiagram.Shuffle (shuffleAdNames, shufflePetri)
-import Modelling.ActivityDiagram.Auxiliary.Util (weightedShuffle)
 
 import Modelling.Auxiliary.Common (
   TaskGenerationException (NoInstanceAvailable),
@@ -348,6 +351,7 @@ Bitte geben Sie Ihre Antwort als Zahl an, welche das passende Petrinetz repräse
       english [i|would indicate that Petri net 2 is the matching Petri net.|]
       german  [i|bedeuten, dass Petrinetz 2 das passende Petrinetz ist.|]
     pure ()
+  auxiliaryPlacesAdvice False
   pure ()
 
 selectPetriSolutionToMap