Layout pasted elements

docs/Diagrams.md

@@ -4,47 +4,66 @@ As of v2.0 the designer supports having multiple views of your model.
 
 ### Concepts
 
-This is a good time to emphasize the difference between the Model Explorer and diagrams.
+This is a good time to touch on the difference between the Model Explorer and diagrams.
 
-While diagrams are your primary interface into the designer, they can be thought of as
+While diagrams are the interface you'll most often use to edit your model, think of them as a view onto a
+facet of the model. They don't necessarily show all the classes and enums available, and only show associations
+and generalizations if both ends of the connection are present and visible.
 
-You'll always have one view available, your primary diagram, and it will be named the same as your DbContext name. 
-You won't be able to delete that view or change its name (except indirectly, if you change the DbContext name), and it will be the 
+The Model Explorer, on the other hand, always shows all the classes and enums you have created. It's the source
+of truth of your model elements, even though it doesn't show the connections. While technically it's also a view
+of your model, it's a view of the complete set of model classes and enumerations, and removing an element from
+the Model Explorer removes it from the model itself.
+
+You'll always have one diagram view available, your primary diagram, and it will be named the same as your DbContext name. 
+You won't be able to delete that view or change its name (except indirectly, by changing the DbContext name), and it will be the 
 one that appears when you open your model file.
 
-You can add additional views by right-clicking the root node of the Model Explorer and selecting `Add Diagram`. You'll get a default
-name for the diagram (e.g., Diagram1, Diagram2, etc.) but can change that in Visual Studio's Property window. Diagrams appear
+You can add additional diagrams by right-clicking the root node of the Model Explorer and selecting `Add Diagram`. You'll get a default
+name for the new diagram (e.g., Diagram1, Diagram2, etc.) but you can change that in Visual Studio's Property window. Diagrams appear
 empty at first, but you can add new elements to them or choose existing elements from the Model Explorer.
 
-### Adding elements
+The extra diagrams can also be deleted, but the primary diagram cannot. You can delete a diagram using the Model Explorer by 
+right-clicking on the diagram node and selecting `Delete`.
 
-To add a class or enum from the Model Explorer, double click its tree node; the active design window will get that
-element added to it in the top left corner of the diagram. Note that if the element is already on that diagram, it'll be 
-selected and centered on the first click, but it won't be added again.
+### Adding elements
 
-Alternatively, you can drag/drop the class or enum from the Model Explorer to a location on the diagram of your choosing. 
-If it's already on the diagram, you won't be able to drop it.
+To add a existing class or enum from the Model Explorer, double click its tree node; the active diagram will get that
+element added to it in its top left corner. Note that if the element is already present on that diagram, even if hidden, 
+it won't be added again.
 
-Any associations (unidirectional, bidirectional, generalization) to other elements already present will 
-also automatically be drawn. If the other end of that association isn't on the diagram at that moment, though,
-the connector won't appear; you'll only know that the association is there by looking at the Property window
-(to see the base class) or the element node's `Source` and `Target` compartments (for unidirectional and bidirectional associations).
+For more control over placement, you can left-click, hold and drag the class or enum from the Model Explorer, dropping it at a 
+location on the diagram of your choosing. If it's already on the diagram, the cursor will change to indicate that you can't drop it there.
 
-The extra diagrams (but not the primary diagram) can also be deleted. Do that through the Model Explorer by right-clicking on the diagram
-node and selecting `Delete`.
+For classes, any connectors (unidirectional and bidirectional associations, as well as generalizations and comment connectors) to other 
+elements already present on that particular diagram will be drawn automatically. If the element at other end of that connector isn't on 
+the diagram at that moment, though, its connector won't appear; you'll only know that the association is there by looking at the 
+Property window (to see the base class) or the class's `Source` and `Target` compartments (for unidirectional and bidirectional 
+associations).
 
 ### Hiding vs Removing from the Diagram vs Deleting Elements
 
-You can take class and enumeration elements off the diagram as well, in three different ways.
+You can remove class and enumeration elements from the diagram as well, in three different ways.
 
 - **Hiding:** Model elements on any diagram can be hidden by selecting them, right-clicking and choosing `Hide Selected Elements`. They'll
-still be on the diagram, but invisible.
+still be on the diagram, but invisible. Because they're still present, they can't be added again.
 - **Removing from diagram:** Right-clicking one or more elements and choosing `Remove from diagram` (default hot key: `Ctrl-Del`) will remove those elements 
 from that diagram but not from the model. They will still be on other diagrams that were showing them, if any, as well as in the Model Explorer.
 - **Deleting:** To delete an element from the model, select one or more of them, right-click and choose `Delete` (default hot key: `Del`). 
-They'll be completely removed from your model and all diagrams without confirmation. If you make a mistake, you can undo the operation in the normal 
+They'll be completely removed from your model and all diagrams _without confirmation_. If you make a mistake, you can undo the operation in the normal 
 way (`Edit/Undo` or `Ctrl-Z`).
 
+### Dragging between diagrams ###
+
+You can copy elements in a diagram (default hot key: `Ctrl-C`) and paste it (default hot key: `Ctrl-V`) into another diagram _in the same model_. 
+Relative position information won't be copied over, and the pasted elements will be selected after the paste operation.
+
+If you cut elements from a diagram, you are effectively deleting the element from the model, the same as if you copied then then deleted them. Pasting them
+creates new elements but be aware that some connectors may not be pasted, depending on the elements you cut and stored in the clipboard.
+
+Copying elements between diagrams that live in different models isn't supported, but is a feature in the backlog that is being considered for
+future implementation.
+
 ### Next Step 
 [Persistent entities](Entities)
 

docs/Using-the-designer.md

@@ -181,7 +181,7 @@ can display any subset of your model to help create a laser focus on those thing
 Add a diagram by right-clicking the model explorer and selecting (oddly enough) "Add New Diagram". You'll get an empty design surface
 with a default name that you can change in the Property window. 
 
-We'll go into more details of multiple diagrams later. 
+We'll go into [more details of diagrams](Diagrams) later. 
 
 ### Generating Code
 
@@ -200,6 +200,6 @@ property on the design surface will default all the other output directories, an
 Solution Explorer tree when you generate your code files.
 
 ### Next Step 
-[Persistent entities](Entities)
+[Diagrams](Diagrams)
 
 

docs/_layouts/default.html

@@ -119,6 +119,13 @@ <h2 class="project-tagline">{{ site.description | default: site.github.project_t
             <li><a href="Using-the-designer.html#the-entity-model-explorer-window">The entity model explorer window</a></li>
             <li><a href="Using-the-designer.html#generating-code">Generating code</a></li>
          </ul>
+         <a href="Diagrams.html">Diagrams</a>
+         <ul>
+            <li><a href="Diagrams.html#concepts">Concepts</a></li>
+            <li><a href="Diagrams.html#adding-elements">Adding elements</a></li>
+            <li><a href="Diagrams.html#hiding-vs-removing-from-the-diagram-vs-deleting-elements">Hiding vs Removing from the Diagram vs Deleting Elements</a></li>
+            <li><a href="Diagrams.html#dragging-between-diagrams">Dragging between diagrams</a></li>
+         </ul>
          <a href="Entities.html">Persistent Entities</a>
          <ul>
             <li><a href="Entities.html#adding-an-entity">Adding an entity</a></li>