#LyX 2.3 created this file. For more info see http://www.lyx.org/ \lyxformat 544 \begin_document \begin_header \save_transient_properties true \origin unavailable \textclass scrartcl \begin_preamble \usepackage{tikz} \usepackage{pgffor} \end_preamble \options DIV=11 \use_default_options false \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman "newcent" "default" \font_sans "default" "default" \font_typewriter "default" "default" \font_math "auto" "auto" \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 100 \font_tt_scale 100 100 \use_microtype false \use_dash_ligatures true \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref true \pdf_title "Teapot User Guide" \pdf_author "Michael Haardt, Jörg Walter" \pdf_bookmarks true \pdf_bookmarksnumbered true \pdf_bookmarksopen true \pdf_bookmarksopenlevel 2 \pdf_breaklinks false \pdf_pdfborder true \pdf_colorlinks false \pdf_backref false \pdf_pdfusetitle true \papersize default \use_geometry false \use_package amsmath 1 \use_package amssymb 1 \use_package cancel 1 \use_package esint 1 \use_package mathdots 0 \use_package mathtools 1 \use_package mhchem 1 \use_package stackrel 1 \use_package stmaryrd 1 \use_package undertilde 1 \cite_engine basic \cite_engine_type default \biblio_style plain \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \justification true \use_refstyle 0 \use_minted 0 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \paragraph_indentation default \is_math_indent 0 \math_numbering_side default \quotes_style english \dynamic_quotes 0 \papercolumns 1 \papersides 1 \paperpagestyle fancy \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Title Teapot User Guide \end_layout \begin_layout Author Michael Haardt, Jörg Walter, Glen Whitney \end_layout \begin_layout Date \begin_inset CommandInset href LatexCommand href name " http://www.syntax-k.de/projekte/teapot" target "http://www.syntax-k.de/projekte/teapot" literal "false" \end_inset \end_layout \begin_layout Publishers \begin_inset CommandInset href LatexCommand href name "https://code.studioinfinity.org/glen/teapot-spreadsheet" target "https://code.studioinfinity.org/glen/teapot-spreadsheet" literal "false" \end_inset \end_layout \begin_layout Abstract For ages, spreadsheet programs have been closely associated with financial calculations done by typical end-users. But time has shown that there is also hacker's work which can be done with them, like calculate monitor timings for various resolutions, or produce convincing time statistics which justify the lack of documentation or the need for a budget increase to your employer. The first part of this user guide explains how the various operations of \noun on teapot \noun default are used, whereas the second part gives an introduction to spreadsheets and explains the expression evaluator and its functions and operators. \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Standard \begin_inset Newpage newpage \end_inset \end_layout \begin_layout Section Copyright, Contributors and License \end_layout \begin_layout Standard \noun on teapot \noun default (Table Editor And Planner, Or: Teapot), is copyrighted 1995–2006 by Michael Haardt, and 2009–2010 by Jörg Walter, and 2019 by Glen Whitney, and is licensed under the Gnu General Public License v3 or later. \end_layout \begin_layout Standard The implementation of clocked expressions is modelled after the description of clocked evaluation in the PhD work of Jörg Wittenberger at the University of Technology in Dresden, Germany. The trigonometric functions were inspired by Koniorczyk Mátyás. The context output format was contributed by Marko Schuetz. \end_layout \begin_layout Standard The (currently unused) message catalogs were contributed by Guido Müsch, Wim van Dorst, and Volodymyr M. Lisivka. \end_layout \begin_layout Standard This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. \end_layout \begin_layout Standard This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. \end_layout \begin_layout Standard You should have received a copy of the GNU General Public License v3 along with this program. If not, see < \begin_inset CommandInset href LatexCommand href target "http://www.gnu.org/licenses/" literal "false" \end_inset >. \end_layout \begin_layout Section Introduction to Spreadsheets \end_layout \begin_layout Subsection General Introduction \end_layout \begin_layout Standard A spreadsheet consists of cells formed by rows and columns. Additionally, in many spreadsheets you have a third dimension, which you can imagine as various layers laying on top of each other. The third dimension allows you to hide intermediate results, calculate additional results you do not want to appear in the \begin_inset Quotes eld \end_inset official \begin_inset Quotes erd \end_inset tables, keep information per time period (like 12 layers for each month in a year) while allowing you to make calculations over the entire time interval and much more. Figure \begin_inset CommandInset ref LatexCommand ref reference "fig:Three-Dimensional-Spread-Sheet" \end_inset shows the three dimensions: \end_layout \begin_layout Standard \begin_inset Float figure placement h wide false sideways false status open \begin_layout Plain Layout \align center \begin_inset ERT status open \begin_layout Plain Layout { \backslash color{white} \backslash hrule} \end_layout \begin_layout Plain Layout \end_layout \begin_layout Plain Layout \backslash begin{tikzpicture}[scale=.1,anchor=west] \end_layout \begin_layout Plain Layout \backslash foreach \backslash z in {0,2,4,6} \backslash filldraw[fill=white,ystep=1,xstep=3,shift={(0,0, \backslash z)}] (0,0) rectangle (60,10) (0,0) grid (60,10); \end_layout \begin_layout Plain Layout \backslash draw[->] (70,10,10) -- +(30,0,0) node{x}; \end_layout \begin_layout Plain Layout \backslash draw[->] (70,10,10) -- +(0,-10,0) node{y}; \end_layout \begin_layout Plain Layout \backslash draw[->] (70,10,10) -- +(0,0,-10) node{z}; \end_layout \begin_layout Plain Layout \backslash end{tikzpicture} \end_layout \begin_layout Plain Layout { \backslash color{white} \backslash hrule} \end_layout \end_inset \end_layout \begin_layout Plain Layout \begin_inset Caption Standard \begin_layout Plain Layout \begin_inset CommandInset label LatexCommand label name "fig:Three-Dimensional-Spread-Sheet" \end_inset Three-Dimensional Spread Sheet Layout \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard You can think of cells as variables, which value is the value of an associated expression. The expression may be constant, like 1.23, or it may be a function of other cell values. The advantage compared to a programmable calculator is that if you change a number, you directly see all changes in other cells caused by that. Often this allows you to get a feeling how much you may change basic sizes with still getting satisfying results without having to solve the problem analytically. \end_layout \begin_layout Standard Spreadsheets offer many editing operations in order to modify, clear, copy and move cells or blocks of cells. Besides the usual mathematical functions, there are functions which work on blocks of cells, like calculating the sum of a block or counting all non-empty elements. Further there are functions working on character strings, because most likely you also want text besides numbers. The next section will introduce you to some of these by examples. \end_layout \begin_layout Standard \noun on teapot \noun default is a traditional spreadsheet and a typical UNIX program, because it does just one thing: Calculations. It does not include any graphics functions and never will, but it allows to export data in many formats, so you can use your favourite graphics software. \end_layout \begin_layout Subsection The First Steps \end_layout \begin_layout Standard Now that you have an idea what \noun on teapot \noun default is about, it is probably a good time to take your first steps with it. This section will show you how to create and save a sheet which contains two numbers and their sum. Start the program without any arguments \begin_inset Foot status collapsed \begin_layout Plain Layout If you are using the graphical version of \noun on teapot \noun default , please see section \begin_inset CommandInset ref LatexCommand vref reference "subsec:Differences-Between-User" \end_inset . \end_layout \end_inset : \end_layout \begin_layout Quote \family typewriter teapot \end_layout \begin_layout Standard You see an empty sheet with the cell cursor being at the upper left corner. Further, the status line tells you that this cell is really empty: \end_layout \begin_layout Quote \family typewriter E @(0,0,0)= \family default \end_layout \begin_layout Standard The \family typewriter E \family default means that you can edit the sheet. A \family typewriter V \family default would mean that you could only view its contents. The meaning of \family typewriter @() \family default will be explained soon. You are now in the command mode of \noun on teapot \noun default . Press the \series bold Enter \series default key to edit this cell. A complete list of command mode operations will be given later. A prompt will appear below the status line: \end_layout \begin_layout Quote \family typewriter Cell contents: \family default \series bold 1 \series default \end_layout \begin_layout Standard Now the cell at position 0,0,0 has the integer constant 1. The status line shows you the cell contents, whereas in the sheet you see its value. Since constants are identical with their values, both are 1. Now move the cell cursor down one row and edit that cell, giving it the integer constant \family typewriter 41 \family default . \end_layout \begin_layout Standard Now that you have two numbers, move the cell cursor to cell 0,2,0 and give that cell the following contents: \end_layout \begin_layout Quote \family typewriter Cell contents: \family default \series bold @(0,0,0)+@(0,1,0) \series default \end_layout \begin_layout Standard If you were confused about the difference between contents and value of a cell, it should become more clear now: The status line shows the contents, which is the arithmetic expression to calculate the sum of two cells, whereas in the sheet you see the value of that expression: 42, which was to be expected. \family typewriter @( \family default \shape italic x \family typewriter \shape default , \family default \shape italic y \family typewriter \shape default , \family default \shape italic z \family typewriter \shape default ) \family default is a function which takes three coordinates and returns the value of the cell at the given position. \end_layout \begin_layout Standard As you can see, the arithmetic expression is not too readable. If you would move cells around, it would not even work any more. For these reasons, you can use symbolic names instead of coordinates, called labels. When used in an expression, a label is like a pointer to a cell, its data type is \emph on location \emph default . Move to cell 0,0,0 and use \series bold / \series default (slash) in command mode to get into the main menu. Depending on your screen size, you may not see all of it. In this case, move the highlighted block right (or left) to scroll through it and to see all items. Now change its label attribute: A)ttributes, L)abel: \end_layout \begin_layout Quote \family typewriter Cell label: \family default \series bold Paper \end_layout \begin_layout Standard Then go one cell down and change its label to \series bold Tapes \series default . After, move again one cell down and change the expression to: \end_layout \begin_layout Quote \family typewriter Cell contents: \family default \series bold @(Paper)+@(Tapes) \end_layout \begin_layout Standard As you see, you can call the function \family typewriter @ \family default with three integer values or with one location value. Now the expression is more understandable, at least to you. To someone else, the sheet only contained three numbers, so a little text should be added. To accomplish that, a new column needs to be inserted: B)lock, I)insert, C)olumn, W)hole column. The last menu item means that you want to insert a whole new column, not only a partial column. If you move the cursor around, you will see that everything is still fine, because you used labels. Go to cell 0,0,0 and edit it: \end_layout \begin_layout Quote \family typewriter Cell contents: \family default \series bold "Paper:" \end_layout \begin_layout Standard This is how you enter strings. A string is a data type on its own, don't confuse this with labels. If you feel like it, leave the quotes and the colon away, and you will see the difference, because the result will not be a string, but the value of the label \family typewriter Paper \family default , which is \family typewriter &(1,0,0) \family default . Now change the cells below to \series bold "Tapes:" \series default and \series bold "Result:" \series default . This is something that is understandable to others, too. \end_layout \begin_layout Standard As the last step, save your work sheet to a file: F)ile, S)ave. The native file format is Teapot ASCII, so choose that. Up to now, your sheet does not have a name, so you will be prompted for one: \end_layout \begin_layout Quote \family typewriter New file name: \family default \series bold firststep \end_layout \begin_layout Standard Unless you see an error message after, your sheet is written to a file. \end_layout \begin_layout Standard If you have come this far, quit (from the main menu) and you have successfully completed your first steps on using \noun on teapot \noun default . Now you know cells, the difference between contents and values, you learned that labels are a good thing and you can do simple cell modifications as well as saving your work. This is enough for most applications. If the capabilities described in the next section confuse you, then it is unlikely that you need them really. Just skip that section and don't worry about it. \end_layout \begin_layout Standard You may wonder what happens if you have circular dependencies, i.e. you have a cell which evaluates to its own value plus one. Well, the answer is that it depends on the order in which you create this cell. If you first give it the value 1 and after edit it to contain the expression which refers to itself plus 1, then you will find that each recalculation, like after editing other cells, will increase the value. While this may be funny, it is certainly not useful as you can not reset the cell and you have little control of its development. \end_layout \begin_layout Standard What you really want is a base value and an iterative expression along with a way to control the recalculations. \noun on teapot \noun default supports this by allowing two expressions per cell. The expressions you have used so far are the ones which evaluate to the base values. Each time you edit a cell, the whole sheet will be reset, which means that all results are recalculated using the base values. After, you can clock the sheet, which is why the iterative part is also called clocked expression. A clock is an atomic operation, which means that all cell results will be recalculated in a way that the new result will only show after the entire recalculation. \end_layout \begin_layout Standard An example will demonstrate how to make use of this feature. The notation \shape italic x \shape default -> \shape italic y \shape default means that \shape italic x \shape default is the base expression and \shape italic y \shape default is the clocked expression. Don't let this confuse you, as both are entered separately: \noun on teapot \noun default does not have an -> operator, but it displays the cell contents this way so you can easily see both expressions at once. So, give the cell a base expression of \family typewriter 1 \family default and a clocked expression of \family typewriter @(0,0,0)+1 \family default (using \series bold ESC-Enter \series default or \series bold Meta-Enter \series default ) and you will see: \end_layout \begin_layout Quote \family typewriter @(0,0,0)=1 -> @(0,0,0)+1 \end_layout \begin_layout Standard The sheet is currently in reset condition and the result is 1. Now clock it and you will see how the value increases. \end_layout \begin_layout Standard After this introductory chapter, you should be familiar with the basic concepts in spread sheets. The next chapters explain all operations available in detail. You should read them to get an overview of the possibilities offered by \noun on teapot \noun default . Finally, we will come back to using \noun on teapot \noun default by showing some common problems and their solutions. \end_layout \begin_layout Subsection \begin_inset CommandInset label LatexCommand label name "subsec:Differences-Between-User" \end_inset Differences Between User Interfaces \end_layout \begin_layout Standard \noun on teapot \noun default comes in two flavours: A mouse-and-keyboard operated graphical application and a traditional console-based program. There has been a concerted effort to ensure this manual accurately documents both flavours, but there could still be occasional inconsistencies. Note that the executable name for the graphical version of \noun on teapot \noun default is typically \family typewriter fteapot \family default , so to follow the tutorial above with the GUI version, start with that command instead of \family typewriter teapot \family default . \end_layout \begin_layout Standard Most notably, at the moment the key bindings can be fairly different in the two flavours. If something doesn't work for \family typewriter fteapot \family default as described here, check the pull-down menus, where most operations can be found. In addition to the keys it shares with the console version, the GUI variant has extended mouse and keyboard bindings that work similarly to other GUI applications. The table in the following section attempts to summarize all bindings from both variants. \end_layout \begin_layout Section Command Mode \end_layout \begin_layout Standard Right after starting \noun on teapot \noun default , you are in the command mode. Many operations from the command mode are also available from menus, but using keys is faster and some things, like moving the cell cursor, are only available through keys. Tables \begin_inset CommandInset ref LatexCommand vref reference "tab:Key-Bindings-in" \end_inset through \begin_inset CommandInset ref LatexCommand vref reference "tab:Key-Bindings-in-2" plural "false" caps "false" noprefix "false" \end_inset list all available key bindings \begin_inset Foot status collapsed \begin_layout Plain Layout If you are using the graphical version of \noun on teapot \noun default , please see section \begin_inset CommandInset ref LatexCommand vref reference "subsec:Differences-Between-User" \end_inset . \end_layout \end_inset . If a binding is only available in the console variant, it is enclosed in square brackets; if the binding only works in the graphical variant, it is in curly braces (the mnemonic for this notation is that square brackets are \begin_inset Quotes eld \end_inset plain \begin_inset Quotes erd \end_inset and curly braces are \begin_inset Quotes eld \end_inset fancy \begin_inset Quotes erd \end_inset ). \end_layout \begin_layout Standard \begin_inset Float table placement !tbh wide false sideways false status open \begin_layout Plain Layout \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout \series bold Cursor Motions \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Function Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout ASCII Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Operation \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Next Character/Right Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-F] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Right \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Prev. Character/Left Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-B] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Left \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Next Line/Down Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-N] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Down \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Previous Line/Up Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-P] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Up \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-PageDown} \end_layout \begin_layout Plain Layout {Click on right of layer number} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [+] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Next Layer \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-PageUp} \end_layout \begin_layout Plain Layout {Click on left of layer number} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout - (Dash/Minus) \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Previous Layer \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Begin/Home \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-A] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To column 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout End \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-E] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To last column \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-Home} {Ctrl-PageUp} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [<] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To row 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-End} {Ctrl-PageDown} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [>] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To last row \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-Home} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [_ (Underscore)] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To Layer 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-End} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [*] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout To last layer \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-X >] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Jump one page right \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-X >] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Jump one page left \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout PageDown {Ctrl-Down} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-V] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Jump one page down \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout PageUp {Ctrl-Up} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Meta-V] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Jump one page up \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-G} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Go to arbitrary location \end_layout \end_inset \end_inset \end_layout \begin_layout Plain Layout \begin_inset Caption Standard \begin_layout Plain Layout \begin_inset CommandInset label LatexCommand label name "tab:Key-Bindings-in" \end_inset Cursor Motion Key Bindings in Command Mode \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Float table placement !tbh wide false sideways false status open \begin_layout Plain Layout \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout \series bold Program Control \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Function Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout ASCII Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Operation \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout F10 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [/] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Main menu \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout F3 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-X Ctrl-S] {Ctrl-S} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Save sheet \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-Shift-S} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Save sheet as... \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Esc z] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Save sheet and quit \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout F2 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-X Ctrl-R] {Ctrl-O} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Load sheet \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-F} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Activate File menu \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-V} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Activate View menu \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-O} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Activate fOrmat menu \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-H} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Activate Help menu \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Ctrl-L \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Redraw screen \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-C] [Ctrl-G] {Esc} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Abort current action \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Cancel \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-X Ctrl-C] {Ctrl-Q} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Quit \end_layout \end_inset \end_inset \end_layout \begin_layout Plain Layout \begin_inset Caption Standard \begin_layout Plain Layout \begin_inset CommandInset label LatexCommand label name "tab:Key-Bindings-in-1" \end_inset Program Control Key Bindings in Command Mode \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard \begin_inset Float table placement !tbh wide false sideways false status open \begin_layout Plain Layout \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout \series bold Modify Cells/Blocks \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Function Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout ASCII Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Operation \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Enter \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-J] [Ctrl-M] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Edit cell contents \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Backspace \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-H] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Edit cell and delete last character \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \begin_inset Quotes eld \end_inset , @, \emph on digit \emph default , \emph on letter \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Overwrite cell contents \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-Enter} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Esc Ctrl-J] [Esc Ctrl-M] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Edit clocked cell contents \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-Meta-Enter} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Esc s] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Edit style expression \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout . (Period) \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Start/End Mark block (see text) \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-Right} {Shift-Left} \end_layout \begin_layout Plain Layout {Shift-Down} {Shift-Up} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Start Mark and Move \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-Insert} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-C} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Copy cell/text/block; End Mark \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-Delete} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Ctrl-X} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Designate block for moving; End Mark \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Shift-Insert} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-Y] {Ctrl-V} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Paste/move block \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Delete} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Clear block \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-A} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Set cell label \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-B} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle cell/block bold \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-U} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle cell/block underlined \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-L} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Make cell/block left justified \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-C} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Make cell/block centered \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-R} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Make cell/block right justified \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-P} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Set cell/block precision \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-W} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Set column width \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-E} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle cell/block shadowed \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-T} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle cell/block transparent \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Meta-I} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle cell/block ignored \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Ctrl-R \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Reset sheet \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout F9, {Shift-Tab} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-S] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Clock sheet \end_layout \end_inset \end_inset \end_layout \begin_layout Plain Layout \begin_inset Caption Standard \begin_layout Plain Layout \begin_inset CommandInset label LatexCommand label name "tab:Key-Bindings-in-2" \end_inset Key Bindings that Modify Cells in Command Mode \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard One command-mode key in particular needs additional explanation. The . (Period) marks blocks: The first time it is pressed marks the beginning of a block, which is then extended by moving the cell cursor. The next time, it marks the end of the block which lets you move the cell cursor after without changing the block. The third time, it removes the block marks again. \end_layout \begin_layout Section The Line Editor \end_layout \begin_layout Standard Many operations in \noun on teapot \noun default require editing a line of text, e.g. editing cell contents, typing file names and the like. Similar to the command mode, all things can be reached by control codes and most by function keys. Table \begin_inset CommandInset ref LatexCommand vref reference "tab:Key-Bindings-forLineEditor" \end_inset lists all available key bindings, again with brackets for those keys that only work in the console variant and curly braces for the graphical variant. \end_layout \begin_layout Standard \begin_inset Float table wide false sideways false status open \begin_layout Plain Layout \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout Function Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout ASCII Key \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Operation \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Previous Character/Left Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-B] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Move cursor left \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Next Character/Right Arrow \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-F] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Move cursor right \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Begin/Home \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-A] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Move cursor to column 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout End \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-E] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Move cursor to last column \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Enter \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-J] [Ctrl-M] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Finish editing/accept line \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Ctrl-L \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Redraw screen \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-T] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Transpose characters \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl- \backslash ] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Go to matching paren \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Cancel [Up Arrow] {Esc} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-G] [Ctrl-C] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Abort editing \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Backspace \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-H] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Delete previous character \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-K] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Delete rest of line \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Delete \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-?] [Ctrl-D] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Delete current character \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Tab] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout File name completion \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Insert \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle insert mode \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout {Tab} \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout [Ctrl-O] \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout Toggle motion in sheet (see text) \end_layout \end_inset \end_inset \end_layout \begin_layout Plain Layout \begin_inset Caption Standard \begin_layout Plain Layout \begin_inset CommandInset label LatexCommand label name "tab:Key-Bindings-forLineEditor" \end_inset Key Bindings for the line editor \end_layout \end_inset \end_layout \end_inset \end_layout \begin_layout Standard Besides the regular line editor operations, you may use Ctrl-O (Tab in the GUI version) to temporarily leave the editor in order to move around in the sheet if you are editing cell contents. Another Ctrl-O (resp. Tab) brings you back to the line editor. While moving around in the sheet, you can insert the value (v) or position (p) at the cursor position in the edited cell. Clicking on a cell while editing has the same effect as moving to that cell and pressing (p). \end_layout \begin_layout Standard Aborting line editing means that you will return immediately to command mode; whatever you started doing will have no effect. \end_layout \begin_layout Section Interactive Operations \end_layout \begin_layout Standard Most actions are available through the menu. Most of these will be applied to all cells within a block if a block of cells is marked. \end_layout \begin_layout Subsection \begin_inset CommandInset label LatexCommand label name "subsec:Cell-Attributes" \end_inset Cell Attributes \end_layout \begin_layout Standard Cells can have several attributes: \end_layout \begin_layout Itemize A cell label, which is useful because it avoids the need to directly address cells by their position, and because it continues to work if the cell is moved or if parts of the spreadsheet are inserted or deleted. A cell label must be different from any of the function names (see the list in \begin_inset CommandInset ref LatexCommand ref reference "subsec:Functions" plural "false" caps "false" noprefix "false" \end_inset ). \end_layout \begin_layout Itemize A \begin_inset Quotes eld \end_inset style, \begin_inset Quotes erd \end_inset which controls the visual appearance of the value of the cell on screen as well as in presentation output formats such as formatted text, \SpecialChar LaTeX , html, etc. Styles are addressed more fully in the next subsection. \end_layout \begin_layout Itemize A flag indicating whether the cell is \begin_inset Quotes eld \end_inset locked. \begin_inset Quotes erd \end_inset \end_layout \begin_layout Itemize A flag indicating whether the cell is \begin_inset Quotes eld \end_inset ignored. \begin_inset Quotes erd \end_inset \end_layout \begin_layout Standard In addition, each column has a width. \end_layout \begin_layout Subsubsection Label \end_layout \begin_layout Standard This operation lets you edit the cell label of the current cell. Further it changes all occurences of it in the cell contents to the new value, unless you erased the cell label. If a block has been marked at the time you edit the cell label, all occurences of the label in contents of cells in that block will be changed (rather than in the entire sheet). Once a cell is labeled, an occurrence of that label in any expression will evaluate to the (current) location of the cell. \end_layout \begin_layout Subsubsection Lock \end_layout \begin_layout Standard You can lock cells to protect them from accidental editing. Note that this protects you from modifying single cells. If you modify a block of cells which contains locked cells, those will be modified as well. Therefore, use extra caution in applying block commands. \end_layout \begin_layout Subsubsection Ignore \end_layout \begin_layout Standard Ignored cells will be completely ignored. They appear as empty cells on screen and during calculations. This is useful for temporarily disabling parts of your calculation, as the former content reappears when the ignore flag is removed again. \end_layout \begin_layout Subsubsection Column Width \end_layout \begin_layout Standard The column width only affects the screen display, not the formatting of the final output (except in the case of formatted text files). It is intended to let you make better usage of the screen for more overview. If the width is too small to display the cell value, a placeholder will be displayed. \end_layout \begin_layout Subsection Styles \end_layout \begin_layout Standard In \noun on teapot \noun default , a collection of all of the attributes that can affect the visual or formatted text of the value of a cell is called a \begin_inset Quotes eld \end_inset style. \begin_inset Quotes erd \end_inset The possble attributes in such a collection are enumerated in the following items. There are options in the menu systems of both teapot and fteapot to set each of these attributes for a cell. Some parts of the style can also be affected by command keys (see \begin_inset CommandInset ref LatexCommand ref reference "tab:Key-Bindings-in-2" plural "false" caps "false" noprefix "false" \end_inset ). \end_layout \begin_layout Standard However, \noun on teapot \noun default 's power to manipulate styles goes well beyond these menu items. Every cell in fact has a \emph on third \emph default associated expression, the style expression. This is accessed with Shift-Meta-Enter in \family typewriter fteapot \family default and Esc-s in \family typewriter teapot \family default . Any valid expression which returns a style may be entered, and then the expression will be evaluated whenever the cell needs to be displayed, and the computed result used to control the display of the cell. So for example, you can easily make the background color of a cell depend on its value; try setting the style expression for a cell to be \family sans background(13+int(@>0)) \family default and then making the contents of the cell either a positive or negative number. (Here \family sans @ \family default is a convenient abbreviation for \family sans @() \family default , the value of the current cell.) Note that you can combine different styles by adding them with the usual + operator; in case of conflict between attribute s, the left style takes precedence. So \family sans bold() + underline() \family default produces a bold, underlined style, whereas \family sans floatfmt(scientific) + floatfmt(decimal) \family default will display non-integer numerical values in scientific format. \end_layout \begin_layout Standard In fact, the menu functions to set items operate simply by adding terms to the style expression for the cell(s) being changed, to force the correspondi ng attribute of the style to have the spcecified values. You can always see the current style expression for a cell by using the proper key to edit its style expression, and then escaping the editor if you don't want to change it. \end_layout \begin_layout Standard A detailed discussion of each style attribute follows. \end_layout \begin_layout Subsubsection Justification (adjustment) \end_layout \begin_layout Standard Cell values may be aligned to the \family sans left \family default , the \family sans right \family default , or the \family sans center \family default . If the justification property of the style is not set to one of these three values (using the \family sans justify \family default () function), then number values will be right-aligned and all other values will be left-aligned. \end_layout \begin_layout Subsubsection Floating-point Format \end_layout \begin_layout Standard Floating-point (non-integer) numerical values in a cell may be displayed in one of four possible formats. Namely, they are \family sans decimal \family default (12.34), \family sans scientific \family default (1.234e1), \family sans compact \family default (a mix of these to produce the shorter notation depending on the magnitude of the value; this is the default), or \family sans hexact \family default (a specialized hexadecimal format used for exact round trips to text representa tion and back, rarely used for display.) This property is set with the \family sans floatfmt() \family default function. \end_layout \begin_layout Subsubsection Precision \end_layout \begin_layout Standard This attribute, set with the \family sans precision() \family default function and defaulting to 3, is an integer determining the number of digits used in the display of floating point values. Exactly how it affects the display depends on the floating-point format. For \family sans decimal \family default and \family sans scientific \family default , the precision specifies the maximum number of digits after the decimal point. For \family sans compact \family default , it determines the maximum total number of digits, before and after the decimal point. Precision has no effect on the \family sans hexact \family default format. A negative precision value subtracts from the maximum number of digits that could be meaningful given the limited accuracy of the computer's internal representation of floating point numbers, with -1 representing the maximum meaningful precision. (Very large precision values may produce more digits, but the trailing digits become meaningless as the computer cannot record variation on this tiny scale.) Note that this attribute only changes what is displayed; \noun on teapot \noun default always uses the maximum precision internally for calculations. \end_layout \begin_layout Subsubsection Dim \end_layout \begin_layout Standard This attribute is a simple true-false flag set with \family sans dim() \family default that determines whether the cell value will be displayed with dim characters, if possible. It defaults to false. \end_layout \begin_layout Subsubsection Bold \end_layout \begin_layout Standard This attribute is a simple true-false flag set with \family sans bold \family default () that determines whether the cell value will be displayed in a bold font, if possible. It defaults to false. \end_layout \begin_layout Subsubsection Italic \end_layout \begin_layout Standard This attribute is a simple true-false flag set with \family sans italic() \family default that determines whether the cell value will be displayed in an italic font, if possible. It defaults to false. \end_layout \begin_layout Subsubsection Underline \end_layout \begin_layout Standard This attribute is a simple true-false flag set with \family sans underline \family default () that determines whether the cell value will be underlined when displayed. It defaults to false. \end_layout \begin_layout Subsubsection Shadowed \end_layout \begin_layout Standard This attribute is a s simple true-false flag set with shadowed(), defaulting to false. When true, it means that the left neighbour cell will additionally use the display room of this cell (and all following shadowed cells to the immediate right as well). Thus, the shadowed cell becomes invisible \begin_inset Quotes eld \end_inset underneath \begin_inset Quotes erd \end_inset the cell to the left, although it retains its contents and its value will be computed, simply not displayed unless/until the shadowing is removed. You may think of shadowing as a way to get multi-column cells, for formatting purposes or so that longer text may be displayed. This mechanism is provided in \noun on teapot \noun default in place of a general \begin_inset Quotes eld \end_inset merge cells \begin_inset Quotes erd \end_inset feature as in other spreadsheets. \end_layout \begin_layout Subsubsection Transparent \end_layout \begin_layout Standard Usually, values are quoted as needed so that you get the exact same output in whatever display format is being used as on screen. That can be overridden with this true-false flag set with \family sans transparent \family default (), defaulting to false. Transparent cells will be exported as-is into display-oriented file formats (html, \SpecialChar LaTeX , etc.) so that you can embed commands for subsequent processing in cell values. When it is false, those special characters are quoted so they appear as-is. Not quoting them allows special effects (if you know html, roff, or \SpecialChar LaTeX ), but of course will cause the cell contents to look odd in formats other than the one for which the special values were designed. \end_layout \begin_layout Subsubsection Colors \end_layout \begin_layout Standard The \family sans foreground \family default () and \family sans background \family default () colors used to display a cell may be set. (Currently this only affects screen display.) The value of these attributes is a positive integer which acts as an index into the \begin_inset Quotes eld \end_inset palette \begin_inset Quotes erd \end_inset of colors for the display device being used. Currently, each of \family typewriter teapot \family default and \family typewriter fteapot \family default set up a default palette appropriate for their respective capabilities. Hopefully, a future enhancement will allow one to display, edit, save, and restore the palette. \end_layout \begin_layout Subsection Block Functions \end_layout \begin_layout Subsubsection Copy/Move \end_layout \begin_layout Standard To copy a block of cells, mark it, then move the cell cursor to where the upper left corner of the copy should be and issue the copy command. Moving works similarly, just use the move command. Of course you can mark three-dimensional blocks and copy them anywhere in the three-dimensional sheet, but doing so requires a good three-dimensional imagination to get what you want. \end_layout \begin_layout Subsubsection Fill \end_layout \begin_layout Standard To fill a block of cells, first mark the block it should be filled with. This may be just one cell! Then move the cell cursor to where the upper left corner of the block to be filled should be and issue the fill command. You will be prompted for how often the marked block should be repeated in each dimension. For example, you may to repeat a cell 9 times below. Mark it, then move down one row. Issue the fill command and answer 1 to the number of column repetitions, 9 to rows and 1 to layers. \end_layout \begin_layout Subsubsection Fill With \end_layout \begin_layout Standard This works in the \begin_inset Quotes eld \end_inset opposite direction \begin_inset Quotes erd \end_inset from Fill, but is handy for when you just want to replicate a single cell but don't know the exact count of repetitions you want. To use this operation, first mark the block you want to fill. Then make the current cell be the (single) cell you want to use to fill that block. Then execute Fill With. \end_layout \begin_layout Subsubsection Clear \end_layout \begin_layout Standard Clearing means to delete the cell contents and set all attributes to the default value. If you want to preserve the attributes, just edit the contents of a cell and delete them. \end_layout \begin_layout Subsubsection Insert \end_layout \begin_layout Standard Since work sheets can be three-dimensional, you can insert cells in all three dimensions, too. The inserted cells will be empty and their attributes have the default values. Cells will always be moved away from the front upper left corner to make room for the inserted cells. If no block is marked, you will be asked if you really only want to insert a cell of if you want to insert a whole row, line or sheet. \end_layout \begin_layout Subsubsection Delete \end_layout \begin_layout Standard Deleting works contrary to inserting. The deleted cells will be filled by moving neighbour cells to their positions. You will be prompted for the direction from where those cells will be taken. Deleting an entire column column-wise is done by marking the column, use the delete command and chose X direction. \end_layout \begin_layout Subsubsection \begin_inset CommandInset label LatexCommand label name "subsec:Sort" \end_inset Sort \end_layout \begin_layout Standard Marked blocks of cells can be sorted after one or multiple keys, either column-wise, row-wise or depth-wise. Sorting a two dimensional block row-wise will sort lines, but if a three dimensional block is sorted row-wise, then horizontal layers will be sorted. The sort key is specified as vector which is orthogonal to the sorted elements, either in ascending or descending order. The following example illustrates the sort operation. The upper left part of the screen should look like this: \begin_inset Separator latexpar \end_inset \end_layout \begin_layout Standard \align center \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout one \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 2 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout two \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 2 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 3 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout three \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 3 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 4 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout four \end_layout \end_inset \end_inset \end_layout \begin_layout Standard The box shows you which block to mark. Now this block should be sorted row-wise, with the sort key being the numbers in descending order, i.e. we want the lines being numbered 4,3,2,1. Go to the block menu, then select sort. Use \family typewriter R)ow \family default , because that is how we want to sort this block. The X position of the sort key vector is 0, because the column 0 contains the numbers. The Z position is 0, too, because those numbers are on sheet 0. Now chose \family typewriter D)escending \family default as direction. At this point, you could add a secondary key or decide to sort the block by the keys entered so far. Use \family typewriter S)ort region \family default to sort it. That's it, the screen should look like this now: \begin_inset Separator latexpar \end_inset \end_layout \begin_layout Standard \align center \begin_inset Tabular \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 0 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 4 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout four \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 3 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout three \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 2 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 2 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout two \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 3 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout 1 \end_layout \end_inset \begin_inset Text \begin_layout Plain Layout one \end_layout \end_inset \end_inset \end_layout \begin_layout Subsubsection Mirror \end_layout \begin_layout Standard Mirroring a marked block of cells can be done in three directions: Left/right, upside/down and front/back. \end_layout \begin_layout Subsection Saving and Loading \end_layout \begin_layout Subsubsection File names \end_layout \begin_layout Standard Usually, you want to overwrite the loaded file. For this reason, the loaded file name is remembered. If the sheet doesn't have a file name, like after starting an empty sheet, you will be asked for a name when saving. \end_layout \begin_layout Standard Occasionally, you may want to rename a sheet, like before making critical changes or when you load an existing sheet to have a start for making a new one. The Save As operation allows you to save the file under a new name. \end_layout \begin_layout Subsubsection File Formats \end_layout \begin_layout Paragraph ASCII (.tpa) \end_layout \begin_layout Standard The ASCII file format allows easy generation/modification of saved sheets by shell scripts. Note that when reading a .tpa file, either ordinary decimal or scientific formats for floating point number are recognized, as well as the exact hex floating point format used by default when saving. The default extension is \family typewriter . \family default tpa. \end_layout \begin_layout Paragraph Legacy XDR (.tp) \end_layout \begin_layout Standard XDR (eXternal Data Representation) is a standard invented by Sun Microsystems which defines a canonical way of storing/transporting data on external media. Its advantage is that it is widely available and that it defines a portable floating point number format. The native \noun on teapot \noun default file format formerly used XDR to be portable across different machine architect ures and operating systems. The advantage of this over the portable ASCII format was that due to the (usually) missing conversion calculations to ensure that any floating point constants would be saved/loaded exactly without conversion errors, the value of a cell might change slightly when saved and restored in the ASCII format. The XDR format was discontinued when the ASCII format was made exact by virtue of the exact hexadecimal \begin_inset Quotes eld \end_inset %a \begin_inset Quotes erd \end_inset style ( \begin_inset Quotes eld \end_inset hexact \begin_inset Quotes erd \end_inset ) of representing floating point values, and so there was no need for a specialized binary format. Old .tp files may be read, but \noun on teapot \noun default no longer writes files in this format. \end_layout \begin_layout Paragraph CSV (.csv) \end_layout \begin_layout Standard CSV (comma separated value) files only contain the data, not the expressions calculating it. Many spread sheets can generate this file format and many graphics programs like gnuplot(1) can read it. The field separator usually is a tab or comma, strings may be enclosed in double quotes and decimal numbers have a dot to mark the fractional part. One popular variation uses semicolons for separating fields and a decimal comma instead of a decimal point, which \noun on teapot \noun default tries to autodetect. \end_layout \begin_layout Standard On load, strings without quotes and with a \emph on 0x \emph default prefix followed by hexadecimal digits will be converted to integers. When loading CSV files, the sheet will not be cleared and the data will be load relative to the current cursor position. \end_layout \begin_layout Paragraph SC SpreadsheetCalculator (.sc) \end_layout \begin_layout Standard \noun on teapot \noun default can load simple SC sheets to convert them to \noun on teapot \noun default 's native format. While loading, \noun on teapot \noun default converts all references to absolute cell positions to labels. This allows to insert and delete in such sheets without screwing the whole sheet up. \noun on teapot \noun default can not save sheets in SC format, because SC lacks many features. For now, only the most basic SC features are supported. \end_layout \begin_layout Paragraph Lotus 1-2-3 (.wk1) \end_layout \begin_layout Standard \noun on teapot \noun default can load simple WK1 sheets to convert them to \noun on teapot \noun default 's native format. By default, 1-2-3 cell references are relative, so don't be surprised by a big amount of relative references in the resulting \noun on teapot \noun default sheet. For now, only the most basic 1-2-3 features are supported. \end_layout \begin_layout Paragraph Formatted ASCII (.txt) \end_layout \begin_layout Standard The generated formatted ASCII files contain about what you see on the screen. If your sheet has more than one layer, then the various layers will be saved separated by form feeds. \end_layout \begin_layout Paragraph Troff tbl (.tbl) \end_layout \begin_layout Standard \noun on teapot \noun default can generate tbl(1) table bodies in single files which are supposed to be used like this: \end_layout \begin_layout Quote \family typewriter .TS \begin_inset Newline newline \end_inset \family default \shape italic options \family typewriter \shape default ; \begin_inset Newline newline \end_inset .so \family default \shape italic filename \begin_inset Newline newline \end_inset \family typewriter \shape default .TE \end_layout \begin_layout Standard You will have to use soelim(1) to eliminate the \family typewriter .so \family default requests before the tbl run. The \shape italic options \family typewriter \shape default ; \family default are optional. If you use GNU roff, you will need to eliminate \family typewriter .lf \family default requests, because this GNU roff extension confuses GNU tbl: \end_layout \begin_layout Quote \family typewriter soelim \family default \shape italic file \shape default \family typewriter | grep -v '^ \backslash .lf' \end_layout \begin_layout Standard Alternatively, you can generate a stand-alone document, which needs no further operations to format and print. Note: If no block is marked, the whole sheet will be saved. \end_layout \begin_layout Paragraph \SpecialChar LaTeX (.latex) \end_layout \begin_layout Standard If you generate \SpecialChar LaTeX2e tables in single files, you include them in documents using the \family typewriter \backslash include \family default command. Alternatively, you can generate a stand-alone document, which needs no further operations to format and print. Note: If no block is marked, the whole sheet will be saved. \end_layout \begin_layout Paragraph Con\SpecialChar TeX t (.tex) \end_layout \begin_layout Standard Analogous to \SpecialChar LaTeX output, this generates input suitable to the Con\SpecialChar TeX t macro package. \end_layout \begin_layout Paragraph HTML (.html) \end_layout \begin_layout Standard You can generate html table bodies in single files which could be used in combination with server-side includes. This feature differs between the various servers, so refer to the manual for your web server for details, please. \end_layout \begin_layout Standard Alternatively, you can generate a stand-alone document. Note: If no block is marked, the whole sheet will be saved. \end_layout \begin_layout Subsection Other operations \end_layout \begin_layout Subsubsection Goto Location \end_layout \begin_layout Standard Sometimes, you directly want to go to a specific position, either to change its contents to see which cell a location expression refers to. This operation lets you enter an expression, which must evaluate to a value of the type location. If so, the cursor is positioned to that location. For example, you could enter \family typewriter &(10,2) \family default to go to cell 10,2 of the current layer or you could enter the name of a label you want to go to. Relative movements are no problem, either. \end_layout \begin_layout Subsubsection Shell \end_layout \begin_layout Standard Start a sub shell. Exiting from that sub shell will bring you back into \family typewriter teapot \family default . This operation does not exist in the GUI version. \end_layout \begin_layout Subsubsection Version \end_layout \begin_layout Standard \noun on teapot \noun default will display its version number and copyright statement. \end_layout \begin_layout Subsubsection Help \end_layout \begin_layout Standard If \noun on teapot \noun default was built with the integrated help viewer, you can access this manual from within \noun on teapot \noun default itself. \end_layout \begin_layout Section Batch operations \end_layout \begin_layout Standard Besides interactive facilities, \noun on teapot \noun default has a batch mode. Using this batch mode, shell scripts can generate output from \noun on teapot \noun default sheets. This is handy if you use make(1) to generate a bigger document containing tables, because you don't have to generate a tbl or \SpecialChar LaTeX file each time you modify a sheet: make will do so. In batch mode, \noun on teapot \noun default reads batch commands from standard input. The following commands are available: \end_layout \begin_layout Description \family typewriter \series bold goto \family default \shape italic \begin_inset space ~ \end_inset location \series default \shape default Go to the specified \shape italic location \shape default . \end_layout \begin_layout Description \family typewriter \series bold from \family default \shape italic \begin_inset space ~ \end_inset location \series default \shape default Start marking a block. \end_layout \begin_layout Description \family typewriter \series bold to \family default \shape italic \begin_inset space ~ \end_inset location \series default \shape default End marking a block. \end_layout \begin_layout Description \family typewriter \series bold sort-x \family default \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset y \begin_inset space ~ \end_inset z \emph default \begin_inset space ~ \end_inset [ \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset y \begin_inset space ~ \end_inset z \emph default \begin_inset space ~ \end_inset ... \begin_inset space ~ \end_inset ] \end_layout \begin_layout Description \family typewriter \series bold sort- \family default y \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset x \begin_inset space ~ \end_inset z \emph default \begin_inset space ~ \end_inset [ \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset x \begin_inset space ~ \end_inset z \emph default \begin_inset space ~ \end_inset ... \begin_inset space ~ \end_inset ] \series default \end_layout \begin_layout Description \family typewriter \series bold sort- \family default z \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset x \begin_inset space ~ \end_inset \emph default y \begin_inset space ~ \end_inset [ \begin_inset space ~ \end_inset d|a \emph on \begin_inset space ~ \end_inset x \begin_inset space ~ \end_inset \emph default y \begin_inset space ~ \end_inset ... \begin_inset space ~ \end_inset ] \series default Sorts the marked block as described in section \begin_inset CommandInset ref LatexCommand vref reference "subsec:Sort" \end_inset , column-wise, row-wise or depth-wise, respectivly. "d" or "a" specify the sort order to be descending or ascending. \emph on x \emph default , \emph on y \emph default and \emph on z \emph default specify the position of the sort key \family typewriter relative \family default to the first cell of the marked block. Up to eight sort keys can be specified. This example reproduces the result from section \begin_inset CommandInset ref LatexCommand ref reference "subsec:Sort" \end_inset : \begin_inset Separator latexpar \end_inset \end_layout \begin_deeper \begin_layout Quote \family typewriter echo " \begin_inset Newline newline \end_inset from &(1,1,0) \begin_inset Newline newline \end_inset to &(2,4,0) \begin_inset Newline newline \end_inset sort-y d 0 0 \begin_inset Newline newline \end_inset save-csv result_num.txt \begin_inset Newline newline \end_inset " | teapot -b doc/unsorted \end_layout \end_deeper \begin_layout Description \family typewriter \series bold save-tbl \family default \emph on \begin_inset space ~ \end_inset file \series default \emph default \end_layout \begin_layout Description \family typewriter \series bold save-csv \family default \emph on \begin_inset space ~ \end_inset file \series default \emph default \end_layout \begin_layout Description \family typewriter \series bold save-latex \family default \emph on \begin_inset space ~ \end_inset file \series default \emph default \end_layout \begin_layout Description \family typewriter \series bold save-context \family default \emph on \begin_inset space ~ \end_inset file \series default \emph default \end_layout \begin_layout Description \family typewriter \series bold save-html \begin_inset space ~ \end_inset \family default \emph on file \series default \emph default Save the marked block in the specified format as \emph on file \emph default . \end_layout \begin_layout Description \family typewriter \series bold load-csv \begin_inset space ~ \end_inset \family default \emph on file \series default \emph default Load \emph on file \emph default in the specified format to the last \family typewriter goto \family default location. This has the same functionality as the interactive load described in subsection \emph on 5.12.4 \emph default . \end_layout \begin_layout Section Expressions \end_layout \begin_layout Standard Cells consist of a base (reset) expression, a clocked expression, a style expression, and a current value. If the sheet is currently in the reset state (the default), all cells display their base value as current value. \end_layout \begin_layout Standard When the sheet is clocked (see Table \begin_inset CommandInset ref LatexCommand ref reference "tab:Key-Bindings-in" \end_inset ), the clocked expression is evaluated, using the current value of referenced cells. The new current value is the result of that evaluation. \end_layout \begin_layout Subsection Data Types \end_layout \begin_layout Standard In \noun on teapot \noun default , each value has an associated data type. The following data types exist: \end_layout \begin_layout Description Empty Empty cells behave as if they have 0, 0.0 or \begin_inset Quotes eld \end_inset \begin_inset Quotes erd \end_inset as value, depending on context. However, the specific unique \begin_inset Quotes eld \end_inset empty \begin_inset Quotes erd \end_inset value can be tested for explicitly, distinct from any of these, for example with \family sans is( \emph on loc \emph default , empty) \family default . \end_layout \begin_layout Description String A string is a sequence of characters enclosed by double quotes: \family typewriter "This is a string" \family default . A double quote can be part of the string, if it is quoted using a backslash: \family typewriter \begin_inset Quotes eld \end_inset \backslash \family default \begin_inset Quotes erd \end_inset \begin_inset Quotes erd \end_inset . If you want the backslash to appear in the output instead of quoting the next character, use it to quote itself: \family typewriter \begin_inset Quotes eld \end_inset \backslash \backslash \family default \begin_inset Quotes erd \end_inset . \end_layout \begin_layout Description Floating \begin_inset space ~ \end_inset Point Floating point values are inexact, their precision and range depends on the implementation of the C type long double on your system. An example is: \family typewriter 42.0 \family default \end_layout \begin_layout Description Integer Integer values are exact, their range depends on the C type long long on your system. An example is: \family typewriter 42 \end_layout \begin_layout Description Boolean \begin_inset Quotes eld \end_inset true \begin_inset Quotes erd \end_inset or \begin_inset Quotes eld \end_inset false, \begin_inset Quotes erd \end_inset used for logical conditions. \end_layout \begin_layout Description Label Cell labels are of this type, but they generally evaluate to locations (or cause an error if there is no cell with that label), so you don't generally manipulate values of this type. \end_layout \begin_layout Description Keyword The names of functions and of special arguments to functions, like the \family sans decimal \family default flag to the \family sans float() \family default function. \end_layout \begin_layout Description Location The values of cell labels and the result of the \family sans &() \family default function have this type, but there are no location constant literals. However, \family sans &(3,2,1) \family typewriter , \family default for example, acts very much like a location constant literal. \end_layout \begin_layout Description Error Syntactical or semantical (type mismatch) errors cause this value, as well as division by 0 and the function \family sans error() \family default . An error always has an assigned error message. Functions and operators, when applied to a value of the type error, evaluate to just that value. That way, the first error encountered, possibly deep inside a complicated expression, will be shown. \end_layout \begin_layout Description Expression a \noun on teapot \noun default formula; some functions (like \family sans find() \family default ) take an expression as an argument so that it can be evaluated from the point of view of other cells. \end_layout \begin_layout Description Style the encapsulated visual/display attributes of a cell. Not many operators/functions apply to Style values, but there is one function for each attribute of a Style (that produces Style values with that attribute set), and they may be combined with the + operator. Style expressions are the key to allowing the appearance of a cell to depend on its value. \end_layout \begin_layout Subsection Operators \end_layout \begin_layout Standard Unlike other spreadsheets, the operators in \noun on teapot \noun default check the type of the values they are applied to, which means trying to add a string to a floating point number will result in an type error. Operators on locations in the spreadsheet, which are just triples of integers, generally operate following typical rules for vectors, with particular notes below. The following operators are available, listed in ascending precedence: \end_layout \begin_layout Description x \series medium \emph on \begin_inset space ~ \end_inset \family typewriter \series default \emph default and \family default \series medium \emph on \begin_inset space ~ \end_inset \series default \emph default y evaluates to the logical conjunction of values \emph on x \emph default and \emph on y \emph default . Note that this evaluation short-circuits: if \emph on x \emph default is false, then \emph on y \emph default is never evaluated, and so does not affect the value even if it is an error, for example. In determining the value, the boolean conversions of \emph on x \emph default and \emph on y \emph default are used (see the description of the bool() function below), but the actual value returned is either that of \emph on x \emph default or \emph on y \emph default , namely, \emph on x \emph default if it corresponds to a boolean false value or \emph on y \emph default otherwise. \end_layout \begin_layout Description x \series medium \emph on \begin_inset space ~ \end_inset \family typewriter \series default \emph default or \family default \series medium \emph on \begin_inset space ~ \end_inset \series default \emph default y evaluates to the logical disjunction of boolean values \emph on x \emph default and \emph on y \emph default . As with \family typewriter \series bold and \family default \series default , this evaluation short-circuits if \emph on x \emph default is true. Also in similar fashion, the value is \emph on x \emph default if it corresponds to a boolean true value and \emph on y \emph default otherwise. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default < \family default \emph on y \series default \emph default evaluates to Boolean true if \emph on x \emph default is less than \emph on y \emph default . If \emph on x \emph default or \emph on y \emph default are empty, they are considered to be 0 if the other is an integer number, 0.0 if it is a floating point number and the empty string if it is a string. On locations, \emph on x= \family default \emph on y \series default \emph default evaluates to true if \emph on x \emph default is greater than or equal to \emph on y \emph default . For locations, this must hold for every component. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default > \family default \emph on y \series default \emph default evaluates to true if \emph on x \emph default is greater than \emph on y \emph default . As with <, for locations, every component must be greater than or equal, and at least one must be strictly greater. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default == \family default \emph on y \series default \emph default evaluates to true if \emph on x \emph default is equal to \emph on y \emph default . \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default ~= \family default \emph on y \series default \emph default evaluates to true if the floating point value \emph on x \emph default is almost equal to the floating point value \emph on y \emph default . Almost equal means that the numbers are equal or neighbor each other in the floating point representation being used. It is an error to use this comparison with any type but float. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default != \family default \emph on y \series default \emph default evaluates to 1 if \emph on x \emph default is not equal to \emph on y \emph default . \end_layout \begin_layout Description Note: a string of consecutive relational operators is interpreted as the conjunction of each consecutive (overlapping) pair. Thus \family sans 2 <= y() <= 10 \family default will evaluate to true precisely in rows 2 through 10, inclusive (it is shorthand for \family sans 2 <= y() and y() <= 10 \family default ). Similarly \family sans @(cell1) == @(cell2) == @(cell3) \family default will return true exactly when all three cells have the same value. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default + \family default \emph on y \series default \emph default evaluates to the sum if \emph on x \emph default and \emph on y \emph default are numbers. If \emph on x \emph default and \emph on y \emph default are strings, the result is the concatenated string. If they are locations, this operates componentwise. If they are styles, it means to take any unset components of the left-hand style and fill them in with values from the right-hand style (ignoring the right-hand components that are already set in the left-hand style). \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default - \family default \emph on y \series default \emph default evaluates to the difference if \emph on x \emph default and \emph on y \emph default are numbers. If they are locations, this operates componentwise. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default * \family default \emph on y \series default \emph default evaluates to the product if \emph on x \emph default and \emph on y \emph default are numbers. You can multiply a location by an integer, or take the dot product of the coordinates of two locations (although the use case for that is unclear). \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default / \family default \emph on y \series default \emph default evaluates to the quotient if \emph on x \emph default and \emph on y \emph default are numbers. You can divide a location by an integer. \end_layout \begin_layout Description \series bold \emph on x \family typewriter \emph default % \family default \emph on y \series default \emph default evaluates to the remainder of the division if \emph on x \emph default and \emph on y \emph default are numbers. You can mod a location by an integer, or operate on two locations, in which case the mod operation applies componentwise. \end_layout \begin_layout Description \family typewriter \series bold - \family default \emph on x \series default \emph default evaluates to \family typewriter - \family default \emph on x \emph default if \emph on x \emph default is a number or location, or the negation of \emph on x \emph default if \emph on x \emph default is Boolean. If \emph on x \emph default is empty, the result will be empty, too. \end_layout \begin_layout Description \series bold \emph on x^y \series default \emph default evaluates to \emph on x \emph default to the power of \emph on y \emph default . \end_layout \begin_layout Description \family typewriter \series bold ( \family default \emph on expression \family typewriter \emph default ) \family default \series default evaluates to the expression. \end_layout \begin_layout Description \series bold \emph on function \family typewriter \emph default ( \family default \emph on argument \family typewriter \emph default , \family default ... \family typewriter ) \family default \series default evaluates to the value of the function applied to the values resulting from evaluating the argument expressions. Note that if no arguments are being supplied, the parentheses are optional. Hence, for example, you can use \begin_inset Quotes eld \end_inset e \begin_inset Quotes erd \end_inset by itself, like a reserved constant whose value is the usual mathematical \begin_inset Quotes eld \end_inset e, \begin_inset Quotes erd \end_inset the base of natural logarithms. \end_layout \begin_layout Subsection \begin_inset CommandInset label LatexCommand label name "subsec:Functions" \end_inset Functions \end_layout \begin_layout Standard This section documents all available functions in alphabetical order (except for the short addressing/value fetching functions, which are listed together at the beginning). The functions are described in a C-like notation; you don't have to write the types when you use the function in a formula. For example, use \family sans @(0,0,0) \family default , not \family sans @(int 0, int 0, int 0) \family default . If no type is given for the result of a function, it means the result type depends on the arguments. Brackets mark optional arguments. \end_layout \begin_layout Description @ \series medium ([location \emph on \begin_inset space ~ \end_inset l \emph default ,][int \begin_inset space ~ \end_inset \emph on x \emph default ][,[int \emph on \begin_inset space ~ \end_inset y \emph default ][,[int \emph on \begin_inset space ~ \end_inset z \emph default ]]]) \series default returns the value of the cell at the specified location. If any of \emph on x \emph default , \emph on y \emph default or \emph on z \emph default is specified, that value overrides the corresponding coordinate of the given location, which defaults to the location of the current cell if it is omitted. \end_layout \begin_layout Description \series medium location \begin_inset space ~ \end_inset \series default & \series medium ([location \emph on \begin_inset space ~ \end_inset l \emph default ,][int \emph on \begin_inset space ~ \end_inset x \emph default ][, \begin_inset space ~ \end_inset [int \emph on \begin_inset space ~ \end_inset y \emph default ][, \begin_inset space ~ \end_inset [int \emph on \begin_inset space ~ \end_inset z \emph default ]]]) \series default the arguments are interpreted in exactly the same way as for \series bold @ \series default (), but this fuction returns the location, not the value of the cell at that location. So note for example that a bare \series bold & \series default with no arguments (with or without parentheses) evaluates to the location of the current cell. \end_layout \begin_layout Description D( \series medium [location \emph on \begin_inset space ~ \end_inset l \emph default ,][int \begin_inset space ~ \end_inset \emph on x \emph default ][,[int \emph on \begin_inset space ~ \end_inset y \emph default ][,[int \emph on \begin_inset space ~ \end_inset z \emph default ]]] \series default ) Like \series bold & \series default (), except that any of \emph on x, y, \emph default or \emph on z \emph default specified are added to the given location, which defaults to the current location; and as a special case, if only the location is given, i.e. \family sans \series bold D \family default \series default ( \emph on l \emph default ), then the location \emph on l \emph default is added to the current location. Think \begin_inset Quotes eld \end_inset D \begin_inset Quotes erd \end_inset for \begin_inset Quotes eld \end_inset displaced (by). \begin_inset Quotes erd \end_inset Thus, both \family sans \series bold D \series default (-1) \family default and \family sans \series bold D \series default (left) \family default return the location of the cell immediately to the left of this one, and \family sans \series bold D \series default (,2,1) \family default returns the location of the cell two below this one on the following layer, as does \family sans \series bold D \family default \series default (&(0,2,1)), but \family sans \series bold D \family default \series default (TABLE,1) returns the location of the cell just to the right of the one labeled \begin_inset Quotes eld \end_inset TABLE \begin_inset Quotes erd \end_inset . \end_layout \begin_layout Description R( \series medium \emph on args \series default \emph default ) Shorthand for \series bold @ \series default ( \family sans \series bold D \family default \series default (args)). Think \begin_inset Quotes eld \end_inset R \begin_inset Quotes erd \end_inset for \begin_inset Quotes eld \end_inset relative. \begin_inset Quotes erd \end_inset Thus \family sans \series bold R \series default (-1) \family default returns the value of the cell immediately to the left of this one, and \family sans \series bold R \series default (,,1) \family default returns the same cell as this one but on the following layer, as do \family sans \series bold R \series default (&(0,0,1) \family default ) and \family sans \series bold R \series default (below \family default ), but \family sans \series bold R \family default \series default (TABLE,,1) returns the value of the cell immediately down from the one labeled \begin_inset Quotes eld \end_inset TABLE \begin_inset Quotes erd \end_inset . \end_layout \begin_layout Description X( \series medium label \emph on \begin_inset space ~ \end_inset to, \begin_inset space ~ \end_inset \emph default label \emph on \begin_inset space ~ \end_inset from, \begin_inset space ~ \end_inset \emph default [ \emph on fix_x \emph default ] \emph on , \begin_inset space ~ \end_inset \emph default [ \emph on fix_y \emph default ] \emph on , \begin_inset space ~ \end_inset \emph default [ \emph on fix_z \emph default ] \series default ) \begin_inset Quotes eld \end_inset Excel reference \begin_inset Quotes erd \end_inset : returns the value of the cell at a computed target location. This target location is the one reached from the current cell via the same offset as the cell with label \emph on to \emph default has from label \emph on from. \emph default The idea is that if you label the source of data you want to reference, say with \family sans SRC \family default , and the location of some place you want to start referring to it with \family sans REF \family default , then you can use \family sans \series bold X \series default (SRC,REF) \family default to refer to the source data, and fill this formula to neighboring cells to refer to the neighbors of the source, and it will all continue to work if either the source or the reference is moved around in the sheet. \begin_inset Newline newline \end_inset If the \emph on fix_DIM \emph default argument is the \family sans fix \family default keyword (as opposed to an empty value), then the corresponding coordinate of the target cell is set to match that of \emph on to \emph default . This corresponds to fixing the row or column (or layer) of the reference, as with a \begin_inset Quotes eld \end_inset $ \begin_inset Quotes erd \end_inset character in Excel. Thus \family sans \series bold X \series default (SRC,REF,1,1,1) \family default is identical to \family sans @(SRC) \family default , but you should certainly prefer the latter for clarity of expression. \begin_inset Newline newline \end_inset There is a corresponding location function \family sans \series bold X& \series default () \family default as well, which takes exactly the same arguments with the same meanings, but it is rarely needed. It is provided for completeness. \begin_inset Newline newline \end_inset See the FAQ below for further discussion of cell references. \end_layout \begin_layout Description \series medium string \begin_inset space ~ \end_inset \series default $ \series medium (string \emph on \begin_inset space ~ \end_inset env \emph default ) \series default evaluates to the contents of the specified environment variable. If the variable does not exist, then an empty string will be returned. \end_layout \begin_layout Description above|below|left|right|up|down \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] As bare words (without any arguments and also without the parentheses) these symbols return a one-cell displacement in the named direction, e.g. \family sans \series bold D \series default (above) \family default \series medium gives the location of the same cell as the current on but in the previous layer and \family sans \series bold R \series default (up) \family default \series medium yields the value of the cell one up from the current cell. With parentheses, they act like \series bold @ \series default () \series medium but displaced by one cell in the named direction, so \family sans \series default right() \family default \series medium returns the value of the cell immediately to the right of the current one, and \family sans \series default down(MYTABLE) \family default \series medium gives the value one line down from the cell labeled \family sans \series default MYTABLE \family default \series medium , etc. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default abs \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) \series default \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default abs \series medium (int \begin_inset space ~ \end_inset \emph on x \emph default ) \series default evaluates to the absolute value of \emph on x \emph default . \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default acos \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc cosine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default arcosh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc hyperbolic cosine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default arsinh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc hyperbolic sine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default artanh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc hyperbolic tangent of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default asin \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc sine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default atan \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the arc tangent of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default background \series medium (int \emph on \begin_inset space ~ \end_inset \emph default c) \series default evaluates to a style token with the background color set to \emph on c \emph default (and no other fields set). \end_layout \begin_layout Description below \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] displacement by one cell in the positive \series default \emph on z \emph default direction; see the fuller description at \family sans \series bold above \series default . \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default bitand \series medium (int \emph on \begin_inset space ~ \end_inset v1, \begin_inset space ~ \end_inset ... \emph default ) evaluates to the bitwise \begin_inset Quotes eld \end_inset and \begin_inset Quotes erd \end_inset of all the supplied values. \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default bitor \series medium (int \emph on \begin_inset space ~ \end_inset v \emph default 1, \emph on \begin_inset space ~ \end_inset \emph default ...) evaluates to the bitwise \begin_inset Quotes eld \end_inset or \begin_inset Quotes erd \end_inset of all the supplied values. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default bold \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the bold property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description \series medium bool \begin_inset space ~ \end_inset \series default bool \series medium [([ \emph on x \emph default ])] \series default Converts \emph on x \emph default to a boolean value. This is very permissive; error values are unaffected; empty, integer 0, float 0.0, and boolean false values are false, and everything else is true. If \emph on x \emph default is omitted, defaults to the value of the current cell. If the parentheses are omitted as well, acts as a keyword, for example for testing types with \family sans \series bold is \series default (). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default ceil \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) evaluates to the smallest integral floating-point value greater than or equal to \family sans \series default \emph on x \emph default . \end_layout \begin_layout Description center keyword used as an argument to \family sans \series bold justify \family default \series default (). \end_layout \begin_layout Description clock \series medium (integer \emph on \begin_inset space ~ \end_inset condition \emph default ,[location[,location]) \series default conditionally clocks the specified cell if the condition is not 0. If two locations are given, all cells in that range will be clocked. The return value of clock is empty. Note that the clocked expression of a cell can clock itself; indeed, that's the only way that a cell can be clocked more than once in a single recalculatio n. Take care with the \emph on condition \emph default expression to avoid recalculation becoming stuck in an infinite loop, however. \end_layout \begin_layout Description compact used as a keyword to the \family sans \series bold string \family default \series default () function; listed here to record that this identifier may not be used as a cell label. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default cos \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the cosine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default cosh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the hyperbolic cosine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description decimal used as a keyword to the string() function; listed here to record that this identifier may not be used as a cell label. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default deg2rad \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the degrees that are equivalent to \emph on x \emph default radians. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default dim \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the dim property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description down \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] displacement by one cell in the positive \series default \emph on y \emph default direction; see the fuller description at \family sans \series bold above \series default . \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default e \series medium [()] \series default evaluates to the Euler constant \emph on e \emph default . Note the parentheses are optional. \end_layout \begin_layout Description empty \series medium [( \shape italic args \shape default )] \series default ignores all of its arguments and returns the empty value. Without parentheses, acts as a keyword, typically for \family sans \series bold is \series default (). \end_layout \begin_layout Description \series medium error \begin_inset space ~ \end_inset \series default error \series medium [([ \emph on message \emph default ])] \series default converts its argument to a string just as with the string() function, and then returns an error with that string as the message. Without parentheses, acts as a keyword, e.g. for \family sans \series bold is \series default () \family default . \end_layout \begin_layout Description eval \series medium (location) \series default evaluates to the value of the expression in the cell at the given \emph on location \emph default , but evaluated in the context of the cell using eval(). This function may not be used nested any deeper than 32 times. \end_layout \begin_layout Description \series medium boolean \begin_inset space ~ \end_inset \series default false represents the false Boolean value. \end_layout \begin_layout Description fident a keyword indicating the token type of \begin_inset Quotes eld \end_inset function identifier, \begin_inset Quotes erd \end_inset provided for the sake of completeness. There is probably little practical call for this type. \end_layout \begin_layout Description find \series medium ( \emph on expr \emph default , \emph on \begin_inset space ~ \end_inset \emph default location \emph on \begin_inset space ~ \end_inset stride \emph default [,location \emph on \begin_inset space ~ \end_inset start \emph default ]) examines cells in turn, returning the location of the first one at which \series default \emph on expr \emph default evaluates to true, or boolean false if the boundary of the sheet is encountered. The second argument \emph on stride \emph default must not have all zero components, and is added to the location being examined at each iteration. Often it is useful to use a direction constant like \family sans \series bold up \family default \series default for the stride. The search begins at location \emph on start \emph default , which defaults to the current location plus the \emph on stride \emph default if it is not specified. \end_layout \begin_layout Description fix used as a keyword to the \family sans X() \family default and \family sans X&() \family default functions; listed here to record that this identifier may not be used as a cell label. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default float \series medium [([float|string|int|empty \emph on \begin_inset space ~ \end_inset s \emph default ])] \series default converts into a floating point number the given float, string, int, or empty value (the latter converts to 0.0). If the argument is omitted, the value of the current cell is used. If the parentheses are omitted, acts as a keyword, e.g., for type testing with \family sans \series bold is \series default () \family default . \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default floatfmt \series medium (decimal|scientific|compact|hexact) \series default evaluates to a style token with the floating-point format set to the specified format, given as a bare word (and no other fields set). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default floor \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) evaluates to the largest integral floating-point value less than or equal to \series default \emph on x \emph default . \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default foreground \series medium (int \emph on \begin_inset space ~ \end_inset \emph default c) \series default evaluates to a style token with the foreground color set to \emph on c \emph default (and no other fields set). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default frac \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the fractional part of \emph on x \emph default . \end_layout \begin_layout Description funcall a keyword indicating the \begin_inset Quotes eld \end_inset funcall \begin_inset Quotes erd \end_inset token type used to encode expressions as tokens; may be used with \family sans \series bold is \series default () \family default for example. \end_layout \begin_layout Description hexact used as a keyword to the string() function; listed here to record that this identifier may not be used as a cell label. \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default int \series medium [([int|float|string|empty \emph on \begin_inset space ~ \end_inset x \emph default ][, \emph on \begin_inset space ~ \end_inset direction \emph default ])] \series default converts to an \emph on \emph default integer the given integer, float, string, or empty value \emph on x. \emph default (The latter converts to 0.) The optional second argument must be the name of one of the functions that produces a floating point integral value from a float, i.e., \family sans \series bold ceil \family default \series default , \family sans \series bold floor \family default \series default , \family sans \series bold round \family default \series default , or \family sans \series bold trunc \family default \series default , and it directs how to convert floating point values to an integer. (The default is \family sans \series bold trunc \family default \series default , see the documentation of the corresponding functions for a description of the conversion behavior.) If \emph on x \emph default is omitted, the value of the current cell is used. If in addition the parentheses are omitted, acts as a keyword, e.g., for value testing with \family sans \series bold is \series default () \family default . \end_layout \begin_layout Description is \series medium [([ \emph on x \emph default ][, \emph on \begin_inset space ~ \end_inset type1, \begin_inset space ~ \end_inset type2 \emph default ,...])] \series default Boolean-valued type testing. Returns true if the given value \emph on x \emph default is any of the listed types. Each type may be any of the keywords \family sans \series bold bool, empty, error, fident, float, funcall, int \family default \series default , \family sans \series bold lident, location, number, operator, \family default \series default \family sans \series bold string \family default \series default , or \family sans \series bold style \family default \series default . Each of these identifies a single type, except \family sans \series bold number \family default \series default , which is a shorthand for \family sans \series bold empty \family default \series default , \family sans \series bold float \family default \series default , \family sans \series bold int \family default \series default . If no types are specified, returns true for any non-empty value. (In other words, \family sans \series bold is \series default ( \emph on x \emph default ) \family default is a boolean-valued version of \family sans \series bold n \series default ( \emph on x \emph default ) \family default , without the special behavior when \emph on x \emph default is a location.) If \emph on x \emph default is omitted, defaults to the value of the current cell; the parentheses may be omitted as well, so bare \family sans \series bold is \family default \series default tests whether the current cell is non-empty. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default italic \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the italic property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default justify \series medium (left|right|center) \series default evaluates to a style token with the justification set to the specified direction, given as a bare word. No other fields are set in the result. \end_layout \begin_layout Description left \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] displacement by one cell in the negative \series default \emph on x \emph default direction; see the fuller description at \family sans \series bold above \series default . \end_layout \begin_layout Description \series medium string \begin_inset space ~ \end_inset \series default len \series medium (string \emph on \begin_inset space ~ \end_inset s \emph default ) \series default evaluates to the length of \emph on s \emph default . \end_layout \begin_layout Description lident a keyword indicating the \begin_inset Quotes eld \end_inset label identifier \begin_inset Quotes erd \end_inset token type. This type is not generally accessible, as labels always evaluate to their locations (or error if there is no such label). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default log \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default [, \begin_inset space ~ \end_inset float|int \emph on \begin_inset space ~ \end_inset y \emph default ]) \series default evaluates to the logarithm of \emph on x \emph default . If \emph on y \emph default is not specified, the result will be the natural logarithm, otherwise it will be the logarithm to the base of \emph on y \emph default . \end_layout \begin_layout Description location currently this is only a keyword, e.g., for use with \family sans \series bold is \series default () \family default . Use \family sans \series bold & \series default () \family default to convert three integers to a location. \end_layout \begin_layout Description \series medium location \begin_inset space ~ \end_inset \series default max \series medium (location \emph on \begin_inset space ~ \end_inset l1 \emph default , \begin_inset space ~ \end_inset location \emph on \begin_inset space ~ \end_inset l2 \emph default ) \emph on \begin_inset space ~ \end_inset \emph default | \emph on \begin_inset space ~ \end_inset \series default \emph default max \series medium ( \emph on v1 \emph default , \begin_inset space ~ \end_inset \emph on v2 \emph default , \emph on \begin_inset space ~ \end_inset \emph default ...) \series default evaluates to the maximum in the same way min does for the minimum. \end_layout \begin_layout Description \series medium location \begin_inset space ~ \end_inset \series default min \series medium (location \emph on \begin_inset space ~ \end_inset l1 \emph default , \begin_inset space ~ \end_inset location \emph on \begin_inset space ~ \end_inset l2 \emph default ) \emph on \begin_inset space ~ \end_inset \emph default | \emph on \begin_inset space ~ \end_inset \series default \emph default min \series medium ( \emph on v1 \emph default , \begin_inset space ~ \end_inset \emph on v2 \emph default , \emph on \begin_inset space ~ \end_inset \emph default ...) \series default The first form evaluates to the location of the minimum of all values in the block marked by the corners pointed to by \emph on l1 \emph default and \emph on l2 \emph default . Note that the empty cell is equal to 0, 0.0 and "", so if the first minimum is an empty cell, the result will be a pointer to this cell, too. If you are not interested in the location of the minimum but the value itself, use @(min( \emph on l1 \emph default , \emph on l2 \emph default )). The second form simply returns the smallest of the specified values, returning an error if it encounters two that are not comparable (like a string and an integer). \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default n \series medium ([location \emph on \begin_inset space ~ \end_inset l1 \emph default [, \begin_inset space ~ \end_inset location \emph on \begin_inset space ~ \end_inset l2 \emph default ]) \emph on \begin_inset space ~ \end_inset \emph default | \emph on \begin_inset space ~ \end_inset \series default \emph default n \series medium ( \family roman \emph on v1, \family default \begin_inset space ~ \end_inset v2, \begin_inset space ~ \end_inset ... \emph default ) \series default The first form evaluates to the number of non-empty cells in the block with corners at location \emph on s l1 \emph default and \emph on l2 \emph default . Location \emph on l2 \emph default defaults to \emph on l1 \emph default ; i.e., with a single location argument \family sans \series bold n \family default \series medium ( \family sans \series default \emph on l1 \family default \series medium \emph default ) \series default just tests whether the cell at \emph on l1 \emph default is empty. Location \emph on l1 \emph default defaults to the current location. The second form simply returns the number of its arguments which are nonempty. \end_layout \begin_layout Description number \series medium [([bool|empty|int|float|string \emph on \begin_inset space ~ \end_inset x \emph default ])] \series default Converts its argument, which defaults to the value of the current cell, to the most appropriate number type. Thus, it leaves ints and floats alone, converts boolean values to integers 1 or 0, converts empty to integer 0, and converts numeric strings to ints if they don't have a decimal point and floats if they do. Without parentheses, acts as a keyword for \family sans \series bold is \series default () \family default , abbreviating the combination of float, int, and empty. \end_layout \begin_layout Description operator A keyword indicating the \begin_inset Quotes eld \end_inset operator \begin_inset Quotes erd \end_inset token type, representing symbols like parentheses, plus signs, commas, etc. \end_layout \begin_layout Description poly \series medium (float|integer \emph on \begin_inset space ~ \end_inset x \emph default , \begin_inset space ~ \end_inset float|integer \emph on \begin_inset space ~ \end_inset cn \emph default [, \begin_inset space ~ \end_inset ...]) \series default evaluates the polynomial \emph on \begin_inset Formula $c_{n}\cdot x^{n}+\ldots+c_{0}\cdot x^{0}$ \end_inset \emph default . \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default precision \series medium (int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to a style token in which the precision is set to \emph on x \emph default (and no other fields are set). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default rad2deg \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the radians that are equivalent to \emph on x \emph default degrees. \end_layout \begin_layout Description right \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] displacement by one cell in the positive \series default \emph on x \emph default direction; see the fuller description at \family sans \series bold above \series default . \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default rnd \series medium () \series default evaluates to a pseudo-random number between 0.0 and 1.0, changing each time the expression is evaluated. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default round \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) evaluates to the argument \series default \emph on x \emph default rounded to an integral value. Unless the system floating-point rounding direction has been changed, this will be the integral value nearest to \emph on x \emph default . \end_layout \begin_layout Description scientific Used as a keyword argument to the string() function; listed here to record that this identifier may not be used as a cell label. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default shadowed \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the shadowed property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default sin \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the sine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default sinh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the hyperbolic sine of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default sqrt \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the square root of \emph on x \emph default . \end_layout \begin_layout Description \series medium string \begin_inset space ~ \end_inset \series default strftime \series medium (string \emph on \begin_inset space ~ \end_inset f \emph default \begin_inset space ~ \end_inset [, \begin_inset space ~ \end_inset integer \emph on \begin_inset space ~ \end_inset t \emph default ]) \series default evaluates to the time \emph on t \emph default formatted according to the format specified in \emph on f \emph default . Times in \emph on t \emph default are counted in seconds since epoch (1970-1-1 0:00). If \emph on t \emph default is empty or 0, the actual time is used. For the format specifications consult the man page of your c library, strftime (3). Example: \emph on @(now)=int(strftime("%s")) \emph default sets the field with label now to the actual time. \end_layout \begin_layout Description \series medium string \begin_inset space ~ \end_inset \series default string \series medium ( \emph on x \emph default [, \begin_inset space ~ \end_inset [integer \emph on \begin_inset space ~ \end_inset precision \emph default ][, \begin_inset space ~ \end_inset \emph on format \emph default ]]) \series default evaluates to the string representation of its first argument. The optional second argument gives the precision used for converting floating point numbers to string form. The optional third argument may be one of the keywords \begin_inset Quotes eld \end_inset decimal \begin_inset Quotes erd \end_inset , \begin_inset Quotes eld \end_inset scientific \begin_inset Quotes erd \end_inset , \begin_inset Quotes eld \end_inset compact \begin_inset Quotes erd \end_inset , or \begin_inset Quotes eld \end_inset hexact \begin_inset Quotes erd \end_inset , controlling the format for converting floating point numbers to string form. If the optional arguments are not specified, current defaults are used. \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default strptime \series medium (string \emph on \begin_inset space ~ \end_inset f \emph default , \begin_inset space ~ \end_inset string \emph on \begin_inset space ~ \end_inset datetime \emph default ) \series default evaluates to the seconds since epoch (1970-1-1 0:00) of the \emph on datetime \emph default string, parsed according to the format specified in \emph on f \emph default . For the format specifications consult the man page of your c library, strptime (3). \end_layout \begin_layout Description \series medium style \begin_inset space ~ \end_inset \series default style \series medium [([ \emph on x \emph default ])] \series default attempts to convert \emph on x \emph default to a style; this currently only succeeds if \emph on x \emph default already is a style; or if it is a location, it extracts the current style of that location. \emph on x \emph default defaults to the current location. Without parentheses as a bare word, \family sans \series bold style \family default \series default is a keyword used for example by \family sans \series bold is \family default \series default () to test the type of an entity. \end_layout \begin_layout Description \series medium string \begin_inset space ~ \end_inset \series default substr \series medium (string \emph on \begin_inset space ~ \end_inset s, \begin_inset space ~ \end_inset \emph default integer \emph on \begin_inset space ~ \end_inset x \begin_inset space ~ \end_inset \emph default [,integer \emph on \begin_inset space ~ \end_inset y \emph default ]) \series default evaluates to the substring of \emph on s \emph default between \emph on x \emph default and \emph on y \emph default , which start at 0. If is omitted, the substring proceeds to the end of the string. \end_layout \begin_layout Description sum \series medium (location \emph on \begin_inset space ~ \end_inset l1 \emph default , \begin_inset space ~ \end_inset location \emph on \begin_inset space ~ \end_inset l2 \emph default ) \emph on \begin_inset space ~ \end_inset \emph default | \emph on \begin_inset space ~ \end_inset \series default \emph default sum \series medium ( \family roman \emph on v1, \family default \begin_inset space ~ \end_inset \family roman v2, \family default \begin_inset space ~ \end_inset \family roman ... \emph default ) \family default \series default The first form evaluates to the sum of all values in the block with corners at locations \emph on l1 \emph default and \emph on l2 \emph default . The second form simply adds all of its arguments. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default tan \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the tangent of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default tanh \series medium (float|int \emph on \begin_inset space ~ \end_inset x \emph default ) \series default evaluates to the hyperbolic tangent of \emph on x \emph default , where \emph on x \emph default is given in radians. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default tau \series medium [()] \series default evaluates to the circle constant \begin_inset Formula $\tau$ \end_inset , the ratio of circumference to radius of any circle. (Note \begin_inset Formula $\tau=2\pi$ \end_inset .) \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default time \series medium [()] \begin_inset ERT status open \begin_layout Plain Layout \end_layout \end_inset \series default each time this expression is evaluated, it gives the time in seconds since the epoch. \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default transparent \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the transparent property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description \series medium boolean \begin_inset space ~ \end_inset \series default true represents the true Boolean value. \end_layout \begin_layout Description \series medium float \begin_inset space ~ \end_inset \series default trunc \series medium (float \emph on \begin_inset space ~ \end_inset x \emph default ) evaluates to the integer part of \series default \emph on x \emph default in floating-point form; generally this should be the same as \emph on x - \emph default frac( \emph on x \emph default ). \end_layout \begin_layout Description \series medium style \emph on \begin_inset space ~ \end_inset \series default \emph default underline \series medium ([bool \emph on \begin_inset space ~ \end_inset b \emph default ]) \series default evaluates to a style token with the underline property set to \emph on b \emph default , which defaults to true (and no other fields set). \end_layout \begin_layout Description up \series medium [([location \emph on \begin_inset space ~ \end_inset l \emph default ])] displacement by one cell in the negative \series default \emph on y \emph default direction; see the fuller description at \family sans \series bold above \series default .) \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default x \series medium ([location \emph on \begin_inset space ~ \end_inset l \emph default ]) \series default \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default y \series medium ([location \emph on \begin_inset space ~ \end_inset l \emph default ]) \series default \end_layout \begin_layout Description \series medium int \begin_inset space ~ \end_inset \series default z \series medium ([location \emph on \begin_inset space ~ \end_inset l \emph default ]) \series default evaluate to the \emph on x \emph default , \emph on y \emph default and \emph on z \emph default position of the given location, of the currently updated cell if none is given. These functions are usually used in combination with the @ function for obtaining information from other cells, but see also the convenience functions \family sans \series bold R \series default () \family default and \family sans \series bold D \series default () \family default for relative references. \end_layout \begin_layout Subsection Expression Grammar \end_layout \begin_layout Description digit::= \family typewriter 0 \family default | .. | \family typewriter 9 \end_layout \begin_layout Description hex_digit::= \family typewriter 0 \family default | .. | \family typewriter 9 \family default | \family typewriter a \family default | .. | \family typewriter f \end_layout \begin_layout Description octal_digit::= \family typewriter 0 \family default | .. | \family typewriter 7 \end_layout \begin_layout Description decimal_integer::= \emph on digit \emph default { \emph on digit \emph default } \end_layout \begin_layout Description hex_integer::= \family typewriter 0x \family default \emph on hex_digit \emph default { \emph on hexdigit \emph default } \end_layout \begin_layout Description octal_integer::= \family typewriter 0 \family default \emph on octal_digit \emph default { \emph on octdigit \emph default } \end_layout \begin_layout Description integer::= \emph on decimal_integer \emph default | \emph on hex_integer \emph default | \emph on octal_integer \end_layout \begin_layout Description float::= \emph on digit \emph default { \emph on digit \emph default } [ \family typewriter . \family default ] { \emph on digit \emph default } [ \family typewriter e \family default | \family typewriter E \family default [ \family typewriter + \family default | \family typewriter - \family default ] \emph on digit \emph default { \emph on digit \emph default } ] \end_layout \begin_layout Description quoted_character::= \emph on \backslash any_character \end_layout \begin_layout Description character::= \emph on any_character \emph default | \emph on quoted_character \end_layout \begin_layout Description string::= \family typewriter " \family default { \emph on character \emph default } \family typewriter " \end_layout \begin_layout Description identifier_character::= \family typewriter _ \family default | \family typewriter @ \family default | \family typewriter & \family default | \family typewriter . \family default | \family typewriter $ \family default | \emph on alpha_character \end_layout \begin_layout Description identifier::= \emph on identifier_character \emph default { \emph on identifier_character \emph default | \emph on digit \emph default } \end_layout \begin_layout Description function::= \emph on identifier \emph default [ \family typewriter ( \family default [ \emph on term \emph default ] { \family typewriter , \family default [ \emph on term \emph default ] } \family typewriter ) \family default ] \end_layout \begin_layout Description label::= \emph on identifier \end_layout \begin_layout Description parenterm::= \family typewriter ( \family default \emph on term \emph default \family typewriter ) \end_layout \begin_layout Description negterm::= \family typewriter - \family default \emph on primary \end_layout \begin_layout Description primary::= \emph on function \emph default | \emph on label \emph default | \emph on parenterm \emph default | \emph on negterm \end_layout \begin_layout Description powterm::= [ \family typewriter - \family default ] \emph on primary \emph default { \family typewriter ‸ \family default \emph on primary \emph default } \end_layout \begin_layout Description mathterm::= \emph on powterm \emph default { \family typewriter / \family default | \family typewriter * \family default | \family typewriter % \family default \emph on powterm \emph default } \end_layout \begin_layout Description factor::= \emph on mathterm \emph default { \family typewriter + \family default | \family typewriter - \family default \emph on mathterm \emph default } \end_layout \begin_layout Description relterm::= \emph on factor \emph default { \family typewriter < \family default | \family typewriter <= \family default | \family typewriter >= \family default | \family typewriter > \family default | \family typewriter == \family default | \family typewriter != \family default \emph on factor \emph default } \end_layout \begin_layout Description conjterm::= \emph on relterm \family sans \emph default { \family typewriter and \family sans \family default \emph on relterm \family sans \emph default } \end_layout \begin_layout Description term::= \emph on conjterm \family sans \emph default { \family typewriter or \family sans \family default \emph on conjterm \family sans \emph default } \end_layout \begin_layout Subsection Implementation notes \end_layout \begin_layout Standard Note that the implementation of a function can tell the difference between whether it is called with parentheses and no arguments, like \begin_inset Quotes eld \end_inset func() \begin_inset Quotes erd \end_inset , or called without parentheses at all, like \begin_inset Quotes eld \end_inset func \begin_inset Quotes erd \end_inset – in the former case it receives an argument count of 0, and in the latter an argument count of -1. So the same symbol can have different semantics depending on which way it is called. In most cases such a difference is counterintuitive, but it seems to work fairly well for the directional \begin_inset Quotes eld \end_inset constants, \begin_inset Quotes erd \end_inset i.e. bare \begin_inset Quotes eld \end_inset left \begin_inset Quotes erd \end_inset is the displacement &(-1,0,0), whereas left() is the location one to the left. The no-parentheses form is also useful for constants like \begin_inset Quotes eld \end_inset e \begin_inset Quotes erd \end_inset and \begin_inset Quotes eld \end_inset tau \begin_inset Quotes erd \end_inset , and it is also used, for example, to allow the names of the functions \begin_inset Quotes eld \end_inset floor \begin_inset Quotes erd \end_inset , \begin_inset Quotes eld \end_inset round \begin_inset Quotes erd \end_inset , etc. to be used as keywords for the int() function. \end_layout \begin_layout Standard Note also that some functions are actually implemented as \emph on macros \emph default , which are just like functions but receive their arguments unevaluated. The difference is meant to be transparent to usage of the function, so it is not mentioned elsewhere in this documentation. However, the macro facility is necessary when the function would need to control the evaluation of the arguments, as in the short-circuiting logical operations, or takes an expression as an argument, say to evaluate it on other cells. \end_layout \begin_layout Section Frequently Asked Questions \end_layout \begin_layout Subsection Can I see some examples of teapot in action? \end_layout \begin_layout Standard Sure, the standard distribution comes with an examples folder containing several spreadsheet files illustrating some of \noun on teapot \noun default 's features. Each sheet is accompanied by a README file with a brief explanation of what is going on in the file. \end_layout \begin_layout Subsection Why is 1.0 unequal 1.0? \end_layout \begin_layout Standard If your machine uses binary floating point arithmetic, and chances are that it does, you may eventually find yourself in the following situation: \end_layout \begin_layout Quote 0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1+0.1 \end_layout \begin_layout Standard You expect to see 1.0 as result, and indeed that is what you get. Now you compare this result to the constant 1.0, but surprisingly for many users, the result is 0. Appearantly, 1.0 is unequal 1.0 for \noun on teapot \noun default . \end_layout \begin_layout Standard This is not a bug in \noun on teapot \noun default , in fact it is not a bug at all. The problem is, that 0.1 (1.0/10.0) does not have an exact representation in binary floating point arithmetic, similar to how 1.0/3.0 does not have an exact representation in decimal arithmetic (or binary, for that matter). As such, a value very close to 0.1 is used, but when displaying it, it will be rounded to 0.1. The result is obvious, adding this number which is a little different from 0.1 ten times leads to a result very close to but not quite 1.0. Since it is so close, displaying it rounded to only a few digits precision shows 1.0. \end_layout \begin_layout Standard To solve the comparison problem, \noun on teapot \noun default has the operator \family typewriter ~= \family default (in contrast to the operator ==), which compares two floating point values apart from the last significant bit. Use this operator to compare the two values from above and the result will be 1, meaning they are about equal. Don't assume that a number which can be expressed with a finite number of decimal digits will be represented exactly in binary floating point arithmetic. \end_layout \begin_layout Subsection How do I hide intermediate results? \end_layout \begin_layout Standard If you used flat, two-dimensional spread sheets before, you are probably used to hidden cells which contain intermediate results, global constants, scratch areas and the like. \noun on teapot \noun default has no way to hide cells, but you have three dimensions. Just use one or more layers for such cells and give each cell a label in order to reference and find it easily. \end_layout \begin_layout Subsection Why is there no conditional evaluation? \end_layout \begin_layout Standard There is no special operator or function for conditional evaluation. I could add one easily, but then next someone would ask for loops and someone else for user-defined functions, variables and so on. If you need a programming language, you know where to find it. \end_layout \begin_layout Standard But don't worry. The answer is, that conditional evaluation comes for free with \noun on teapot \noun default 's orthogonal cell addressing. As an example, depending on the cell labelled \family typewriter X \family default being negative or not, you want the result to be the string \family typewriter "BAD \family default or \family typewriter "GOOD" \family default . This is a solution: \end_layout \begin_layout Quote eval(BAD + &((@(X)>=0),0,0)) \end_layout \begin_layout Standard Note this is making use of the fact that you can add locations in the natural way. The cell labelled \family typewriter BAD \family default contains the string \family typewriter "BAD" \family default , its right neighbour contains the string \family typewriter "GOOD" \family default . If you have nested conditions, you could weight them with 1, 2, 4 and so on to address a bigger range of cells. Alternatively, you could make use of all three dimensions for nested conditions. \end_layout \begin_layout Standard Sometimes you can also get conditional-like behavior using the logical expressio ns. Suppose you want to use the value of the cell labeled \family sans OPTION \family default if it is non-empty and non-zero, and the value of the cell labeled \family sans DEFAULT \family default otherwise. Since the empty and zero values are considered false, but the logical operators short-circuit and preserve the original values of their arguments, you can achieve this with: \end_layout \begin_layout Standard \family sans @(OPTION) or @(DEFAULT) \end_layout \begin_layout Subsection But my references don't do the right thing when I move or copy them! \end_layout \begin_layout Standard If you are used to other spreadsheets, you have probably noticed that references like \family sans @(0,1,0) \family default (for the start of the second row) or \family sans @(MYDATA) \family default (for a location) are \begin_inset Quotes eld \end_inset absolute \begin_inset Quotes erd \end_inset – they always refer to the same location no matter where in the spreadsheet they occur. And of course sometimes it is convenient, for example when making a column of consecutive numbers, to refer to nearby cells in a relative manner, either with say \family sans @(x(),y()-1,z())+1 \family default or \family sans @(&()+&(0,-1,0))+1 \family default or \family sans R(,-1)+1 \family default or up()+1 to add one to the value of the cell which is one up from the current cell (all of these expressions work). Then you can fill that expression downwards and get your column of consecutive numbers. \end_layout \begin_layout Standard But these sorts of relative expressions only keep working if the cells move together with the cells they refer to. If for example you have a row of cells that are all referring to the row above with a relative reference (like \family sans R(,-1) \family default ) and you insert another row in between them, your references will be all messed up. There is value to \begin_inset Quotes eld \end_inset Excel-style \begin_inset Quotes erd \end_inset references that can be used to fill and which also can move around while still just \begin_inset Quotes eld \end_inset referring to what you want. \begin_inset Quotes erd \end_inset \end_layout \begin_layout Standard To provide for this need, \noun on teapot \noun default has a function \family sans \series bold X \series default (SRC, REF) \family default to retrieve the value of the cell labeled \family sans SRC \family default \bar under from \bar default the cell labeled \family sans REF \family default . If the so-labeled cells move around (either the source or the reference) it will still work. This is not particularly useful in and of itself; what makes it useful is that from a cell other than \family sans REF \family default , it gives you the value of the cell that stands in the same relation to \family sans SRC \family default as that cell stands to \family sans REF \family default . So in the cell to the right of \family sans REF \family default , it will give you the value of the cell to the right of \family sans SRC \family default ; in the cell below, it gives you the cell below \family sans SRC \family default , etc. Now you can fill a block of cells around \family sans REF \family default with formulas contaning \family sans X(SRC,REF) \family default and they will refer to the analogous block of cells around \family sans SRC \family default . \end_layout \begin_layout Standard Sometimes you want to make this kind of reference and fix one of the coordinates but not the others; \family sans X() \family default has optional flags for this, as well, so that \family sans X(SRC,REF,,,fix) \family default will always be on the same layer as \family sans SRC \family default regardless of what layer it is called from or what layer \family sans REF \family default is on. (This flag roughly corresponds to supplying the \begin_inset Quotes eld \end_inset $ \begin_inset Quotes erd \end_inset in an Excel cell reference.) Thus \family sans X(SRC,REF,fix,fix,fix) \family default is just \family sans @(SRC) \family default , but the intent of the latter is much clearer. \end_layout \begin_layout Standard You might ask as a follow-up question: Isn't \family sans X(SRC, REF) \family default much more cumbersome than just referring to cells by coordinate and then letting Excel \begin_inset Quotes eld \end_inset do the right thing \begin_inset Quotes erd \end_inset as you copy and move either that formula or the referred-to data? The response to this is that in a typical spreadsheet, there are only a small number of fundamental references, and all other references derive from them in this way. So you generally only need a few labels, and by taking just a little extra time to apply those labels and refer to them in initial formulas, you are making the semantics of your references much clearer and in essence documenting them within your spreadsheet. This modicum of extra effort will therefore be repaid in an easier-to-use, easier-to-understand, and easier-to-maintain and update spreadsheet. \end_layout \end_body \end_document