[Indigo]<CaminoReal>CaminoRealDoc.tioga!15

CaminoRealDoc.tioga

Dennis Arnon, December 15, 1986 10:26:03 am PST

CaminoReal

CEDAR 7.0 — FOR INTERNAL XEROX USE ONLY

CaminoReal

by Dennis Arnon and Carl Waldspurger

Abstract: CaminoReal is an environment for several kinds of manipulations of mathematical expressions: (1) interactive, syntax-directed, two-dimensional, WYSIWYG editing, (2) insertion into a Tioga document, and (3) algebraic manipulation.

Created by: Dennis Arnon and Carl Waldspurger

Maintained by: Dennis Arnon <Arnon.pa>

Keywords: Math, Technical Documents, Math Editor, Mathematical Expressions, WYSIWYG, AlgebraStructures, Computer Algebra, Symbolic Mathematical Computation, Polynomials, Matrices

XEROX Xerox Corporation
Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304

For Internal Xerox Use Only

There is no 'royal road' to geometry.

Euclid, said to Ptolemy I

1. Preface

To see the mathematical expressions in this document, you need to start up CaminoReal. To do so:

% bringover -p [Cedar]<CedarChest7.0>Top>CaminoReal.df

% CaminoReal

A single, iconic CaminoReal viewer should appear.

After doing the above, there is a registered CaminoReal command; typing "CaminoReal" again to a command tool will get you another (iconic) CaminoReal viewer.

In the following, double-starred items (**) can be ignored by the general user.

2. Introduction

There are computer algebra systems (Macsyma, Maple, Reduce, Scratchpad, SMP), and there are high quality document formatting systems that support mathematical expressions (Eqn-Troff, TEX, INFOR, VORTEX). There is still no adequate support for the working scientist who needs "living" notebooks and technical papers. Such a worker typically wants to examine a document, edit or algebraically manipulate expressions therein, and save new expressions back into it. Not only should editing and algebra serve documents, but conversely: it would be nice to be able to make high-quality logs of algebra sessions.

CaminoReal is a prototype system for the integration of documents, editing, and algebra. It supports interactive, syntax-directed, two-dimensional, WYSIWYG editing of mathematical expressions, placing/fetching such expressions in/from Tioga documents, and algebraic manipulation of expressions. The algebraic manipulation is based on an object-oriented paradigm that supports generic procedures (this is AlgebraStructures, a separate CedarChest package). For example, one can easily create and do simple arithmetic on matrices of polynomials with complex number coefficients, or matrices of such matrices, etc.

It is perhaps most natural to view the algebra system as resident in the editor, i.e. algebraic manipulation of expressions is just a kind of editing of expressions. The current algebra functionality is a small Cedar package. [In the future we hope to offer access to other algebra systems running in Unix or Lisp. This may be done either by extending the current user interface paradigm to incorporate functionality provided by the foreign system, or by providing a new user interface for algebraic manipulation that allowa the (necessarily knowledgeable) user to work with the foreign system in some facsimile of its own interface paradigm] .

The new user should get some acquaintance with the terminology of Section 3. Sections 4-8 deal with editing of expressions, and moving expressions back and forth between CaminoReal and Tioga documents. Sections 9-12 deal with doing algebra. Section 13 discusses "computed documents", a methodology for spreadsheets/active documents that involve bot algebra and documents. Section 14 discusses miscellaneous useful buttons.

3. The Basics of Editing Expressions

The Basic Paradigm

It is a syntax-directed editor. You replace a selected placeholder with template, which may itself contain placeholders. Templates are chosen either from menus or the keyboard.

How to use the BiScrollers

For the vertical scroll bar, left mouse click means "move it up", right means "move it down", middle means nothing. The closer to the top of the scroll bar the mouse cursor is when you click the mouse, the less motion there is; the closer to the bottom the mouse cursor is, the more motion.

For the horizontal scroll bar, left mouse click means "move it left", right means "move it right", middle means nothing. The closer to the left of the scroll bar the mouse cursor is when you click the mouse, the less motion there is; the closer to the right the mouse cursor is, the more motion.

4. Terminology for Editing Expressions

PlaceHolder:

A placeholder is an empty Expression which needs to be filled in. It is similar in appearance and function to placeholders () in Tioga.

Replace:

"Replace old with new" means to delete old and insert new in its place.

Wrap:

"Wrap template foo around bar" means to use bar to fill in a placeholder in template foo. After the wrap, bar is a subExpression of foo.

5. Selecting Expressions

What can you select?

CaminoReal considers each class of Expression (e.g. summation, integral) to be composed of Arguments and Symbols. An Argument is a "subExpression", i.e. something which is recursively an Expression; a Symbol is a glyph (e.g. the sigma symbol, the integral sign) which is part of the rendering of that notation, but is not itself an Expression. The basic rule is that you can select Arguments, but not Symbols.

If for example you are editing a summation Expression, you can select any of the summation's subExpressions (lowerlimit, upperlimit, summand) or the entire summation Expression. You cannot, however, select the sigma symbol by itself in the summation (clicking on the sigma will actually select the entire summation Expression).

Expressions can be thought of as trees (with operators at nodes and atoms at leaves), CaminoReal provides ways to move through the Expression tree with a minimum of fuss. Operations are available which allow you to: extend a selection to include its parent Expression (moving up the tree), narrow a selection to a child Expression (moving down the tree), and change a selection to select a sibling Expression (same level in tree). Thus, both CaminoReal and Tioga have hierarchical tree-like structures and commands for selecting subtrees and leaves.

There are four selection types, similar in appearance and function to Tioga selections:

Primary selection:

Selected Expression is highlighted by rendering it white on black, which is inverted from the normal black on white (just like Tioga).

Copy selection:

Selected Expression is highlighted in dark gray.

Move selection:

Selected Expression is highlighted in light gray.

Keyboard (KB) selection:

This selection type cannot be applied by the user. The selected Expression is highlighted using horizontal gray lines. This selection type is automatically invoked when there is an active keyboard entry for an atom (e.g. a number or a variable). Its purpose is mostly as an indicator. However, when template wrapping is invoked from the keyboard, an active keyboard selection becomes the primary selection.

How can you select?

You can select Expressions using either the mouse or keyboard. To select with the mouse, simply point at the Expression you wish to select and click the appropriate button. The selected Expression will be the smallest Expression (greatest depth in tree) which contains the point specified by the mouse. If you think of each Expression as being enclosed by a bounding box, this is the Expression enclosed by the smallest box which contains the point specified by the mouse.

The following mappings are currently used:

Single Clicks:

Red => Primary Select

Shift Red => Copy Select

Ctrl Red => Move Select

Double Clicks:

Red => Extend Primary Selection to Parent

Shift Red => Extend Copy Selection to Parent

Ctrl Red => Extend Move Selection to Parent

Keyboard selection actions:

DEL, Ctrl-D => Delete Primary Selection

Ctrl-I => Primary select entire current viewer contents

Ctrl-P, '), '], '} => Primary Select Parent of current Primary or KB selection

Ctrl-K => Primary Select Child (das Kind) of current Primary or KB selection

Ctrl-L, ', => Primary Select Sibling (Lateral movement) of current Primary or KB selection

Ctrl-M => convert KB selection to Primary (rarely needed)

6. Entering Expressions

Using Menus:

ReplaceWithObject:

Replaces the primary selection with a "mathematical object". The type of object is chosen from a pop-up menu. Depending on the type of object, the actual Expression is either given a default value (rational, complex), obtained from additional pop-up menus, or from a Tioga viewer selection (variable, bool, integer, real). For example, "ReplaceWithObject Integer" tries to get an integer from an active text selection, and "ReplaceWithObject GreekVariable" provides a pop-up menu of choices for the variable.

"ReplaceWithObject Variable" may allow you to get characters you want into an Expression when no other way seems available. Whatever is in the active text (Tioga) selection, i.e. any valid rope, will be picked up and stuffed when you bug the "Variable" entry of the pop-up menu.

For sets, sequences, vectors, matrices, and blocks (see below for defn of block), the dimensions are chosen from pop-up menus. (note: CaminoReal can support arbitrarily big matrices, but the current user interface restricts the maximum dimension to be 10 x 10.)

The matrix is initialized by setting all elements = 0. This is useful when entering sparse matrices, and isn't really a hindarance when you aren't.

ReplaceWithOperator:

Brings up a pop-up menu listing classes of operators. You select a class of operators from these menus, and then get another pop-up menu listing the actual templates. Then the primary selection is replaced by the template for the operator you have selected.

WrapWithOperator:

Similar to ReplaceWithOperator, but wraps a template around the primary selection instead of replacing it. In other words, the primary selection is used to fill in a placeholder in the template. This placeholder is usually the first (e.g. "a" in "a + b") or most important (e.g. integrand in integration) argument to the template. (Yes, of course the "hot" argument should be highlighted in the pop-up menu, but unfortunately the pop-up menus package can't switch fonts between chars or even selections. Other alternatives looked bad.)

Using the keyboard:

CaminoReal allows keyboard input for some of the most common expression types.

Integer, Real, and Variable atoms can be typed directly into a (Primary- or Keyboard-)selected Expression. As mentioned in the section on selections, the active Keyboard selection will be selected and highlighted using horizontal gray lines. This selection is terminated as soon as a Primary selection is made or any editing function is invoked (you can always select outside of an Expression to get rid of the Keyboard selection). A Real number must begin with a digit (e.g. 0), and not just a decimal point.

Typing operator characters into a selected Expression performs a template wrap around the currently active Keyboard or Primary selection. Currently supported keys, with their semantics, are:

'+ => binary sum

'— => unary difference

'- => binary negation

'* => binary product

'/ => binary fraction

'^ => binary pow

'← => binary subscript

'? => binary function of one argument

'( => unary parentheses

'{ => unary curlyBrackets

'! => unary factorial

'$ => unary exists

'@ => unary forAll

'& => binary and

'| => binary or

'~ => unary not

'= => binary eqFormula

'> => binary gtFormula

'< => binary ltFormula

'# => binary notEqFormula

Ctrl-P, '), '], '} => Primary Select the Parent of the current Keyboard or Primary Selection.

Ctrl-I => Primary Select entire Current Expression (entire contents of the viewer in which mouse sits)

Ctrl-K => Primary Select the Hot Child (Kind) of current Primary Selection.

Ctrl-L, ', => Primary Select sibling (Lateral movement) of current Keyboard or Primary Selection.

Ctrl-H => undo previous keystroke; Primary Select entire Current Expression

Ctrl-X => swap Primary and Move selections (can't really use in keyboard input, since mouse required to make Move selection)

** Ctrl-M => Convert the Keyboard Selection into the Primary Selection (should not be needed)

For the binary operators, this gives "pseudo-infix" input. For example, to enter "a + b", simply select a placeholder, then type "a", "+", "b". What is really going on is that the operation "+" is wrapped around the Expression "a", and the placeholder for the augend is auto-selected. Typing the "b" fills in the augend placeholder. The ctrl-P "select parent" operation is very useful for keyboard input to avoid switching beteen the keyboard and the mouse. For example, to enter

use the keystrokes "x", "^", "2", ctrl—P, "+", "1", ctrl-P, "=", "0".

For the unary operators, the input paradigm is "prefix" or "postfix", depending on the operator. E.g. to enter

type the keystrokes "(", "$", "x".

7. Editing Expressions

Copy

Make a Primary selection, hold down the Shift key, make a Copy selection, release Shift, and the Primary selection will be replaced by the Copy selection. The Copy selection is unchanged.

Move

Make a Primary selection, hold down the Control key, make a Move selection, release Control, and the Primary selection will be replaced by the Move selection. The Move selection is replaced by a Placeholder.

Swap

Intended to mimic Tioga's swap. Make a Primary selection, hold down Control, hit and release the "X" key (continue holding down Control) make a Move selection, release the Control key, and the Primary and Move selections will be interchanged.

The selections (i.e. operands) for Copy, Move, and Swap can either lie within a single Camino viewer, or in two different Camino viewers. Note that Copy, Move, and Swap in CaminoReal are performed very much as in Tioga.

8. Expressions and Tioga Documents I

ToTioga button

To put an expression into a Tioga doc, make a primary selection in the Camino viewer, make a selection in the Tioga doc, and bug "ToTioga". The expression will be placed in the document immediately preceding the Tioga selection. The value in the ScratchPad will become its PointSize in the document. 20.0 is a good initial choice.

The ScratchPad must either contain a REAL constant, or be empty, when you do this. If nonempty, the value it contains will become the PointSize of the expression in the document. 20.0 is the default if the ScratchPad is empty, and in general is a good initial choice.

Note that scaling an expression in a Camino viewer (with the Scale button) has no bearing on the PointSize an expression gets when put into a Tioga document; only the value in the ScratchPad controls that.

FromTioga button

To fetch an expression from a Tioga doc, make a primary selection in the Camino viewer, (character) select the expression in the Tioga doc, and bug "FromTioga". The ScratchPad will get set to the PointSize.

SetPtSize button

To adjust the PointSize of an expression in a document, put the value you want in the ScratchPad, (character) select the expr in the doc, and bug "SetPtSize".

Examples

Here are some sample paragraphs containing Expressions. This is a plain line of text which happens to be above a Expression:

This is a plain line of text which happens to be below a Expression. The following is a large Expression:

This line is immediately below the large Expression.

Here are some various sizes of Expressions, obtained by setting PointSize's to the various values (i.e. 20, 30, 40):

Note that Expressions can easily be moved or copied around in text with Tioga character copy.

Let's place this expression here:

Printing the document

Create an interpress file with the command "TiogaToInterpress <doc>.tioga", followed by an InterpressToPD command (e.g. "InterpressToPD <doc>.interpress raven384" for Stinger); print the resulting pd file. Be sure MeddleArtwork on is in effect when you do the TiogaToInterpress.

This sequence of steps is bundled up in the command file StingerPrint.cm

Further details on expressions in documents **

This discussion assumes that in the "Properties" box of the Edit Tool, you have toggled the "For selected nodes" box so that it becomes "For selected characters".

An Expression in a Tioga document is a character with Properties (see TiogaDoc). Thus if you select an Expression and list its properties, you'll see that it has the Artwork, MeddleExpr, and MeddlePtSize, properties. The way things work is that the value of the Artwork property for each Expression is "MeddleExpr", and the value of its MeddleExpr property is its "Meddle-format rope". The current modus operandi is to move Meddle-format ropes back and forth between the CaminoReal viewer and the characters in the document to which they are attached, with the FromTioga and ToTioga buttons of the Camino viewer

To see one of these Meddle-format rope's, fill in the "Property name" field of the Edit Tool with value "MeddleExpr", select an Expression in a document (e.g. this document), and hit the Get button for Property values.

9. Domains

1. What they are

The Ground Domains are:

Expressions (i.e. general expressions)

Variables

Bools

Integers (Mesa INTs)

Rationals (BigRats)

Reals (Mesa REALs)

Complexes (built from Mesa REALs)

The Domain Structuring Operations are:

SingleSet

FamilyOfSets

Sequences

Vectors

Matrices

Polynomials

2. Creating Domains

Bug the

Working Domain

button in the control panel. You'll get a pop-up menu of choices, including all the Ground Domains and Domain Structuring Operations. You must initially select a Ground Domain; a short name for it (e.g. Z for Integers) will appear in the text viewer next to the Working Domain button.

Matrices

These are rectangular matrices of specified size, whose entries are elements of the current Working Domain. When you select Matrices, you get a pop-up menu to select the size.

Polynomials

For any polynomial, we need to keep track of 'what variables it's a polynomial in'. This is accomplished by associating a variable sequence with the polynomial. This is a sequence of Ropes (the variables). In order for scanning to work, variables should be Cedar identifiers. A variable sequence should be written as comma-separated variables enclosed in parentheses (whitespace ok anywhere except within a variable). For example, "(x,y,z)".

What you do is enter the variable sequence into the ScratchPad, then bug WorkingDomain, and bug Polynomials in the menu. The coefficient domain is what was previously in the "WorkingDomain".

10. Evaluation

This is the most basic way to do algebra. Any Expression can be evaluated; if CaminoReal doesn't know enough algebra to do something interesting with it, it just returns it unevaluated.

The result of an evaluation always belongs to some Domain. General Expressions (denoted MExprs) is the catchall if nothing narrower can be determined.

The semantics of Eval are: To evaluate a function of args (which every non-atomic Expression can be viewed as), we first (recursively) evaluate the arguments, then look for the function as a Method in some Domain (typically the Domain to which the first (evaluated) argument belongs), and apply that Method to the evaluated arguments.

Miscellaneous note: polynomial gcd's are currently done by the SAC-2 package on the Vax (via the Bridge). For uninteresting reasons, you'll get an error if the variables of polynomials whose gcd's you try to compute do not consist entirely of upper case letters.

EvalPrimaryInPlace button

Evaluate the Primary selection and replace it by the result. Domain of the result is shown in the "Result Domain" viewer.

EvalTiogaInPlace button

Evaluate the current CaminoReal Expression selected in a Tioga document, and replace it by the result. Domain of the result is shown in the "Result Domain" viewer.

Evaluation from the keyboard (Control-V)

Control-V evaluates the current Primary selection in place. Same as EvalPrimaryInPlace button, except that the Domain of the result is NOT shown in the "Result Domain" viewer.

Miscellaneous note on polynomial gcd's.

11. Operations

OpPrimaryInPlace button

Evaluate the Primary selection, put up a pop-up menu of operations appropriate for that Domain, get the appropriate number of arguments for the selected operation from CaminoReal selections (e.g. for sum, the second arg is the CaminoReal Copy selection), and replace the Primary selection by the result of the operation.

OpWDinPlace button

Put up a pop-up menu of operations appropriate for the current Working Domain, get the appropriate number of arguments for the selected operation from CaminoReal selections, and replace the Primary selection by the result of the operation.

OpPrimary, OpWD buttons

Put the result in a new CaminoReal viewer instead of replacing Primary Selection.

12. The Environment

Currently there is just one environment in place across all documents and all CaminoReal viewers. Running CaminoReal resets it.

A variable is placed into the environment by evaluating an assignment statement. For example, the evaluation of

will place a variable X into the environment with value X .

KillAll(), KillVariable('x') refer to this environment.

Never say "x ← x"!!! Next time you evaluate x you'll loop.

13. Computed Documents (Expressions and Tioga Documents II)

Blocks

A block is an expression which is simply a sequence of other expressions, and whose value is the value of the last expression. You enter a block into the editor via the ReplaceWithObject button.

MathEval on/off

When the EvalBeforePaint flag is off (the default), CaminoReal Expressions in a Tioga document are painted just as they are stored. When the EvalBeforePaint flag is on, they are evaluated before being painted. This enables Computed Documents.

The commands "MathEval on" and "MathEval off" do the toggling. See the document Own.tioga for an example of a home mortgage calculation sample "computed document".

Expression constructors

sequenceFromIteration[function, variable, start, finish]; Result is a sequence of general expressions. prior value of variable is destroyed; at exit has value finish

matrixFromRowSequence[rowSequence]; rowSequence is a Sequence of Vectors over any Domain(s), all of same dimension; Result is a nRows x nCols matrix of general expressions, where nRows is length of rowSequence, and nCols is dimension of each row. The elements of the output matrix are obtained by evaluation of (the Exprs obtained) from the appropriate vector elements.

iteration[function, variable, start, finish]; Result is value of last iteration. prior value of variable is destroyed; at exit has value finish

squareMatrixFromFunction[function, rowIndex, colIndex, size]; Result is a size x size matrix of general expressions. prior values of rowIndex and colIndex are destroyed; at exit they have value size

See the document Dealer.form for examples of blocks, and these constructors.

14. Other Menu Buttons

Scale

Scales the contents of the viewer:

red => scale by factor of 1.5 (zoom)

yellow => remove all scaling and return to default size (normal)

blue => scale by factor of 1/1.5 (shrink)

Home

Moves the Expression to its default location at the lower left-hand corner of the viewer. This is useful if you used the bi-scrollers and "lost" the Expression somewhereon the infinite plane.

SelectPrimary

Sets the primary selection to be the entire Current Expression. Note that SelectPrimary can also be done from the keyboard with Control-I.

SelectCopy

Sets the copy selection to be the entire Current Expression.

Undo

Undoes the last operation which changed the contents of the viewer. Undo in CaminoReal, unlike Tioga, undoes the last change to an individual viewer, not to the global collection of active viewers (There are pros and cons to this approach). Undo sets the primary selection to the entire Current Expression. Note that Undo can also be done from the keyboard with either Control-H or Backspace.

SetName

Sets the name of this Item to the contents of the ScratchPad.

NewItem

Get a new CaminoReal viewer.

15. Acknowledgements

Thanks to Rick Beach and Michael Plass for enlightenment on Tioga and other matters. Thanks to Ken Pier for the "point and stuff" part of the CaminoReal-Tioga interface. Thanks to Christian LeCocq for the BridgeSubmit package. Thanks to those in the Computer Science Lab at PARC who have used CaminoReal for their documents and computations, and suggested improvements. Thanks to Alan Perlis for inspirational conversations on mathematics and computing.

Appendix - Analysis templates

The recognized names for each template are given, followed by the template itself. For example, to wrap a summation template around the current Keyboard or Primary selection, either select it from the pop up menus given by bugging "WrapWithOperator", or type "?sigma? from the keyboard.

summation, sigma X

integration, int X

indefInt X

dDx X

partialDeriv X

nRadical, nRad X

radical X

limit X

approxEqFormula X

approachesFormula X