Bug 550902: [Doc] The papyrus embedded documentation must be the same

than the documentation on the wiki

- Add the mars works documentation:
  - Modeling Assistants
  - Diagram synchronization
  - Diagram expansion

Change-Id: I2021e7745e2b3ec2769e942feca94f553ff41e8a
Signed-off-by: Nicolas FAUVERGUE <nicolasfauvergue@gmail.com>

8 files changed, 224 insertions, 0 deletions

diff --git a/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/plugin.xml b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/plugin.xml
index 3e9cd702500..0ba9b8d1b94 100644
--- a/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/plugin.xml
+++ b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/plugin.xml
@@ -51,5 +51,13 @@
             file="target/generated-eclipse-help/keyBindingsDefinition-toc.xml"
             primary="false">
       </toc>
+      <toc
+            file="target/generated-eclipse-help/diagramExpansion-main-toc.xml"
+            primary="false">
+      </toc>
+      <toc
+            file="target/generated-eclipse-help/diagramExpansion-toc.xml"
+            primary="false">
+      </toc>
    </extension>
 </plugin>
diff --git a/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion-main-toc.xml b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion-main-toc.xml
new file mode 100644
index 00000000000..c903a303411
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion-main-toc.xml
@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<toc label="Diagram Expansion" link_to="../org.eclipse.papyrus.infra.doc/toc.xml#PapyrusDocDev">
+    <topic href="target/generated-eclipse-help/diagramExpansion.html" label="Diagram Expansion">
+        <link toc="target/generated-eclipse-help/diagramExpansion-toc.xml"/>
+        <anchor id="PapyrusDiagramExpansion"/>
+  	</topic>
+</toc>
diff --git a/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion.mediawiki b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion.mediawiki
new file mode 100644
index 00000000000..036350ccb3a
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.infra.gmfdiag.common.doc/resource/diagramExpansion.mediawiki
@@ -0,0 +1,39 @@
+=Table of Contents=
+==Requirements==
+* Add Graphical Elements (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_010): 
+The system shall be able to add new graphical elements in new diagrams or existing diagrams
+* Add Graphical Compartments (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_011): 
+The developper can add new compartments from a existed graphical element.
+* Add new nodes (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_012): 
+A developper can add new nodes in the diagram that no exist in the existed diagram or  add element by reusing existed shape.
+* Add new child label  (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_013): 
+A developper can add new child labels ( element that can be contained in a list compartment) in the diagram that no exist in the existed diagram or  add element by reusing existed child label.
+* Add new border item (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_014): 
+A developper can add new border items ( element that can be installed around the  shape) in the diagram that no exist in the existed diagram or  add element by reusing existed border item.
+* Add new links  (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_015): 
+A developper can add new links in the diagram that no exist in the existed diagram or  add element by reuse existed links.
+* Reuse representations from diagram (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_016): 
+It must be able to reuse rperesentations from existed diagrams
+* Drop of new Elements (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_020): 
+New Elements can be dropped from the model explorer.
+* Assistant (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_030): 
+The new element must be created by using assistant mechanism
+* Creation from the palette (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_040): 
+Elements can be created fom the palette
+* Non impact on parent diagrams (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_050): 
+the inheridted diagram must not impact parent diagram by addin the new compartments.
+* ExpransionModel (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_060): 
+The expansion of diagram has to be a model and be interpreted
+* The model has to be well-built (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_061): 
+When the model is done, the ystem has to ensure that it can be correctly interpreted.
+* Expanded diagrams viewed with original editor (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_070): 
+The original diagram must be view in original diagram, exteernal element must have a predefined shape.
+It cannot be implemented for the version Mars
+* CSS driven (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_080): 
+The added element must be driven by CSS
+* View point relation (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_090): 
+The new specialization editor must benefit of all specializations.
+* Loading at runtime (id=org.eclipse.papyrus.infra.gmfdiag.expansion.Req_0100): 
+An expansion model must be able to load during runtime, not only with extension point.
+It allow to be tested by Junit Tests.
+
diff --git a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/plugin.xml b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/plugin.xml
index a90343395cd..62be3e750df 100644
--- a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/plugin.xml
+++ b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/plugin.xml
@@ -35,6 +35,22 @@
             file="target/generated-eclipse-help/stereotype-property-reference-edge-toc.xml"
             primary="false">
       </toc>
+      <toc
+            file="target/generated-eclipse-help/modelingAssistants-main-toc.xml"
+            primary="false">
+      </toc>
+      <toc
+            file="target/generated-eclipse-help/modelingAssistants-toc.xml"
+            primary="false">
+      </toc>
+      <toc
+            file="target/generated-eclipse-help/diagramSynchronization-main-toc.xml"
+            primary="false">
+      </toc>
+      <toc
+            file="target/generated-eclipse-help/diagramSynchronization-toc.xml"
+            primary="false">
+      </toc>
    </extension>
 
 </plugin>
diff --git a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization-main-toc.xml b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization-main-toc.xml
new file mode 100644
index 00000000000..cacf8652f7d
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization-main-toc.xml
@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<toc label="Diagram synchronization" link_to="../org.eclipse.papyrus.infra.doc/toc.xml#PapyrusTipsAndTricks">
+   <topic href="target/generated-eclipse-help/diagramSynchronization.html" label="Diagram synchronization support">
+      <link toc="target/generated-eclipse-help/diagramSynchronization-toc.xml"/>
+      <anchor id="UMLDiagramSynchronization"/>
+   </topic>	
+</toc>
diff --git a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization.mediawiki b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization.mediawiki
new file mode 100644
index 00000000000..c1845ba0196
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/diagramSynchronization.mediawiki
@@ -0,0 +1,103 @@
+This page describes the work that will be performed on Papyrus Mars to support synchronization.
+There are at least 2 kind of synchronization to implement in Papyrus: 
+* diagram content synchronized on semantic model content, called canonical mode
+* diagram content synchronized on another diagram. 
+
+= Canonical mode, a.k.a. diagram synchronized on semantic model =
+
+Bugzilla reference:
+
+* bug 433206 - the model/view synchronization enhancement request
+* bug 461629 - problematic interaction between canonical view creation, non-transactional diagram refresh enabling/disabling canonical edit policy by CSS, and undo/redo of semantic model element creation
+
+This mode has already been partially implemented in Papyrus Luna, but never deployed as there were not as many tests as expected to be sure the feature would not slow down or even corrupt the tool. The work on canonical model could be based on that first implementation. see org.eclipse.papyrus\plugins\uml\diagram\org.eclipse.papyrus.uml.diagram.synchronizeview for that initial implementation
+There is also an implementation of this framework in the tables, it could be interesting to see how it is implemented and how the 2 synchronizations mechanism could rely on the same framework.
+
+Here are some requirements, to be developed more extensively (taken from model in plugin org.eclipse.papyrus\plugins\uml\diagram\org.eclipse.papyrus.uml.diagram.synchronizeview)
+* The synchronization should be local to an element or for the whole diagram
+* The synchronization mechanism should alter the performances only in a reasonable way
+* The synchronization should take into account all features of Papyrus: drag'n'drop, copy and paste, 
+* The synchonization should be linked to CSS framework (reuse canonical style from GMF ?)
+* The synchronization should share its framework with the table framework
+
+Automated tests for view synchronization are added to the in-progress Papyrus Diagram Tests Generation Framework:
+* [https://git.eclipse.org/r/#/c/38587/ Gerrit change]
+
+== Demo Videos ==
+
+* Tech preview of canonical list and shape compartments: [http://youtu.be/NhdDWIlpXao YouTube]
+* Interaction of canonical edit policy with undo/redo: [http://youtu.be/qbLF_4l-SF4 YouTube]
+* Properties view support and drag-and-drop interaction: [http://youtu.be/aOcCthCuDBI YouTube]
+* Demonstration of a new CSS {{code|canonical}} attribute: [http://youtu.be/cfoQQKPlsxw YouTube]
+* A problem ({{bug|461629}}) in the interaction between canonical creation of views, non-transactional refresh triggered by CSS to activate/deactivate canonical synchronization, and undo/redo of edit commands: [http://youtu.be/bv2Gozopha0 YouTube]
+** And that problem, fixed: [http://youtu.be/XNyl6hlcs08 YouTube]
+* Canonical composite structure diagrams (incl. connector-end part-with-port): [http://youtu.be/uo2jpPd-n2s YouTube]
+* Improvements in the layout of canonical diagrams (esp. behaviours): [https://youtu.be/ydTiYbcJQss YouTube]
+* First phase of automated test generation: [http://youtu.be/ZIZPceUdvE8 YouTube]
+
+= Diagram synchronized on another diagram =
+
+Bugzilla reference:
+
+* bug 465416 - the diagram-to-diagram feature request
+
+== Requirements ==
+
+The requirements for diagram-to-diagram synchronization are primarily driven by UML-RT use cases such as state machine inheritance:
+
+* '''R1''' the sync framework shall support automatic synchronization of model semantics. For example, a state machine in a subclass that redefines a state machine in a superclass must always define regions, vertices, and transitions corresponding to and redefining the regions, vertices, and transitions of the superclass state machine
+* '''R2''' the sync framework shall support automatic synchronization of the layout of diagrams. For example, a state machine diagram in a subclass that redefines a state machine in a superclass initially presents the same layout as the superclass state machine and changes in the superclass state machine diagram layout are reflected in the subclass
+** '''R2.1''' synchronization of diagram layout shall be optional.  Initially, a diagram is synchronized with the diagram that it redefines, but as needed to effect a sensible layout of the redefining diagram, this synchronization may be broken by the user.  The semantics remain synchronized, and some graphical views may remain synchronized, but the user may freely rearrange other views as required by the redefining context
+
+== Demo Videos ==
+
+* Synchronization of redefining state machines in UML-RT Capsule inheritance: [https://youtu.be/BKYe8b84ywM YouTube]
+* Overriding synchronization by tweaking the layout of a synchronized diagram: [http://youtu.be/TwneFmoFmIw YouTube]
+
+== Prototype ==
+
+An initial prototype is posted to Gerrit:  [https://git.eclipse.org/r/#/c/36747/ Change 36747].  This comprises
+
+* a generic framework for synchronization of source objects to target objects, including
+** a model of source/target synchronization pairs
+** collection of synchronizations on the same source object
+** orchestration of synchronization updates based on an abstraction of change messages
+* an implementation of the framework in the Papyrus Diagram Common plug-in for common scenarios such as
+** synchronizing the children of a node in a diagram
+** synchronizing the location and size of a node in a diagram
+* an implementation of the framework for synchronization of the size and position of UML-RT Capsules in a Capsule Diagram of their package, re-using the common diagram sync pieces
+
+Basic use cases in the prototype work like so:
+
+# Create two Capsule Diagrams in a package
+# In each, right-click on the diagram surface and invoke the '''Synchronize''' context menu action
+# On one of the diagrams, right-click on the diagram surface and invoke the '''Setup as sync master''' context menu action
+#* ''This particular implementation denotes one diagram as the master, which pushes its changes to all others, a 1-to-N sync. The framework seems to allow also for N-M sync, in which all participants keep each other in sync''
+# In the master diagram, create a Capsule.
+#* ''See it appear in the same location and with the same size in the other diagram.''
+# In the master diagram, create another Capsule.
+#* ''See it also appear in the other diagram.''
+# In the master diagram, create an association between the two capsules.
+#* ''Nothing happens in the other diagram: no synchronization is registered for edge views, only child nodes that represent capsules.''
+# In the master diagram, move one of the capsules and resize it.
+#* ''See the same change for that capsule in the other diagram.''
+# Undo.
+#* ''See the same change undone in both diagrams. Synchronization processes changes in the diagrams in a transaction pre-commit listener and appends consequent updates to the transaction as trigger commands.''
+# In the other diagram (not master), move a capsule.
+#* ''See that the corresponding shape in the master diagram is not moved, because synchronization is one-way from the master to the others.''
+
+== To-do tasks ==
+
+* Custom notation styles for synchronization, capturing:
+** the <tt>SyncBucket</tt> in which to register the view
+** 'master' and 'slave' roles in the synchronization, or just all-party synchronization
+* Expression of the above details might benefit from a model of synchronizations:
+** Pluggable registry of synchronization models
+** Synchronization styles can reference <tt>SyncBucket</tt>s in these models
+** Buckets are created from the models:
+*** Either instantiating implementations of the API classes as currently, or
+*** (more elaborate) describing synchronization semantics in the model, so that generic bucket implementations can be used that interpret the synchronization specification
+* Currently, the framework supports synchronization of multiple diagram visualizations of the same model element. For UML-RT, it is necessary to support also synchronization of diagram visualizations of two related model elements (for example, a capsule showing inherited ports in the same location on its border as where those ports are on the general capsule in the same or different diagram)
+
+= Several instances of the same diagram =
+* Having several instances of the same diagram (Moka example)
diff --git a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants-main-toc.xml b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants-main-toc.xml
new file mode 100644
index 00000000000..2837ec3b892
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants-main-toc.xml
@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<toc label="Modeling Assistants" link_to="../org.eclipse.papyrus.infra.doc/toc.xml#PapyrusTipsAndTricks">
+   <topic href="target/generated-eclipse-help/modelingAssistants.html" label="Modeling Assistants Customization for UML Profiles">
+      <link toc="target/generated-eclipse-help/modelingAssistants-toc.xml"/>
+      <anchor id="UMLModelingAssistants"/>
+   </topic>	
+</toc>
diff --git a/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants.mediawiki b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants.mediawiki
new file mode 100644
index 00000000000..5096e750265
--- /dev/null
+++ b/plugins/doc/org.eclipse.papyrus.uml.diagram.common.doc/resource/modelingAssistants.mediawiki
@@ -0,0 +1,37 @@
+This page presents the requirements and design notes for Modeling Assistants in the diagram editors, customizable for DSMLs based on UML Profiles.
+
+=Requirements=
+
+The requirements for Modeling Assistants in the Papyrus diagram editors, addressable in the Mars release, are
+
+* '''R1''' assistants provided by a diagram shall be described by a model
+* '''R2''' the assistants model shall be initially generated ("seeded") from a UML Profile
+* (omitted) bug 459510 '''R3''' the assistants model should, as much as possible, be unified/aligned with the models for diagram palette customization and Model Explorer "new child" menu customization inasmuch as all three of these mechanisms are, in general terms, different manifestations of tools for creating new model elements
+** '''R3.1''' the modeling assistants shall provide the same "new child" menu as the Model Explorer in the context of diagrams
+*** '''R3.1.1''' which may be further filtered by restrictions of the visualization
+* (omitted) bug 459509 '''R4''' a lightweight customization mechanism may be included that promotes "favourites" in the tool palette as modeling assistants
+* '''R5''' hyperlinks and the hyperlink creation tool shall continue to be presented in the popup bar, in addition to the element creation tools specified by the assistant model
+* '''R6''' the standard UML diagrams provided by Papyrus shall provide assistant models for core editing functionality
+** '''R6.1''' the assistant model for each diagram should be generated from the diagram's GMF Generator model, unless it can better be generated from the diagram's ''Chaos II'' element-types configuration model
+
+=Bugzilla=
+
+The main bugzilla enhancement item tracking progress of this feature is
+
+* bugstrike 451230
+
+Deferred requirements:
+
+* bug 459509
+* bug 459510
+
+=Demonstration Videos=
+
+The progress of development of this feature is recorded in a series of videos, here:
+
+* [http://youtu.be/NxWiMdSu39I First prototype of basic diagram assistants]
+* [http://youtu.be/vRnQ8jOXoWo Defining element types for diagram assistants specific to a UML Profile]
+* [http://youtu.be/i3ERSnjmTgA Generation of diagram assistants model for a UML Profile targeting a particular diagram]
+* [http://youtu.be/tyc0gWU4xj0 Generation of diagram assistants model for a UML Profile not targeting any particular diagram, but UML generally]
+* [http://youtu.be/UR8eSaYXON8 Generating a diagram assistants model for unprofiled UML, targeting a particular diagram's visual types]
+* [http://youtu.be/v-AakQ7TYHQ Context-sensitive activation of diagram assistants for UML Profiles]