GNOME Bugzilla – Bug 552222
Ambiguous gconf key short and long descriptions
Last modified: 2009-01-09 22:21:38 UTC
I'm sorry to say that late at the development cycle but "data/pointer-capture-applet.schemas.in" has a lot of really bad descriptions. They may seem obvious for those already familiar with the applet, but they are very easy to mistranslate. Example: <short>Capture mouse button</short> <long>Mouse button to capture the pointer ("0" = Capture immediately)</long> I really couldn't understand this one. The short description is ambiguous; does the key chooses a button, or enable a capture? The long description seems like it's about a button, but the only value is "0", "capture. If it's about enabling the capture, then we should have something like: <short>Capture mouse button</short> <long>Whether if a mouse button should capture the pointer. Valid values are "0" (capture immediately) and "1" (description here).</long> Please notice the dot at the end of the long description. It helps us translators know that it is a long description. (It's not always so obvious.) Other example: <short>Capture modifier</short> <long>Capture modifier key (Shift)</long> Does this key chooses a modifier of the capture, or enables a capture of a modifier? And why are there three keys with the same short description (Capture modifier), and another three with another short description (Release modifier)? Sorry, but this file needs a rewrite. Then you'll need aprovals from the release team, the translation team, and (not sure) maybe the documentation team also.
(In reply to comment #0) > <short>Capture mouse button</short> > <long>Mouse button to capture the pointer ("0" = Capture immediately)</long> > > I really couldn't understand this one. The short description is ambiguous; does > the key chooses a button, or enable a capture? The long description seems like > it's about a button, but the only value is "0", "capture. If it's about > enabling the capture, then we should have something like: It means which mouse button has to be pressed to capture the pointer. The values are 1-3 for left, middle, right mouse button. Value 0 is a special case which means the pointer is captured as soon as the cursor hovers over the applet (= no button). > <short>Capture modifier</short> > <long>Capture modifier key (Shift)</long> > > Does this key chooses a modifier of the capture, or enables a capture of a > modifier? And why are there three keys with the same short description (Capture > modifier), and another three with another short description (Release modifier)? It means -> capture the mouse pointer only if the Shift key is pressed. The same applies to the other 2 modifiers Alt and Ctrl. There are separate options for every modifier to allow combinations. eg. Alt+Ctrl+Mouse Button 1. It's also possible to capture the mouse pointer with the left mouse button, but free/release it with a different key+button combination. That's why those options exist for both 'capture' and 'release'. > > Sorry, but this file needs a rewrite. Then you'll need aprovals from the > release team, the translation team, and (not sure) maybe the documentation team > also. > I agree, but I'd rather make the changes in the next cycle as those options are going to change or be removed altogether.
Is this fixed for GNOME 2.26?
Leonardo: We've updated all the descriptions of the keys now. Please let me know if something it still unclear.
Created attachment 126098 [details] [review] Description enhancements The changes in revision 369 are good, but the short descriptions are still not clear enough. When translators are updating the translations, it's not always clear for them which messages refer to the same gconf key, so you can't count on a long description to make the translator understand the meaning of a short description. I believe this patch makes the short descriptions free from any ambiguity, and it adds to the long descriptions all the information I learned from this bug report. Please check if the text is accurate and if you agree it's clear enough. Specifically: isn't "0" a valid value for \"release-pointer\"?
I have a doubt: if the user selects a right hand mouse button layout, how are the mousetweaker settings affected? Would "1" still mean left button?
Created attachment 126099 [details] [review] New diff Fixed quotes.
(In reply to comment #4) > I believe this patch makes the short descriptions free from any ambiguity, and > it adds to the long descriptions all the information I learned from this bug > report. Please check if the text is accurate and if you agree it's clear > enough. Specifically: isn't "0" a valid value for \"release-pointer\"? > Value "0" isn't implemented for release-pointer. > I have a doubt: if the user selects a right hand mouse button layout, how are > the mousetweaker settings affected? Would "1" still mean left button? If the handedness changes the button mappings would be reversed. "1" -> right button and "3" -> left button. However I don't think that's a problem, because this inconsistency is specifically explained in the GNOME user manual. Under section "Mouse Button Conventions" there's this note: "If you set your mouse device to be left handed, you should reverse the mouse button conventions used in this manual. This is normally also implied in most documentation and in many applications." and "Use Mouse Preferences to reverse the orientation of your mouse device. You will then need to reverse the mouse button conventions used in this manual and other GNOME documentation. See Section 8.4.2 ― Mouse Preferences for more information about setting your mouse preferences." The patch looks good, thanks very much.
Agreed. Committing.
I just noticed a typo. May I commit this fix? Index: pointer-capture-applet.schemas.in =================================================================== --- pointer-capture-applet.schemas.in (revisão 371) +++ pointer-capture-applet.schemas.in (cópia de trabalho) @@ -68,7 +68,7 @@ <default>false</default> <locale name="C"> <short>Release pointer only if Shift is pressed</short> - <long>Whether if the Shift key must be pressed with the mouse button set in "release-button" for the pointer to be released from the capture area.</long> + <long>Whether if the Shift key must be pressed with the mouse button set in "release_button" for the pointer to be released from the capture area.</long> </locale> </schema> <schema> @@ -78,7 +78,7 @@ <default>false</default> <locale name="C"> <short>Release pointer only if Alt is pressed</short> - <long>Whether if the Alt key must be pressed with the mouse button set in "release-button" for the pointer to be released from the capture area.</long> + <long>Whether if the Alt key must be pressed with the mouse button set in "release_button" for the pointer to be released from the capture area.</long> </locale> </schema> <schema> @@ -88,7 +88,7 @@ <default>false</default> <locale name="C"> <short>Release pointer only if Ctrl is pressed</short> - <long>Whether if the Ctrl key must be pressed with the mouse button set in "release-button" for the pointer to be released from the capture area.</long> + <long>Whether if the Ctrl key must be pressed with the mouse button set in "release_button" for the pointer to be released from the capture area.</long> </locale> </schema> </schemalist>
Sure. Feel free to commit updates to your own patches.
Thanks, fixed.