The &kformula; Handbook

Git commit dd8eae2910af623fe195ea6eb556dfe855d96872 by Thomas Zander Pushed by zander into branch master Move the docs from koffice to this repo M +1 -0 CMakeLists.txt A +4 -0 doc/CMakeLists.txt [License: UNKNOWN] A +1246 -0 doc/index.docbook [License: UNKNOWN] http://commits.kde.org/f7ad80b1/dd8eae2910af623fe195ea6eb556dfe855d96872 diff --git a/CMakeLists.txt b/CMakeLists.txt index ba50b84..c9897a9 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -9,4 +9,5 @@ include_directories(${KDE4_INCLUDES} ${QT_INCLUDES} ${KOFFICELIBS_INCLUDE_DIR}) add_subdirectory(kformula) add_subdirectory(filters) +add_subdirectory(doc) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000..0df9c9a --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,4 @@ +########### install files ############### +# +# +kde4_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en) diff --git a/doc/ambiguous-string.png b/doc/ambiguous-string.png new file mode 100644 index 0000000..3627615 Binary files /dev/null and b/doc/ambiguous-string.png differ diff --git a/doc/correct_index_location.png b/doc/correct_index_location.png new file mode 100644 index 0000000..7b97a6f Binary files /dev/null and b/doc/correct_index_location.png differ diff --git a/doc/definite_integral.png b/doc/definite_integral.png new file mode 100644 index 0000000..881e862 Binary files /dev/null and b/doc/definite_integral.png differ diff --git a/doc/file-toolbar.png b/doc/file-toolbar.png new file mode 100644 index 0000000..04a64d4 Binary files /dev/null and b/doc/file-toolbar.png differ diff --git a/doc/file-toolbar2.png b/doc/file-toolbar2.png new file mode 100644 index 0000000..65e6dda Binary files /dev/null and b/doc/file-toolbar2.png differ diff --git a/doc/green1.png b/doc/green1.png new file mode 100644 index 0000000..db87087 Binary files /dev/null and b/doc/green1.png differ diff --git a/doc/green2.png b/doc/green2.png new file mode 100644 index 0000000..efb7c5e Binary files /dev/null and b/doc/green2.png differ diff --git a/doc/greens.png b/doc/greens.png new file mode 100644 index 0000000..a534983 Binary files /dev/null and b/doc/greens.png differ diff --git a/doc/incorrect_index_location.png b/doc/incorrect_index_location.png new file mode 100644 index 0000000..771d75c Binary files /dev/null and b/doc/incorrect_index_location.png differ diff --git a/doc/index.docbook b/doc/index.docbook new file mode 100644 index 0000000..ce02247 --- /dev/null +++ b/doc/index.docbook @@ -0,0 +1,1246 @@ + + + + + +]> + + + + +The &kformula; Handbook + + + + +Jonathan +Drews +

&Jonathan.Drews.mail;

+ + +Anne-Marie +Mahfouf +

&Anne-Marie.Mahfouf.mail;

+ + +Alfredo +Beaumont Sainz +

alfredo.beaumont@gmail.com

+ + +Ulrich +Küttler +Developer + + + + + +2002 +&Jonathan.Drews; + + +2005 +&Anne-Marie.Mahfouf; + + +2006 +Alfredo Beaumont Sainz + +&FDLNotice; + +2006-09-09 +1.5.90 + + + +&kformula; is used to layout formulas. + + + + + +KDE +KOffice +kformula +formula + + + + + +Introduction +&kformula; is used to write formulas. It doesn't evaluate +anything. All it does is print them. +&kformula; was designed for your editing pleasure. It makes it +delightful to enter Greek letters, fractions and all the stuff that +makes a formula look like a formula. +But most of the time you won't want to use &kformula; itself. +Instead you might choose to use it from within &kword; or any other +&koffice; application. That is &kformula; is not a useful application +on its own but an extension to all the other &koffice; applications +you've fallen in love with. + +Where ever &kformula; gets embedded, it will +behave the same. + + + + +Basics +A new (empty) &kformula; document looks like a small blue square. +This square stands for the central idea of &kformula;. It represents an +empty list. The idea of &kformula; is to have different elements +arranged in lists. An element in this respect might be a single char +or a root symbol or something like that. The lists are put together so +that they form a formula. That is there are lists for indexes, lower +and upper bounds and so on. And of course there is the main +list, which we've already seen. + +Writing a formula means to fill the empty list with letters, +figures and mathematical symbols. That is straightforward: use your +keyboard. As soon as you type something the empty +symbol will vanish and you will see whatever you have inserted +instead. New characters are always put at the current cursor +position. + +There is a toolbar called Add that allows +you to create more complex elements. There are indices, fractions, +roots and matrices to name a few. All these elements +consist of at least one list, you can move the cursor into and insert +new items. + + + + +Using &kformula; + Below is a typical formula entry in &kformula;. To enter the partial +derivatives and Greek letters click on the symbol combo box, on the +right, and select the appropriate symbol. The symbol combo box, in the figure +below, has the word +Cap on it. Click on the return key symbol to the right of it, +to enter a symbol. + +Screenshot of &kformula; + + + + + + Screenshot of &kformula; + + + + + The Greens formula above can be printed to a &PostScript; +file. To do that choose FilePrint + and configure print as shown below: + + +Here's a screenshot of Greens Formula in &kformula; + + + + +Here's a screenshot of Greens Formula in &kformula; + + + + +Here is what the resulting &PostScript; file should look +like: + + +Here is the &PostScript; output from &kformula; + + + + + + + + +More &kformula; features + +More on formulas +To enter matrices, click on the [ ] and then click +on the matrix symbol + + . +You can move from matrix element to matrix element using the arrow +keys Right arrow, Up arrow, +Down arrow and Left arrow. An example matrix +is shown below. + + +Here is the resulting matrix; + + + + + + + + + + +Command Reference + + +The Main &kformula; Window + + +The <guimenu>File</guimenu> Menu + + + + + +&Ctrl;N + +File +New + +Creates a new &kformula; +document. + + + + + +&Ctrl;O + +File +Open... + +Opens a previously saved +document. + + + + +File +Open Recent + +Displays a selection of recently opened documents. + + + + + +&Ctrl;S + +File +Save + +Saves the document. + + + + +File +Save As... + +Saves the document with a name you provide. + + + + +File +Reload + +Reloads the more recently opened document. + + + + +File +Import + +Imports formulas from other formats. + + + + +File +Export + +Exports the current document in another format. + + + + +File +Mail... + +Invokes &kmail; so you can email the file. +The file is already attached to the email. + + + + + +&Ctrl;P + +File +Print... + +Prints the document. + + + + +File +Print Preview... + +Shows how the printed document will appear. + + + + +File +Document Information + +Provides a dialog box where you can enter your name, +email address and a short description about the document. + + + + + +&Ctrl;W + +File +Close + +Closes the current document. + + + + + +&Ctrl;Q + +File +Quit + +Quits &kformula;. + + + + + + +The <guimenu>Edit</guimenu> Menu + + + + + +&Ctrl;Z + +Edit +Undo + +Undoes an action. You can revert to the state that existed +before your last change. + + + + + +&Ctrl; &Shift; Z + +Edit +Redo + +Undoes an undo. Reverse the action of Undo. This will restore the change +you originally made. + + + + + +&Ctrl;X + +Edit +Cut + +Cuts a highlighted piece of text from the &kformula; screen. + + + + + +&Ctrl;C + +Edit +Copy + +Copies a highlighted piece of text from the &kformula; screen. + + + + + +&Ctrl;V + +Edit +Paste + +Pastes the text you selected with Cut or Copy to the &kformula; screen. + + + + + +&Ctrl;A + +Edit +Select All + +Highlights all the text in the &kformula; screen for +either Cut or Copy. + + + + + +&Ctrl;R + +Edit +Remove Enclosing Element + +Removes enclosing braces, brackets or absolute value bars. +This action takes place on the braces just outside the cursor. + + + + + +&Ctrl;G + +Edit +Convert to Greek + +Converts a Latin character to a Greek symbol. + + + + +Edit +Edit Formula String... + +Brings up an editor where you can edit the existing formula. + + + + +See the Advanced editing +section for details. + + + + +The <guimenu>Element</guimenu> Menu + + + + + +Element +Add +Add Root + +Inserts the square root. + + + + +Element +Add +Add Fraction + +Inserts a fraction. + + + + +Element +Add +Add Bracket + +Inserts a pair of brackets, &ie; ( ). You can also just +type ( to insert a pair of brackets. + + + + +Element +Add +Add Integral + +Inserts the integral sign. + + + + +Element +Add +Add Sum + +Inserts the summation sign. +(sigma). + + + + +Element +Add +Add Product + +Inserts the product sign. + + + + +Element +Add +Add Matrix... + +Inserts a matrix. A dialog box pops up, with the default size being 3x3. +You can specify the number of rows and columns in this box. + + + + +Element +Add +Add 1x2 Matrix + +Inserts a two rowed column vector. + + + + +Element +Add +Add Overline + +Inserts an overline in this box. + + + + +Element +Add +Add Underline + +Inserts an underline in this box. + + + + +Element +Add +Add Multiline + +Inserts a new line each time you type Enter in the square. + + + + + +&Ctrl;U + +Element +Add +Add Upper Index + +Adds an upper index like so: + + . + + + + + +&Ctrl;L + +Element +Add +Add Lower Index + +Adds a lower index: + + . + See the Definite Integrals and +Indices section for details about indices. + + + + + +Element +Add +Add Negative Thin Space + +Inserts a small reduced space, here between the o and the e: + + . + + + + +Element +Add +Add Thin Space + +Inserts a small space. + + + + +Element +Add +Add Medium Space + +Inserts a space that is one and a half times wider. + + + + + +Element +Add +Add Thick Space + +Inserts a double space. + + + + +Element +Add +Add Quad Space + +Inserts a quadruple wide space. + + + + +Element +Matrix +Insert Column + +Inserts a column in an existing matrix. The column is inserted where the cursor is at. + + + + +Element +Matrix +Append Column + +Appends a column to an existing matrix. The column is appended on the right. + + + + +Element +Matrix +Remove Column + +Removes a column from an existing matrix. Removal occurs where the cursor is positioned. + + + + +Element +Matrix +Insert Row + +Inserts a row in an existing matrix. The row is inserted where the cursor is at. + + + + +Element +Matrix +Append Row + +Appends a row to an existing matrix. The row is appended on the bottom. + + + + +Element +Matrix +Remove Row + +Removes a row from an existing matrix. Removal occurs where the cursor is positioned. + + + + +Element +Size + +Allows to set the size of the font (from 6 to 72). + + + + +Element +Left Delimiter + +Allows insertion of various delimiters &ie; (, {, and +[. + + + + +Element +Right Delimiter + +Allows insertion of various delimiters &ie; ), }, and +]. + + + + + +&Ctrl;I + +Element +Insert Symbol + +Inserts the symbol, selected in the symbol +toolbar. + + + + + + +The <guimenu>Settings</guimenu> Menu +Here you can choose how &kformula; is configured. + You can select the toolbars you want displayed or the type of fonts to be +used. + + + + + +Settings +Toolbars +File (KFormula) + +Toggles the toolbar that contains clickable icons for +new, open and save files. +Print and print preview are here also. + + + + +Settings +Toolbars +Edit (KFormula) + +Toggles the edit toolbar. Here are clickable icons for +cut and paste as well as Undo and Redo. + + + + +Settings +Toolbars +Add (KFormula) + +This toolbar contains all the mathematical elements such +as Sum, Integral, Exponent &etc; + + + + +Settings +Toolbars +Font (KFormula) + +This toolbar contains the font settings (size, bold, italic, &etc;). + + + + +Settings +Toolbars +Symbol (KFormula) + +This toggles the combo box that contains Del, the +partial derivative symbol, limit arrows, +boolean operators and other mathematical symbols. + + + + + +Settings +Toolbars +Matrix (KFormula) + +This toggles the matrix toolbar. It contains clickable +icons that pertain to matrix creation and editing. + + + + +Settings +Syntax Highlighting + +Checking this item determines if the numbers will be +displayed in color. + + + + + + + + + +Configuring Shortcuts + +The +SettingsConfigure Shortcuts... +allows you to specify shortcuts. + + +Below is an example of how to configure a shortcut for a +print preview. + + + +Picture of shortcut dialog + + + + + + + + + +Click on Custom. + + + +Next click on the button Advanced >> and then Primary shortcut:. + + + +Do &Ctrl;Space +and the dialog should disappear. The shortcut is now entered. + + + + +Picture of shortcut dialog + + + + + + + +Pressing the keys &Ctrl;Space +now displays the print preview. + + + + + +Configuring Toolbars +The +SettingsConfigure Toolbars... +is used to add additional buttons to the toolbars. + + +Picture of toolbars dialog + + + + + + + + + + + +To add a button to the File toolbar, + + + +Picture of toolbars dialog + + + + + + + + make sure File + <&koffice;> is displayed in the top combo box. + + + +Click on one of the items in the left hand pane. This item will now be +highlighted to show that it has been selected. + + + +Next click on the Right arrow button to place it in +the right pane. + + + +Click on Apply and then +click on OK. + + + + +The new Item should be in the toolbar. + + + + + + + + + + +Configuring &kformula; +The +SettingsConfigure +&kformula;... is where the font sizes and font styles are +selected. + + + +The Formula section allows you to select fonts +and font highlight colors. + + + + + + + +The <guimenu>Help</guimenu> Menu + + + +Help +Tip of the Day + +Opens the Tip of the Day dialog which displays a random tip about &kformula;. + + +&help.menu.documentation; + + + + + + + +Advanced Editing + + +Name insertion + +A special feature is the name insertion. The blue square you +type into is actual a list. Furthermore, that list can contain other +lists. When you type a backslash (\) you get a new +empty list right away. But this one is special. It uses a different +font and is meant to insert things like function names. There is, +however, a second idea here. Your keyboard only has a limited number of keys. +The wealth of mathematical symbols on the other side is overwhelming. To get one +of those you can type its name and press the space bar afterwards. The name you +typed will be replaced by the symbol then. In this context, the +Space bar means get out of here, that +is move the cursor to the containing list. The cursor will be +positioned at the end of what you just entered but will also enclose part of the original +formula, after pressing the space bar. + + +Another thing you might want to insert are spaces. We all know, +printing formulae is all about the right spacing. And you can do just +that using a name list. + +Inside the blue square do: \,SPACE to get a small space. + + +Do: \<Space to get a medium space. + + +Do: \;Space to get a thick space. + + +Do: \ quad Space to get +a quadruple wide space. + + +In the same way, specific mathematical symbols can be inserted. +\ oint Space inserts +the path integral about a closed contour. Below is the result of +\ oint Space: + +Picture of path integral + + + + + + + + + +Editing Formulas + +The +Edit +Edit Formula String + allows the user to edit the ASCII formulas that have been copied from other applications, +such as Scilab, and transform them directly into mathematical type. An example will make this clear. Below is a screenshot of INRIA Scilab. + + + +Scilab picture + + + + + + + Copy and paste the text beginning with x*sin(30*x) into the formula editor as +shown below: + + +Scilab formula edit picture + + + + + + + +If you click on OK, the editor will complain about aborted parsing. It cannot +recognize one of the symbols in the formula. The displayed formula would show that the Pi symbol is +not correctly rendered. This means that the % must be deleted. Do this and &kformula; will +render the mathematical font properly, as shown below. + + +Scilab formula rendered in &kformula; + + + + + + + + The formula editor will accept most C language mathematical expressions, like the formulas from a +Runge-Kutta program below: +void derives(float x, float y[], float dydx[]) +{ + dydx[1] = y[2]; + dydx[2] = -0.8*x*y[2] - sin(x)*y[1]; +} + +Here dydx[1] is the first order derivative and dydx[2] is the second order +derivative. After copying the formula, you will have to edit the derivatives with &kformula;. Here is how it is done. +First copy and paste the bottom expression into the formula editor. + + +Runge-Kutta in editor; + + + + + + + +Next remove the [ ], leaving just y's. + + +Runge-Kutta edited + + + + + + + +Now click OK and place the cursor by a y and delete it. Insert the appropriate symbols as +shown below. + + +Runge-Kutta in &kformula; + + + + + + + +Not every expression that &kformula; is capable of translates into a valid C expression. For example the +superscript expression: + + +Superscript in &kformula; + + + + + + + +is displayed as ()**(), which is not a valid C statement for exponentiation. Similarly the 1 by 2 +matrix displays as ()/(). This is not a valid array in C. + + + + +Definite Integrals and Indices + +Definite Integrals + A definite integral is made by using &Ctrl;U for the upper limit +of integration and &Ctrl;L +for the lower limit of integration. + + + +definite integral + + + + + + +Reposition the cursor in front of the integral after making the +first of the limits. + + + +Positioning Indices + +The upper or lower index can be positioned by highlighting the desired +text. In this example, an arrow is needed above the P, in dP. Using &Ctrl;U places the desired vector +symbol in the wrong place; namely above the d. + + + + + +The problem is solved by + highlighting only the P in + + and then entering &Ctrl;U. Here is the correct + result. + + + + + + + + + + + +Credits and Licenses + +&kformula; Copyright by The &kformula; Team + + +&kformula; Developers (Alphabetically) +Alfredo Beaumont Sainz alfredo.beaumont@gmail.com +Ulrich Küttler +Andrea Rizzi + + +Documentation copyright 2002 &Jonathan.Drews; +&Jonathan.Drews.mail; + +Documentation copyright 2005 &Anne-Marie.Mahfouf; +&Anne-Marie.Mahfouf.mail; + +Documentation copyright 2006 Alfredo Beaumont Sainz +alfredo.beaumont@gmail.com + +&underFDL; +&underGPL; + + + + +Installation + + +How to obtain &kformula; + +&install.intro.documentation; + + + + +Requirements + + +&kformula; is part of &koffice; +on The &kformula; home +page +You must have &koffice; installed. &kformula; will not work without the rest of +&koffice; + + + + + +Compilation and Installation + + +&install.compile.documentation; + + + + + +&documentation.index; + + + + + + + + + + diff --git a/doc/index_smear.png b/doc/index_smear.png new file mode 100644 index 0000000..3b604a4 Binary files /dev/null and b/doc/index_smear.png differ diff --git a/doc/kfontinst1.png b/doc/kfontinst1.png new file mode 100644 index 0000000..ad703c4 Binary files /dev/null and b/doc/kfontinst1.png differ diff --git a/doc/kfontinst2.png b/doc/kfontinst2.png new file mode 100644 index 0000000..072efa2 Binary files /dev/null and b/doc/kfontinst2.png differ diff --git a/doc/kfontinst3.png b/doc/kfontinst3.png new file mode 100644 index 0000000..2b55544 Binary files /dev/null and b/doc/kfontinst3.png differ diff --git a/doc/kfontinst4.png b/doc/kfontinst4.png new file mode 100644 index 0000000..4178056 Binary files /dev/null and b/doc/kfontinst4.png differ diff --git a/doc/kfontinst5.png b/doc/kfontinst5.png new file mode 100644 index 0000000..ce630b3 Binary files /dev/null and b/doc/kfontinst5.png differ diff --git a/doc/kfontinst6.png b/doc/kfontinst6.png new file mode 100644 index 0000000..efa17e7 Binary files /dev/null and b/doc/kfontinst6.png differ diff --git a/doc/lower-index.png b/doc/lower-index.png new file mode 100644 index 0000000..fb0f7a2 Binary files /dev/null and b/doc/lower-index.png differ diff --git a/doc/matrix-view.png b/doc/matrix-view.png new file mode 100644 index 0000000..379a52b Binary files /dev/null and b/doc/matrix-view.png differ diff --git a/doc/matrix.png b/doc/matrix.png new file mode 100644 index 0000000..c713eeb Binary files /dev/null and b/doc/matrix.png differ diff --git a/doc/negative_thin_space.png b/doc/negative_thin_space.png new file mode 100644 index 0000000..a2a83ba Binary files /dev/null and b/doc/negative_thin_space.png differ diff --git a/doc/path-integral.png b/doc/path-integral.png new file mode 100644 index 0000000..3585f88 Binary files /dev/null and b/doc/path-integral.png differ diff --git a/doc/rk-edit0.png b/doc/rk-edit0.png new file mode 100644 index 0000000..452119b Binary files /dev/null and b/doc/rk-edit0.png differ diff --git a/doc/rk-edit1.png b/doc/rk-edit1.png new file mode 100644 index 0000000..5e16200 Binary files /dev/null and b/doc/rk-edit1.png differ diff --git a/doc/rk-edit2.png b/doc/rk-edit2.png new file mode 100644 index 0000000..3f0327f Binary files /dev/null and b/doc/rk-edit2.png differ diff --git a/doc/scilab-edit.png b/doc/scilab-edit.png new file mode 100644 index 0000000..1e03578 Binary files /dev/null and b/doc/scilab-edit.png differ diff --git a/doc/scilab.png b/doc/scilab.png new file mode 100644 index 0000000..a93a4e0 Binary files /dev/null and b/doc/scilab.png differ diff --git a/doc/shortcut0.png b/doc/shortcut0.png new file mode 100644 index 0000000..03eb6e7 Binary files /dev/null and b/doc/shortcut0.png differ diff --git a/doc/shortcut1.png b/doc/shortcut1.png new file mode 100644 index 0000000..f2c077c Binary files /dev/null and b/doc/shortcut1.png differ diff --git a/doc/sin.png b/doc/sin.png new file mode 100644 index 0000000..8f514d6 Binary files /dev/null and b/doc/sin.png differ diff --git a/doc/toolbars.png b/doc/toolbars.png new file mode 100644 index 0000000..7bb0579 Binary files /dev/null and b/doc/toolbars.png differ diff --git a/doc/upper-index.png b/doc/upper-index.png new file mode 100644 index 0000000..2e70dd8 Binary files /dev/null and b/doc/upper-index.png differ