From fbadfa5f41dca9e13ae65198f5073dd85633d7a8 Mon Sep 17 00:00:00 2001 From: gregory guy Date: Sat, 8 Aug 2020 17:39:17 +0200 Subject: Fix help page install location. Rework of the help page, README and INSTALL files. Signed-off-by: gregory guy --- doc/en/index.docbook | 291 ++++++++++++++++++++++++++++++++++++++++++ doc/mathemagics/index.docbook | 281 ---------------------------------------- 2 files changed, 291 insertions(+), 281 deletions(-) create mode 100644 doc/en/index.docbook delete mode 100644 doc/mathemagics/index.docbook (limited to 'doc') diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..ed37e23 --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,291 @@ + + + + + +]> + + + +The &mathemagics; Handbook + + + +Jason +Katz-Brown + +
jason@katzbrown.com
+ + + + + +2002 +Jason Katz-Brown + + +&FDLNotice; + +2002-05-25 +1.0 + +&mathemagics; is a scientific RPN calculator for &tde;. + + +KDE +Mathemagics +calculator +RPN + + + + +Introduction + +This document describes &mathemagics; version 1.0. + +&mathemagics; is a full-featured scientific calculator. It uses Reverse Polish Notation, or RPN. &mathemagics; can store and use user-defined functions and variables, and comes with large number of built-in functions. + +Have fun with &mathemagics;! + + + + + +Usage + +This chapter describes usage of &mathemagics;'s features. + + +Reverse Polish Notation (RPN) + +Most calculators use an algebraic system of input. In this system, one enters arguments to a function after entering the function itself. For example, to add 2 and 2, one would enter 2 + 2. + +&mathemagics; uses the Reverse Polish Notation system for input. With RPN, arguments are entered before the function. So to add 2 and 2, one would enter "2 2 +". + +RPN is based around the stack. The stack stores numbers. When you execute a function, like x^y, the operation takes its arguments from the stack. If there are not enough numbers on the stack, &mathemagics; will tell you. In &mathemagics;, the stack is shown as a pile of line-entries. The first stack level is on the very bottom. + + + +Modifying the Stack + +To enter something onto the stack, type it into the line-entry on the main toolbar. Then press the Return key. The number you entered will be pushed onto the stack. You can enter multiple numbers onto the stack at once by separating them with spaces. + +To modify numbers already on the stack, click in the line-entry that represents the stack level. Then modify the displayed number by typing the new number you want into the line-entry. Finally, press return and the number will be saved onto that stack level. If you ever want to get rid of any stack changes you've made in this way, Choose the Edit->Revert Stack Changes. + +To drop a stack level, replace the text in its line-entry with nothing. Then press return as you normall would in that line-entry. + +To roll values on the stack upwards from a level, click the button to the right of the stack level you want to roll from. If the Inv button is checked, this will roll the values down; otherwise, it will roll them up. + + + +Using Functions + +&mathemagics; comes with many built-in functions. You can access most of them from the Operations menu. The functions take their arguments from the numbers on the stack. + +Alternatively, you can type the name of the function directly into the main line-entry. + + + + +Variables + +Variable syntax in &mathemagics; are slightly tricky to use. + + + +Assigning Variables + +2 $example= will create the variable example and assign the value 2 to it. +2 level $example= will create the variable example and assign the value of the second stack level to it. +So, to assign the value on stack level 1 to a variable, write the variable name (prefaced by '$') followed immediately by '='. + + + +Using Variables + +To push the variable example on the stack, simply enter $example. In this way, using variables is the same as using any other number in equations. If you enter a variable that has no value assigned to it, nothing is pushed onto the stack. + + + + + + + + +Scripting + +&mathemagics; can be scripted by defining your own functions. + + +Defining Your Own Functions + +You can define your own functions in &mathemagics;. + + + +Creating Functions + +example=2 * will create the function example. As defined, this function multiplies the bottom stack level by two. Functions can use any variables, and even call other functions + + + +Using Functions + +To use the function example, simply enter example. The function will be evaluated. + + + + + + + +Useful Functions for Scripting + +There are a few useful built-in functions that you can use when scripting &mathemagics;. Of course, all other built-in functions are also available for use. + + + +FunctionArgumentsResult + + + +reqargs +1: number of required arguments +stops function execution if stack does not have enough arguments + +stopif +1: whether or not to stop (1 for true ($true), anything else for false ($false)) +stop function execution if specified + +at +1: level number (0-indexed) +drops stack level 1; pushes value of stack level onto stack + +level +1: level number (1-indexed) +drops stack level 1; pushes value of stack level onto stack + + + + + + + + + +Notes on Specific Functions + +Some built-in functions in &mathemagics; require extra explanation. This follows. + + +Left Shift (lsh) and Right Shift (rsh) + + +lsh left shifts the integer part of the displayed value (multiplies it by 2) n times, where n is the next input number, and gives an integer result: +10 3 lsh gives 80 (10 multiplied by 2 three times). +10.345 3 lsh also gives 80. + + + +rsh right shifts the value (performs an integer divide by 2) n times. 16 2 rsh gives 4 (16 divided by 2 twice). 16.999 2 rsh also gives 4. + + + + + + + +And, Or and XOr + +The and, or and xor functions perform bitwise logical operations and therefore appear more meaningful if the Base is set to Hexadecimal, Octal or Binary rather than Decmal. In the following examples Base is set to Binary. + + + +and does a logical AND. +101 110 and gives +100 + + + +or does the logical OR. +101 110 or gives +111 + + + +xor performs the logical +XOR (exclusive OR) operation. +101 110 xor gives +11 + + + + + + + + + +Questions and Answers + + + + +How do I get pi=3.1415926...? +There is a predefined variable pi. To use it, enter $pi. + + + +How do I get e, the Euler number? +There is a predefined variable e. To use it, enter $e. + + + + + + +Credits and License + +&mathemagics; Program copyright 2001-2002 Jason Katz-Brown jason@katzbrown.com. + +Documentation copyright 2002: + +Jason Katz-Brown jason@katzbrown.com + + +&underFDL; + + + + + +Installation + +&mathemagics; is part of the &tde; project. For more details about &tde; visit http://trinitydesktop.org. + +&mathemagics;'s website is +https://mirror.git.trinitydesktop.org/gitea/TDE/mathemagics + + +Compilation and Installation + + +In order to compile and install &mathemagics; on your system, type the following in the base directory; distribution: + +% mkdir -p build +% cd build +% cmake ../ +% make +% make install + + + +Since &mathemagics; uses cmake you should have not trouble compiling it. Default options for cmake build are available in the INSTALL file. + + + + + diff --git a/doc/mathemagics/index.docbook b/doc/mathemagics/index.docbook deleted file mode 100644 index ff1092c..0000000 --- a/doc/mathemagics/index.docbook +++ /dev/null @@ -1,281 +0,0 @@ - - - - - -]> - - - -The &mathemagics; Handbook - - - -Jason -Katz-Brown - -
jason@katzbrown.com
- - - - - -2002 -Jason Katz-Brown - - -&FDLNotice; - -2002-05-25 -1.0 - -&mathemagics; is a scientific RPN calculator for &kde;. - - -KDE -Mathemagics -calculator -RPN - - - - -Introduction - -This document describes &mathemagics; version 1.0. - -&mathemagics; is a full-featured scientific calculator. It uses Reverse Polish Notation, or RPN. &mathemagics; can store and use user-defined functions and variables, and comes with large number of built-in functions. - -Have fun with &mathemagics;! - - - - - -Usage - -This chapter describes usage of &mathemagics;'s features. - - -Reverse Polish Notation (RPN) - -Most calculators use an algebraic system of input. In this system, one enters arguments to a function after entering the function itself. For example, to add 2 and 2, one would enter 2 + 2. - -&mathemagics; uses the Reverse Polish Notation system for input. With RPN, arguments are entered before the function. So to add 2 and 2, one would enter "2 2 +". - -RPN is based around the stack. The stack stores numbers. When you execute a function, like x^y, the operation takes its arguments from the stack. If there are not enough numbers on the stack, &mathemagics; will tell you. In &mathemagics;, the stack is shown as a pile of line-entries. The first stack level is on the very bottom. - - - -Modifying the Stack - -To enter something onto the stack, type it into the line-entry on the main toolbar. Then press the Return key. The number you entered will be pushed onto the stack. You can enter multiple numbers onto the stack at once by separating them with spaces. - -To modify numbers already on the stack, click in the line-entry that represents the stack level. Then modify the displayed number by typing the new number you want into the line-entry. Finally, press return and the number will be saved onto that stack level. If you ever want to get rid of any stack changes you've made in this way, Choose the Edit->Revert Stack Changes. - -To drop a stack level, replace the text in its line-entry with nothing. Then press return as you normall would in that line-entry. - -To roll values on the stack upwards from a level, click the button to the right of the stack level you want to roll from. If the Inv button is checked, this will roll the values down; otherwise, it will roll them up. - - - -Using Functions - -&mathemagics; comes with many built-in functions. You can access most of them from the Operations menu. The functions take their arguments from the numbers on the stack. - -Alternatively, you can type the name of the function directly into the main line-entry. - - - - -Variables - -Variable syntax in &mathemagics; are slightly tricky to use. - - - -Assigning Variables - -2 $example= will create the variable example and assign the value 2 to it. -2 level $example= will create the variable example and assign the value of the second stack level to it. -So, to assign the value on stack level 1 to a variable, write the variable name (prefaced by '$') followed immediately by '='. - - - -Using Variables - -To push the variable example on the stack, simply enter $example. In this way, using variables is the same as using any other number in equations. If you enter a variable that has no value assigned to it, nothing is pushed onto the stack. - - - - - - - - -Scripting - -&mathemagics; can be scripted by defining your own functions. - - -Defining Your Own Functions - -You can define your own functions in &mathemagics;. - - - -Creating Functions - -example=2 * will create the function example. As defined, this function multiplies the bottom stack level by two. Functions can use any variables, and even call other functions - - - -Using Functions - -To use the function example, simply enter example. The function will be evaluated. - - - - - - - -Useful Functions for Scripting - -There are a few useful built-in functions that you can use when scripting &mathemagics;. Of course, all other built-in functions are also available for use. - - - -FunctionArgumentsResult - - - -reqargs -1: number of required arguments -stops function execution if stack does not have enough arguments - -stopif -1: whether or not to stop (1 for true ($true), anything else for false ($false)) -stop function execution if specified - -at -1: level number (0-indexed) -drops stack level 1; pushes value of stack level onto stack - -level -1: level number (1-indexed) -drops stack level 1; pushes value of stack level onto stack - - - - - - - - - -Notes on Specific Functions - -Some built-in functions in &mathemagics; require extra explanation. This follows. - - -Left Shift (lsh) and Right Shift (rsh) - - -lsh left shifts the integer part of the displayed value (multiplies it by 2) n times, where n is the next input number, and gives an integer result: -10 3 lsh gives 80 (10 multiplied by 2 three times). -10.345 3 lsh also gives 80. - - - -rsh right shifts the value (performs an integer divide by 2) n times. 16 2 rsh gives 4 (16 divided by 2 twice). 16.999 2 rsh also gives 4. - - - - - - - -And, Or and XOr - -The and, or and xor functions perform bitwise logical operations and therefore appear more meaningful if the Base is set to Hexadecimal, Octal or Binary rather than Decmal. In the following examples Base is set to Binary. - - - -and does a logical AND. -101 110 and gives -100 - - - -or does the logical OR. -101 110 or gives -111 - - - -xor performs the logical -XOR (exclusive OR) operation. -101 110 xor gives -11 - - - - - - - - - -Questions and Answers - - - - -How do I get pi=3.1415926...? -There is a predefined variable pi. To use it, enter $pi. - - - -How do I get e, the Euler number? -There is a predefined variable e. To use it, enter $e. - - - - - - -Credits and License - -&mathemagics; Program copyright 2001-2002 Jason Katz-Brown jason@katzbrown.com. - -Documentation copyright 2002: - -Jason Katz-Brown jason@katzbrown.com - - -&underFDL; - - - - - -Installation - -&mathemagics; is part of the &package; package within the &kde; project. For more details about &kde; visit http://www.kde.org. - -&mathemagics;'s website is -http://katzbrown.com/mathemagics/ - - -Compilation and Installation - -&install.intro.documentation; -&install.compile.documentation; - - - - - -- cgit v1.2.1