Difference between revisions of "Settings Wording"

From GnuCash
Jump to: navigation, search
m (Doh moved to GConf Wording)
Line 1: Line 1:
This page describes the wording style that gnucash tries to follow in the description of the GConf configuration keys.
+
== Brain Teasers - How To Play The "Mind Reading" Game ==
  
== HIG ==
 
  
Gnome Human Interface Guidelines (HIG): http://developer.gnome.org/projects/gup/hig/2.0/gconf-keys.html
+
Their are lots of people who wanted to have such mind reading books and games. In this kind of situation [http://www.trickyriddles.com/ '''Brain Teasers'''] can be the best for those individual to have its best situations they may need to have in life. Making an individual have the things that can be the best for those people in a certain period of time. It can make those people have such situations wherein people can surely satisfy their needs in living. It can make an individual have the chance of having '''brain teasers''' in life. With the best situations helping an individual learn many things with having such game he/she may need to have in life. Brain Teasers can be a great help for those people on having such ways they can have in life.
  
== General wording ==
 
Pretty much the only helpful suggestion from the HIG is that the "short description should be less than 8 words". To achieve this, any "fill words" like "This key..." or "Enable this..." or even "this" ''should not'' be used in the short description.
 
  
So we need to find out a good wording and style for ourselves. A useful approach is to distinguish the different keys by their ''key type''. For now, we only copy the existing wordings here. We should then decide which ones should be kept and which ones should be replaced.
+
Making such ways that will surely make an individual gain brain teasers that they may need to have in life. [http://www.trickyriddles.com/ '''Brain Teasers'''] can be the best things an individual may need to have in a certain period of time. It is best for those people to have such ways that will surely make those people satisfy their needs in living. With these things it can make an individual have a great ways in life. It is best for those people to have such '''Brainteasers''' that will surely make them have its best situations in life.
 
 
Some numbers: We have currently 123 different gconf keys in gnucash. Since each key eventually has two description strings, the question of consistent wording is definitely non-trivial. The vast majority (more than 50%) are <tt>bool</tt> keys. The exact numbers are:
 
* 55 bool
 
* 26 int
 
* 17 list
 
* 15 string
 
* 10 float
 
 
 
== Recommendations per key type ==
 
=== bool key types ===
 
The <tt>bool</tt> keys are the vast majority in gnucash. This makes them a good example to find out a way for consistent wording of the descriptions.
 
==== Recommendations ====
 
Proposed '''recommendations for short descriptions:''' The short descriptions should not be complete sentences; instead, I'd propose to imagine a full sentence beginning with "If this setting is active, gnucash will ''do xyz''". We should use only the latter part "''do xyz''" as the short description. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST)
 
 
 
Proposed '''recommendations for long descriptions:''': It turns out bool keys are used in two different ways.
 
* One usage refers to a key that activates/deactives something user-visible in gnucash. In that case, I propose the following example wording because we don't have to explicitly mention the semantics of active vs. not active:
 
** ''This setting enables the commodity column in the register.''
 
* The other usage refers to a key where the semantics of activated/deactivated are not obvious but correspond to one out of two choices. I propose the following wording so that there is a clear "if active, foo will happen; otherwise, bar will happen" distinction between the two available choices:
 
** ''If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched.''
 
 
 
==== Existing wording ====
 
Existing wording in gnucash for <tt>bool</tt> keys:
 
* Set this value to TRUE to...
 
* If this field is TRUE then...
 
* If set to TRUE then...
 
* If TRUE, ...
 
* Setting this value to TRUE tells gnucash to...
 
* A value of TRUE says to...
 
* Set this key to TRUE to ...
 
* This key indicates whether...
 
* This key indicates whether to...
 
* Whether or not to ...
 
* This setting controls whether or not...
 
* Enable ...
 
 
 
Sigh. One obvious thought is that users don't see any value labeled ''TRUE''; they only see a checkbox that may be activated or deactivated. Also, the wording "whether or not" doesn't really add useful information here, because the user will always see a checkbox which unambiguously explains that this setting is about something that is active or not. Also, the user doesn't know that these settings are called "keys" internally.
 
 
 
==== Two Examples ====
 
TODO: Decide on one of the following example possibilities for long descriptions (from [http://svn.gnucash.org/repo/gnucash/trunk/src/gnome/schemas/apps_gnucash_dialog_prices.schemas.in here]):
 
# If active, the commodity column in the register will be shown.
 
# This setting controls whether gnucash shows the commodity column in the register.
 
# This setting enables the commodity column in the register.
 
Comment: This example refers to a key that activates/deactives something user-visible in gnucash. In that case, I'd vote to use the wording #3 because we don't have to explicitly mention the semantics of active vs. not active. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST)
 
 
 
TODO: Decide on one of the following example possibilities for long descriptions (from [http://svn.gnucash.org/repo/gnucash/trunk/src/business/business-gnome/schemas/apps_gnucash_dialog_business_common.schemas.in here]):
 
# If active, only the 'active' items in the current class will be searched. Otherwise all items in the current class will be searched.
 
# This setting controls whether gnucash searches only in the 'active' items in the current class. If not active, only the 'active' items in the current class will be searched.
 
Comment: This example refers to a key where the semantics of activated/deactivated are not obvious but correspond to one out of two choices. I'd vote for #1 so that there is a clear "if active, foo will happen; otherwise, bar will happen" distinction between the two available choices. --[[User:Cstim|Cstim]] 04:45, 8 February 2006 (EST)
 
 
 
=== int ===
 
==== Existing wording ====
 
* This value specifies...
 
* This dialog is presented ... (obviously the flag for "don't show again")
 
* This setting controls...
 
* This key contains the...
 
 
 
=== string ===
 
'''Recommendation:''' Actually most of the existing wordings are just fine, except that the word "key" shouldn't be used and instead of using either "field" or "setting" we should agree on one. I'd recommend to write always "''This setting {contains,determines,specifies}...''" --[[User:Cstim|Cstim]] 05:14, 8 February 2006 (EST)
 
==== Existing wording ====
 
* This key contains...
 
* This setting determines...
 
* This setting allows...
 
* This setting controls how...
 
* This field specifies...
 
 
 
=== list string ===
 
==== Existing wording ====
 
* This key contains a list of names which ...
 
* This key indicates which ...
 
* This key indicates how ...
 
 
 
=== list int ===
 
==== Existing wording ====
 
* This key contains the coordinates describing...
 
* The X,Y coordinates...
 
* This value contains the X,Y coordinates...
 
 
 
=== float ===
 
==== Existing wording ====
 
* This field sets the number of...
 
 
 
== Tools ==
 
To view all schemas files in one big file, run the following command in the gnucash top directory:
 
head -1000 `grep schemas po/POTFILES.in` > allschemas.xml
 
(which, actually, isn't a valid XML file anymore, but it still looks similar to one.)
 
 
 
To write all 14 schemas files back in the whole trunk from the above created single file allschemas.xml, use:
 
perl -ne 'if (/^==> (.*) <==$/) {
 
  $fname="$1"; open(STDOUT, ">$fname") or die "cannot open $fname: $!";
 
  } else { print; } ;' allschemas.xml
 
but note that due to the headers of <tt>head</tt> this will inadvertantly add one newline at the end of all 14 files except the last one. This could potentially be avoided by the following script instead:
 
perl -ne 'if (/^$/) { $emptylines++; } else {
 
  if (/^==> (.*) <==$/) {
 
    $fname="$1";
 
    open(STDOUT, ">$fname") or die "cannot open $fname: $!";
 
    $emptylines = 0;
 
  } else {
 
    while ($emptylines > 0) { print "\n"; $emptylines--; };
 
    print;
 
  }
 
}; ' allschemas.xml
 

Revision as of 01:38, 20 January 2011

Brain Teasers - How To Play The "Mind Reading" Game

Their are lots of people who wanted to have such mind reading books and games. In this kind of situation Brain Teasers can be the best for those individual to have its best situations they may need to have in life. Making an individual have the things that can be the best for those people in a certain period of time. It can make those people have such situations wherein people can surely satisfy their needs in living. It can make an individual have the chance of having brain teasers in life. With the best situations helping an individual learn many things with having such game he/she may need to have in life. Brain Teasers can be a great help for those people on having such ways they can have in life.


Making such ways that will surely make an individual gain brain teasers that they may need to have in life. Brain Teasers can be the best things an individual may need to have in a certain period of time. It is best for those people to have such ways that will surely make those people satisfy their needs in living. With these things it can make an individual have a great ways in life. It is best for those people to have such Brainteasers that will surely make them have its best situations in life.