GNOME Bugzilla – Bug 309210
Placeholder bug for needed gcalctool documentation changes.
Last modified: 2006-10-30 16:37:29 UTC
This bug will list all the changes needed to the gcalctool documentation (online help and manual pages). 1/ See bug #309182. The way of entering scientific numbers with a negative exponent is different in arithmetic operator precedence mode that the way it's done in non-arithmetic operator precedence mode ("classic" mode). In non-arithmetic operator precedence mode, you would enter something like: 12 Exp 8 +/- to get 0.00000012 This is how it's currently documented. In arithmetic operator precedence mode, you would enter: 12 Exp +/- 8 Notice the change of entry order.
2/ Bug #168694 gcalctool now saves/restores the ten memory register values as gconf resources. 3/ Bug #167479 gcalctool will set the View->Memory Registers menu item inactive if the calculator is in Basic mode. 4/ Bug #172704 and bug #172869 When the user now uses the keyboard shortcut for any of the gcalctool buttons that have a menu associated with them, that menu is now displayed. The user can use the arrow keys to select a menu item or the menu items shortcut. 5/ Bug #304056 Adjusted the keyboard shortcuts for the Xor and x^y operations. New values are: Xor - 'x' x^y - '^'
Sorry, I gave the wrong information for entry #1 and there doesn't seem to be a way of editing in-situ, so here it is again (hopefully correct this time). 1/ See bug #309182. The way of entering scientific numbers with a negative exponent is different in arithmetic operator precedence mode that the way it's done in non-arithmetic operator precedence mode ("classic" mode). In non-arithmetic operator precedence mode, you would enter something like: 12 Exp 8 +/- to get 0.00000012 This is how it's currently documented. In arithmetic operator precedence mode, you would enter: 12 Exp - 8 Notice the use of the minus sign instead of the change sign, and the change of entry order.
6/ See bug #153854 If the user tries to change modes, a warning dialog is displayed: Changing Modes Clears Calculation When you change modes, the current calculation will be cleared, and the base will be reset to decimal. There is a checkbox that can be toggled that says: Do not warn me again If the user presses the Cancel button, the change mode operation is cancelled. If the user presses the Okay button, the mode is changed. This has the following side-effects: * Clears the display * Sets the base to decimal * Sets the numeric display to fixed * Sets the accuracy to nine places after the numeric point. * Clears the display of the thousands separator * Clears the display of trailing zeroes after the numeric point. and dismisses the register window if the new mode is Basic.
Unfortunately these changes didn't make it into gcalctool for GNOME 2.12. I'll keep the bug open, and start listing changes that will now also have to be added for GNOME 2.13/14. a/ Bug #312609 and bug #162453. The memory register window is now a dialog that uses GtkEntry widgets to display the register values. There is also a close button to easily dismiss this dialog. If there are any screen shots of the memory register window, they will need to be reshot. b/ Bug #148104 There is now a Mod (Modulus Division) operation in Scientific Mode. A Mod B return the remainder when you divide A by B. A and B must be integers. Keyboard shortcut for this operation is "M". Any screenshots of Scientific mode will need to be reshot. c/ Bug #316382. The "useless" cursor is no longer displayed in the calculator display area. If there are any screen shots showing this cursor, then they will need to be reshot.
d/ Bug #157961 Started to implement a bit panel for non-arithmetic precedence mode. It's automatically displayed when in Scientific mode, and active when integers (upto 64 bit) are being displayed. It allows you to toggled individual bits in the current display.
e/ Bug #323722 Operations like Ctrm need an explicit "=" to actually perform them. The gcalctool documentation should mention this is an obvious place.
f/ Bug #323149 Gcalctool now uses the Unicode symbols for division, multiplication, plus/minus, minus and square root. Any screenshots that show these symbols are going to be incorrect.
g/ Bug #328524 The documentation for operations like "square root" is incorrect when the user is in arithmetic operator precedence mode. In order to do the square root of 5, the actual sequence of commands that they have to enter is: Sqrt( 5 ) = There are probably several other similar operations that need to be formatted this way.
h/ The documentation for Clear Entry and Clear could be better. For example, Clear Entry is only now appropriate when "Use Arithmetic Operator Precedence" mode is not checked. See bug #344691 for more information.
*** Bug 349735 has been marked as a duplicate of this bug. ***
i/ From bug #348765: Documentation Section: (Usage) 3.5.11. To Use Functions 3. Click on the Value field, then enter the new value. Use the keyboard shortcuts to invoke a Calculator button. For example, enter 90K to calculate sine(90). Correct version: A couple of simple working examples. A Farenheit to Celcius conversion example might be nice, if possible. Can the function use the number already on the display or is it not really a function so it can only hold a constant? Other information: Even though I'm not using the most recent version, I didn't see a bug report in bugzilla and I couldn't find the change in the changelog so I'm posting this bug. The help file says you should be able to create a function, that takes the sin of 90 degrees, by entering 90K in the value field of the Edit Functions dialog box. It doesn't seem to work. Only simple expressions such as 2+3*4= gave results. It took a lot of trial and error to figure out how to get it to give me anything but a malformed function error. While the function syntax seems obvious in hindsight, I kept trying various things like standard spreadsheet notation =2+3*4 and plain old 2+3*4 Is there any way to include the display value so that the user functions are actually functions and not just constant expressions? I'm running Ubuntu 6.06
*** Bug 348765 has been marked as a duplicate of this bug. ***
*** Bug 165919 has been marked as a duplicate of this bug. ***
The operation of % operator has changed. It's now same as dividing the number by 100 (= one percent of the original number). --- Example: non-arithmetic precedence mode 5 % Display now shows 0.05 --- Example: arithmetic precedence mode Calculating expression "5%" yeilds 0.05.
Another change for gcalctool in GNOME 2.17/18. The bitcalculating extension is now available in both arithmetic operator precedence mode and non-arithmetic operator precedence mode. It's no longer always displayed . There is a new option in the View menu, that if checked, with show this extension. (Also adjusting summary for this bug to better reflect that these all all the documentation changes that need to be made for gcalctool).
*** Bug 364411 has been marked as a duplicate of this bug. ***
I'm not sure that having one monster bug for all the problems and hoping a knight in shining armour will fix the lot in one fell swoop is the best way to go about things. A huge heap of things to fix will be quite daunting the newcomers, and the existing docs team people don't have much time. In future, it might be best to file one bug per problem. I for one prefer to work that way. Make small fixes, commit, close bug, in and out fast like a ninja ;)
Seeing as this is a big list of points already: - there is inconsistency in the markup used for entering numbers: <para>12 <guibutton>Exp</guibutton> <guibutton>8</guibutton> The 12 has no guibutton (or rather the 1 and the 2, but the 8 does. A docbook expert's opinion is needed, ie Shaun. - Chunking depth should be changed - Usage should be split. I would suggest grouping the current subtopics into Basic / Advanced / Financial / Scientific, as at the moment a topic like 'To Enter Exponential Numbers' gives no indication of which mode I need to be in to actually do this task.
I'll add that great chunks of this manual are because of this arithmetic operator precedence mode lark.
A lot of the problems reported here, did originally have separate bug numbers. I have no problem with somebody from the gnome documentation team reopening them and fixing them individually if that is your preferred way of working. Bugzilla unfortunately doesn't make it easy to remove/edit previous comments when such a particular bug is fixed. Perhaps there is a better way to do this. Maybe a page on a Wiki somewhere... The main problem here is I don't understand the gnome documentation system. If I did, I would have fixed these problems long ago. It needs somebody who does understand it, to step up and help out. Carving off little chunks at a time and fixing them is fine with me. Any volunteers?
If you need pointers on editing the docs yourself, I'm happy to answer questions or review patches. I'm also going to try and tackle a few of these from time to time but when a manual is this far out of date it's rather demoralizing. Is it DocBook syntax in particular you have problems with? That's a bit of a pain I agree. (It's probably not worth the hassle to go round reopening all those bugs.) My comment above should have said that the existence of arithmetic operator precedence mode means that a section such as Exponents almost needs to be written twice, because it is so different in the two modes. I'm not sure how to best resolve this.
I'm running GNOME on Solaris. I don't think I have an environment currently where DocBook works properly. Are there any GUI tools (sort of the equivalent of an HTML editor) for handling these files? Or are you in there, editing the files in a text editor "by hand"? If it's the latter, I'd prefer to leave this to somebody a lot more experienced than me. Combine this with my full time job of working on Orca. I'm not likely to make too many changes either myself. It's unfortunate that Sun decided to RIF its GNOME documentation team a couple of years back. They were handling all this for gcalctool.
Lol... GUI tools? It's just gedit to edit the source and yelp to view.
Well, good luck with that!
So it looks to me like the bugs here are generally reported against gcalctool itself. After they've been fixed, they're listed here to remind somebody to make corresponding changes in the documentation. I generally applaud this, as most maintainers just resolve the bugs, and the documentation team never knows anything needs to be changed. But a big tracker bug like this is hard to track, because we can't close things off when we make documentation changes. What I suggest instead is that, for any bugs that also need documentation work, you simply move the bug to the docs component when you would otherwise resolve them. It would also be nice to add a comment at the end giving a quick synopsis of what changed to the documentation folks. Is that reasonable?
Yup, very reasonable. Here's a summary of what I believe is currently outstanding. You are welcome to file individual bugs against these (or reopen the original ones), and fix them separately. Just so you have the right historical perspective, having them in a single bug is how I used to do this with Breda McColgan. That's the way she preferred it. Unfortunately she was RIF'ed from Sun during the gathering of gcalctool doc changes for GNOME 2.12. -------------------------------------------------------------------------- * From comment #2 1/ The way of entering scientific numbers with a negative exponent is different in arithmetic operator precedence mode that the way it's done in non-arithmetic operator precedence mode ("classic" mode). In non-arithmetic operator precedence mode, you would enter something like: 12 Exp 8 +/- to get 0.00000012 This is how it's currently documented. In arithmetic operator precedence mode, you would enter: 12 Exp - 8 Notice the use of the minus sign instead of the change sign, and the change of entry order. -------------------------------------------------------------------------- * From comment #1 2/ Bug #168694 gcalctool now saves/restores the ten memory register values as gconf resources. 3/ Bug #167479 gcalctool will set the View->Memory Registers menu item inactive if the calculator is in Basic mode. 4/ Bug #172704 and bug #172869 When the user now uses the keyboard shortcut for any of the gcalctool buttons that have a menu associated with them, that menu is now displayed. The user can use the arrow keys to select a menu item or the menu items shortcut. 5/ Bug #304056 Adjusted the keyboard shortcuts for the Xor and x^y operations. New values are: Xor - 'x' x^y - '^' -------------------------------------------------------------------------- * From comment #3 6/ See bug #153854 If the user tries to change modes, a warning dialog is displayed: Changing Modes Clears Calculation When you change modes, the current calculation will be cleared, and the base will be reset to decimal. There is a checkbox that can be toggled that says: Do not warn me again If the user presses the Cancel button, the change mode operation is cancelled. If the user presses the Okay button, the mode is changed. This has the following side-effects: * Clears the display * Sets the base to decimal * Sets the numeric display to fixed * Sets the accuracy to nine places after the numeric point. * Clears the display of the thousands separator * Clears the display of trailing zeroes after the numeric point. and dismisses the register window if the new mode is Basic. -------------------------------------------------------------------------- * From comment #4 a/ Bug #312609 and bug #162453. The memory register window is now a dialog that uses GtkEntry widgets to display the register values. There is also a close button to easily dismiss this dialog. If there are any screen shots of the memory register window, they will need to be reshot. b/ Bug #148104 There is now a Mod (Modulus Division) operation in Scientific Mode. A Mod B return the remainder when you divide A by B. A and B must be integers. Keyboard shortcut for this operation is "M". Any screenshots of Scientific mode will need to be reshot. c/ Bug #316382. The "useless" cursor is no longer displayed in the calculator display area. If there are any screen shots showing this cursor, then they will need to be reshot. -------------------------------------------------------------------------- * From comment #5 d/ Bug #157961 Started to implement a bit panel for non-arithmetic precedence mode. It's automatically displayed when in Scientific mode, and active when integers (upto 64 bit) are being displayed. It allows you to toggled individual bits in the current display. -------------------------------------------------------------------------- * From comment #6 e/ Bug #323722 Operations like Ctrm need an explicit "=" to actually perform them. The gcalctool documentation should mention this is an obvious place. -------------------------------------------------------------------------- * From comment #7 f/ Bug #323149 Gcalctool now uses the Unicode symbols for division, multiplication, plus/minus, minus and square root. Any screenshots that show these symbols are going to be incorrect. -------------------------------------------------------------------------- * From comment #8 g/ Bug #328524 The documentation for operations like "square root" is incorrect when the user is in arithmetic operator precedence mode. In order to do the square root of 5, the actual sequence of commands that they have to enter is: Sqrt( 5 ) = There are probably several other similar operations that need to be formatted this way. -------------------------------------------------------------------------- * From comment #9 h/ The documentation for Clear Entry and Clear could be better. For example, Clear Entry is only now appropriate when "Use Arithmetic Operator Precedence" mode is not checked. See bug #344691 for more information. -------------------------------------------------------------------------- * From comment #11 i/ From bug #348765: Documentation Section: (Usage) 3.5.11.?To Use Functions 3. Click on the Value field, then enter the new value. Use the keyboard shortcuts to invoke a Calculator button. For example, enter 90K to calculate sine(90). Correct version: A couple of simple working examples. A Farenheit to Celcius conversion example might be nice, if possible. Can the function use the number already on the display or is it not really a function so it can only hold a constant? Other information: Even though I'm not using the most recent version, I didn't see a bug report in bugzilla and I couldn't find the change in the changelog so I'm posting this bug. The help file says you should be able to create a function, that takes the sin of 90 degrees, by entering 90K in the value field of the Edit Functions dialog box. It doesn't seem to work. Only simple expressions such as 2+3*4= gave results. It took a lot of trial and error to figure out how to get it to give me anything but a malformed function error. While the function syntax seems obvious in hindsight, I kept trying various things like standard spreadsheet notation =2+3*4 and plain old 2+3*4 Is there any way to include the display value so that the user functions are actually functions and not just constant expressions? I'm running Ubuntu 6.06 -------------------------------------------------------------------------- * From comment #14 The operation of % operator has changed. It's now same as dividing the number by 100 (= one percent of the original number). --- Example: non-arithmetic precedence mode 5 % Display now shows 0.05 --- Example: arithmetic precedence mode Calculating expression "5%" yeilds 0.05. -------------------------------------------------------------------------- * From comment #15 The bitcalculating extension is now available in both arithmetic operator precedence mode and non-arithmetic operator precedence mode. It's no longer always displayed . There is a new option in the View menu, that if checked, with show this extension. --------------------------------------------------------------------------
So that interested parties can get traction with this bug, I plan to open individual bite-size bugs for each of the 17 documentation bugs listed in the last comment, and then close out this one. More in a few minutes...
Individual bugs have now been filed. These are: Bug #367712 - [doc] Need to document how to enter scientific number s w... Bug #367715 - [doc] Update doc to mention saving of memory registers. Bug #367718 - [doc] Documentation change needed for View->Memory Regist... Bug #367720 - [doc] Documentation change needed for keyboard shortcuts ... Bug #367722 - [doc] Update documentation for Xor and x^y operations. Bug #367723 - [doc] Update documentation for Changing Modes Clears Calc... Bug #367725 - [doc] Update documentation for the Memory Register Window. Bug #367728 - [doc] Update documentation for Mod (Modulus Division) ope... Bug #367729 - [doc] Update documentation for the "useless" cursor in ca... Bug #367731 - [doc] Update documentation for bit calculating extension. Bug #367735 - [doc] Update documentation for Ctrm operation. Bug #367737 - [doc] Documentation screenshots need to be updated. Bug #367738 - [doc] Square root documentation needs to be updated. Bug #367740 - [doc] Documentation for Clear Entry and Clear could be be... Bug #367750 - [doc] "To Use Functions" suggested documentation changes. Bug #367754 - [doc] Update documentation for % operator. Closing this one out.