Merge lp:~clissold345/ubuntu-docs/fix-for-964727 into lp:~ubuntu-core-doc/ubuntu-docs/trunk2017-07-10

[Chris Perry]

Please see the comment I added to the bug report:

https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs/+bug/964727

[Gunnar Hjalmarsson (gunnarhj)]

Thanks for your work with this, Chris.

You addressed the bug reporter's request by dropping the "most keyboards..." para, and the change of step 4 was apparently necessary (probably the last tab was not present when the page was written originally).

I have a few thoughts.

This sentence: "With mouse keys there are three buttons: primary, alternate, and modifier." confuses me. Which buttons? I don't see any buttons. Shouldn't it rather be three modes or three levels? Or am I missing something? (I see on the Wikipedia page that the term "button" is used, but it doesn't make me understand it better.) Can you somehow explain/justify the use of the term "button" in this context?

Personally I think the table is redundant. The clarifications you added through the bullet points already covers it, don't they?

review: Needs Information

[Chris Perry (clissold345)]

Hi Gunnar

Have you tried mouse keys out? I found it made more sense when I tried it out. One of my laptops has a (real) numeric keypad, which was useful.

My take on mouse keys is that it simulates a pointing and clicking device with three buttons (eg a three-button mouse - but not necessarily a mouse - other pointing and clicking devices are available). The wikipedia page just uses the term button (without quotes), so I've copied that. Of course there is no physical button/buttons, so it could perhaps be termed a virtual button?

I'd say that the page needs to give the meaning/action of all the mouse keys. My examples just cover the main examples, they don't cover all the the mouse keys actions. Eg the examples don't cover all the navigation keys. Also - though this is a bit specialized - mouse keys provides three kinds of drag and drop and my examples only cover one kind (though I'm not sure if any applications distinguish between the different drags and drops). I've given the meaning/action of the keys using a table (adapting the table in the wikipedia page) but I think the info could be given a different way (eg in a diagram?).

Does the above make sense?

[Gunnar Hjalmarsson (gunnarhj)]

Yep, I tried it out. Not extensively, though. You are right, it does simulate the mouse buttons. I withdraw my objection on that one.

Still hesitating wrt to the table, but you did the work and I trust your feeling for how much info is motivated.

Your changes improve the page significantly, btw. Thanks again!

review: Approve

=== modified file 'ubuntu-help/C/mouse-mousekeys.page'
--- ubuntu-help/C/mouse-mousekeys.page	2013-09-15 00:45:58 +0000
+++ ubuntu-help/C/mouse-mousekeys.page	2016-12-10 19:51:44 +0000
@@ -34,11 +34,13 @@
 control the mouse pointer using the numeric keypad on your keyboard. This
 feature is called <em>mouse keys</em>.</p>
 
+<p>To enable mouse keys using the keyboard:</p>
+
 <steps>
   <item><p>Tap the <key><link xref="windows-key">Super</link></key> key to open the <gui>Dash</gui>.</p></item>
   <item><p>Type <input>Universal Access</input> and press <key>Enter</key> to open the Universal Access settings.</p></item>
   <item><p>Press <key>Tab</key> once to select the <gui>Seeing</gui> tab.</p></item>
-  <item><p>Press <key>←</key> once to switch to the <gui>Pointing and Clicking</gui> tab.</p></item>
+  <item><p>Press <key>←</key> twice to switch to the <gui>Pointing and Clicking</gui> tab.</p></item>
   <item><p>Press <key>↓</key> once to select the <gui>Mouse Keys</gui> switch then press <key>Enter</key> to switch it on.</p></item>
  <item>
   <p>
@@ -49,39 +51,157 @@
 </steps>
 
  <note style = "tip">
- <p>These instructions provide the shortest way to enable mouse keys using
- only the keyboard. Select <gui>Universal Access Settings</gui> to see more
+ <p>The above instructions provide the shortest way to enable mouse keys using
+ only the keyboard. See <gui>Universal Access</gui> settings for more
  accessibility options.</p>
  </note>
 
-<p>
-The keypad is a set of numerical buttons on your keyboard, usually arranged
-into a square grid. If you have a keyboard without a keypad (such as a laptop
-keyboard), you may need to hold down the function (<key>Fn</key>)
+<p></p>
+
+<p>
+The numeric keypad is a set of numerical buttons on your keyboard, usually arranged
+into a square grid. With mouse keys there are three buttons: primary, alternate, and modifier. Initially the primary button is selected.
+Here are some examples of how to use mouse keys:</p>
+
+<list type="circle">
+
+  <item><p>
+Each number on the keypad (except 0 and 5) corresponds to a direction. For example, pressing
+<key>8</key> will move the pointer upwards and pressing <key>2</key> will move
+it downwards.
+</p></item>
+
+  <item><p>
+To click the selected button, press <key>5</key>.
+</p></item>
+
+  <item><p>
+To double-click the selected button, quickly press 
+<key>5</key> twice or press <key>+</key> once. 
+</p></item>
+
+  <item><p>
+To right click, 
+press <key>-</key> to select the alternate button (if it is not already selected) and press <key>5</key>.
+</p></item>
+
+  <item><p>
+To middle click, 
+press <key>*</key> to select the modifier button (if it is not already selected) and press <key>5</key>.
+</p></item>
+
+
+  <item><p>
+To drag and drop using the primary button, 
+press <key>/</key> to select the primary button (if it is not already selected),
+press <key>0</key> to depress the button, drag the pointer to the required position, and 
+press <key>.</key> to release the button.
+</p></item>
+
+
+</list>
+
+<p>
+ </p>
+<p>Here is a table of mouse keys and their actions:</p>
+
+
+<table frame="top bottom" rules="rows">
+
+  <tr>
+    <td><p><em>Key</em></p></td>
+    <td><p><em>Action</em></p></td>
+  </tr>
+  <tr>
+    <td><p><key>8</key></p></td>
+    <td><p>Pointer up</p></td>
+  </tr>
+  <tr>
+    <td><p><key>2</key></p></td>
+    <td><p>Pointer down</p></td>
+  </tr>
+  <tr>
+    <td><p><key>6</key></p></td>
+    <td><p>Pointer right</p></td>
+  </tr>
+  <tr>
+    <td><p><key>4</key></p></td>
+    <td><p>Pointer left</p></td>
+  </tr>
+
+  <tr>
+    <td><p><key>7</key></p></td>
+    <td><p>Pointer up and left</p></td>
+  </tr>
+  <tr>
+    <td><p><key>9</key></p></td>
+    <td><p>Pointer up and right</p></td>
+  </tr>
+  <tr>
+    <td><p><key>3</key></p></td>
+    <td><p>Pointer down and right</p></td>
+  </tr>
+  <tr>
+    <td><p><key>1</key></p></td>
+    <td><p>Pointer down and left</p></td>
+  </tr>
+
+  <tr>
+    <td><p><key>/</key></p></td>
+    <td><p>Select the primary button. On a mouse the primary button is usually the left button</p></td>
+  </tr>
+  <tr>
+    <td><p><key>*</key></p></td>
+    <td><p>Select the modifier button. On a mouse the modifier button (if present) is usually the middle button</p></td>
+  </tr>
+  <tr>
+    <td><p><key>-</key></p></td>
+    <td><p>Select the alternate button. On a mouse the alternate button is usually the right button</p></td>
+  </tr>
+  <tr>
+    <td><p><key>5</key></p></td>
+    <td><p>Click selected button</p></td>
+  </tr>
+
+  <tr>
+    <td><p><key>+</key></p></td>
+    <td><p>Double click selected button</p></td>
+  </tr>
+  <tr>
+    <td><p><key>0</key></p></td>
+    <td><p>Depress selected button</p></td>
+  </tr>
+  <tr>
+    <td><p><key>.</key></p></td>
+    <td><p>Release selected button</p></td>
+  </tr>
+
+</table>
+
+<p>
+</p>
+
+<note>
+<p>If you have a keyboard without a keypad (as with some laptops),
+you may need to hold down the function (<key>Fn</key>)
 key and use certain other keys on your keyboard as a keypad. If you use this
-feature often on a laptop, you can purchase external USB keypads.
-</p>
-
-<p>
-Each number on the keypad corresponds to a direction. For example, pressing
-<key>8</key> will move the pointer upwards and pressing <key>2</key> will move
-it downwards. Press the <key>5</key> key to click once with the mouse, or
-quickly press it twice to double-click.
-</p>
-
-<p>
-Most keyboards have a special key which
-allows you to right-click; it is often near to the space bar. Note, however,
-that this key responds to where your keyboard focus is, not where your mouse
-pointer is. See <link xref="a11y-right-click"/> for information on how to
-right-click by holding down <key>5</key> or the left mouse button.
-</p>
-
+feature often, you may wish to purchase an external USB keypad.
+</p>
+</note>
+
+<p>
+</p>
+
+<note>
 <p>
 If you want to use the keypad to type numbers while mouse keys is enabled, turn
 <key>Num Lock</key> on. The mouse cannot be controlled with the keypad when
 <key>Num Lock</key> is turned on, though.
 </p>
+</note>
+
+<p>
+</p>
 
 <note>
     <p>
@@ -90,4 +210,5 @@
     </p>
 </note>
 
+
 </page>