![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/keys.xml b/doc/keys.xml
index 9ce4771a06f19f556490705db66d9f077312167e..977ff4ba7f295a30f51d3dc31e4b7ba85f325fa5 100644 (file)
--- a/doc/keys.xml
+++ b/doc/keys.xml
</group>
<group>
-<title>Guides and grid</title>
+<title>Guides, grids, snapping</title>
<mouse><key><left-drag/></key> <action>drag off a ruler to create guide</action></mouse>
<note>Drag off the horizontal or vertical ruler to create a new guideline. Drag a guideline onto the ruler to delete it.</note>
<keys><key>|</key> <key><shift/>\</key> <action>toggle guides and snapping to guides</action></keys>
-<note>If you want to have different values for guides visibility and snapping, set them via the Document Options dialog.</note>
+<note>If you want to see the guides but not snap to them, use the global snapping toggle (% key).</note>
<note>When you create a new guide by dragging off the ruler, guide visibility and snapping are turned on.</note>
-<keys><key>#</key> <key><shift/>3</key> <action>toggle grid and snapping to grid</action></keys>
-<note>If you want to have different values for grid visibility and snapping, set them via the Document Options dialog.</note>
+<keys><key>#</key> <key><shift/>3</key> <action>toggle grids and snapping to grids</action></keys>
+<note>If you want to see the grids but not snap to them, use the global snapping toggle (% key).</note>
<note>Note that only the 3 key on the main keyboard works, not on the keypad.</note>
+<keys><key>%</key> <action>toggle snapping on and off</action></keys>
+<note>This toggle affects snapping to grids, guides, and objects in all tools.</note>
</group>
<group>
<mouse><key><left-drag/><misc-wide f="Space"/></key> <action>drop a copy</action></mouse>
<note>When dragging nodes with mouse, each Space leaves a copy of the selected object.</note>
<note>You can press and hold Space while dragging for a nice "trail."</note>
-<mouse><key><alt/><left-drag/></key> <action>sculpt nodes</action></mouse>
+<mouse><key><alt/><left-drag/></key> <action>sculpt selected nodes</action></mouse>
<note>Sculpting moves the selected nodes so that the dragged node moves all the way, the farthest selected nodes stay put;</note>
<note>all intermediate selected nodes move intermediate distances, governed by a bell-like curve.</note>
<note>Sculpting is pressure-sensitive with a tablet; press harder for a blunter drag profile, press lightly for a sharper profile.</note>
*<section title="3D box tool" color="cff4e2">
<group>
<title>Draw</title>
-<mouse><key><left-drag/></key> <action>draw a 3D box</action></mouse>
+<mouse><key><left-drag/></key> <action>draw a 3D box (X/Y plane)</action></mouse>
+<mouse><key><shift/><left-drag/></key> <action>draw a 3D box (extrude in Z)</action></mouse>
</group>
<group>
<keys><key><misc f="Esc"/></key> <action>deselect</action></keys>
</group>
+<group>
+<title>Edit by handles</title>
+<note>All editing operations occur "in perspective", i.e., either along PLs or within planes spanned by these.</note>
+<mouse><key><left-drag/></key> <action>resize/move box</action></mouse>
+<note>The four front handles and the center normally move withing the XY-plane, the four rear handles along the Z-axis.</note>
+<mouse><key><shift/><left-drag/></key> <action>resize/move (with handle behaviour swapped)</action></mouse>
+<mouse><key><ctrl/><left-drag/></key> <action>resize/move (handles snap to axes or diagonals)</action></mouse>
+</group>
+
+<group>
+<title>Edit perspectives</title>
+<note>In what follows, we use the abbreviations VP = vanishing point, PL = perspective line.</note>
+<mouse><key><left-drag/></key> <action>drag square handles to move the VPs</action></mouse>
+<keys><key>[</key> <key>]</key> <action>rotate X-PLs (if parallel) by the angle step</action></keys>
+<note>The default angle step is 15 degrees. ],),} rotate clockwise, [,(,{ rotate counterclockwise.</note>
+<keys><key><alt/>[</key> <key><alt/>]</key> <action>rotate X-PLs (if parallel) by 1 pixel</action></keys>
+<keys><key>(</key> <key>)</key> <action>rotate Y-PLs (if parallel) by the angle step</action></keys>
+<keys><key><alt/>(</key> <key><alt/>)</key> <action>rotate Y-PLs (if parallel) by 1 pixel</action></keys>
+<keys><key>{</key> <key>}</key> <action>rotate Z-PLs (if parallel) by the angle step</action></keys>
+<keys><key><alt/>{</key> <key><alt/>}</key> <action>rotate Z-PLs (if parallel) by 1 pixel</action></keys>
+</group>
+
+<group>
+<title>Visual appearance</title>
+<keys><key>L</key> <action>toggle visibility of PLs</action></keys>
+<keys><key>A</key> <action>toggle PLs to all corners/only front corners</action></keys>
+</group>
+
</section>
*<section title="Ellipse tool" color="ffece8">
<group>
<title>Draw</title>
+<note>Without Alt the starting end ending point of the mouse drag mark the corners of the bounding box.</note>
+<note>With Alt the ellipse is enlarged so that its circumference passes through these two points (Ctrl+Alt is a special case; see below).</note>
<mouse><key><left-drag/></key> <action>draw an ellipse</action></mouse>
<mouse><key><ctrl/><left-drag/></key> <action>make circle or integer-ratio ellipse</action></mouse>
<note>This restricts ellipse so its height/width ratio is a whole number.</note>
<mouse><key><shift/><left-drag/></key> <action>draw around the starting point</action></mouse>
<note>This creates an ellipse symmetric around the starting point of the mouse drag.</note>
+<mouse><key><ctrl/><alt/><left-drag/></key>create circle passing through the starting and ending point<action></action></mouse>
+<note>This creates a perfect circle whose diameter is defined by the starting and ending point of the mouse drag.</note>
</group>
<group>
<mouse><key><shift/><left-drag/></key> <action>temporarily disable snapping</action></mouse>
<note>Shift also temporaily disables snapping to grid or guides when you are drawing with grid or guides on.</note>
</group>
+
+<group>
+<title>Create dots</title>
+<mouse><key><ctrl/><left-click/></key> <action>create a dot</action></mouse>
+<note>This creates a small circle. Its size (relative to the current stroke width) can be set in Preferences.</note>
+<mouse><key><shift/><ctrl/><left-click/></key> <action>create a double-sized dot</action></mouse>
+<mouse><key><alt/><ctrl/><left-click/></key> <action>create a random-sized dot</action></mouse>
+</group>
</section>
*<section title="Pen (Bezier) tool" color="e7f5d7">
<note>These commands change the last (red) segment of the path to straight line or curve.</note>
</group>
+<group>
+<title>Create dots</title>
+<mouse><key><ctrl/><left-click/></key> <action>create a dot</action></mouse>
+<note>This creates a small circle. Its size (relative to the current stroke width) can be set in Preferences.</note>
+<mouse><key><shift/><ctrl/><left-click/></key> <action>create a double-sized dot</action></mouse>
+<mouse><key><alt/><ctrl/><left-click/></key> <action>create a random-sized dot</action></mouse>
+</group>
+
<group>
<title>Finish</title>
<keys><key><misc-wide f="Enter"/></key> <action>finish current line</action></keys>
<title>Select handles</title>
<mouse><key><left-click/></key> <action>select a handle</action></mouse>
<mouse><key><shift/><left-click/></key> <action>add handle to selection</action></mouse>
+<mouse><key><shift/><left-drag/></key> <action>select by rubberband</action></mouse>
<keys><key><misc f="Tab"/></key> <action>select next handle</action></keys>
<keys><key><shift/><misc f="Tab"/></key> <action>select previous handle</action></keys>
+<keys><key><ctrl/>A</key> <action>select all handles</action></keys>
<keys><key><misc f="Esc"/></key> <action>deselect all handles</action></keys>
+<note>Single click outside all handles also deselects all handles.</note>
</group>
<group>
-<title>Create/delete stops</title>
+<title>Create/delete intermediate stops</title>
<mouse><key><ctrl/><alt/><left-click/></key> <action>create a stop</action></mouse>
<mouse><key><left-click/><left-click/></key> <action>create a stop</action></mouse>
<note>Ctrl+Alt+click or double click on a gradient line creates a new intermediate stop</note>
<mouse><key><ctrl/><alt/><left-click/></key> <action>delete stop</action></mouse>
-<note>Ctrl+Alt+click on a stop's handle deletes the stop;</note>
-<note>if it was an end stop, gradient shortens or disappears</note>
+<note>Ctrl+Alt+click on a stop's handle deletes the stop; if it was an end stop, gradient shortens or disappears</note>
+<keys><key><misc f="Ins"/></key> <action>insert new stop(s)</action></keys>
+<note>This adds new stop(s) in the middle(s) of selected segment(s), so it requires that more than two adjacent handles be selected.</note>
<keys><key><misc f="Del"/></key> <action>delete selected stops</action></keys>
</group>
<group>
-<title>Move handles</title>
-<!-- TODO: restore! -->
+<title>Move handles/stops</title>
<mouse><key><left-drag/></key> <action>move selected handle(s)</action></mouse>
+<mouse><key><ctrl/><left-drag/></key> <action>move stops in 1/10 range increments</action></mouse>
+<note>Ctrl+dragging selected intermediate stops moves them snapping to 1/10 steps of the available range</note>
+<mouse><key><alt/><left-drag/></key> <action>sculpt selected stops</action></mouse>
+<note>Sculpting moves the selected intermediate stops depending on how close each one is to the stop being dragged, using a smooth bell-like curve similar to the node sculpting feature in Node tool.</note>
<mouse><key><arrows/></key> <action>move selected handle by the nudge distance</action></mouse>
<mouse><key><shift/><arrows/></key> <action>move selected handle by 10x nudge distance</action></mouse>
<note>The default nudge distance is 2 px (SVG pixel units, not screen pixels).</note>
<mouse><key><alt/><arrows/></key> <action>move selected handle by 1 pixel</action></mouse>
<mouse><key><alt/><shift/><arrows/></key> <action>move selected handle by 10 pixels</action></mouse>
+<note>If at least one end handle is selected, arrow keys move the end handle to move or resize the gradient line.</note>
+<note>If only mid stops are selected, arrow keys move the selected stops along the gradient line.</note>
<note>The actual distance for pixel movements depends on zoom level. Zoom in for finer movement.</note>
-<!-- TODO:
-<mouse><key><alt/><left-drag/></key> <action>sculpt handles</action></mouse>
-<note>Sculpting moves the selected handles so that the dragged handle moves all the way, the farthest handles stay put, and the intermediate handles move intermediate distances, governed by a bell-like curve</note>
- -->
</group>
<group>