[Pixel]<Imaging>Documentation>CaminoRealDoc.tioga!27

CaminoRealDoc.tioga

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

CaminoReal

CEDAR 6.0 — FOR INTERNAL XEROX USE ONLY

CaminoReal

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

0. Prefatory Note

To see the mathematical expressions in this document, begin by carrying out the instructions in Section 2.

Double-starred items (**) can be ignored by the general user.

1. 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 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 14 discusses some rather esoteric data structures pertaining to algebraic curves and surfaces.

See AlgebraStructuresDoc for particulars of the AlgebraStructures algebra system, e.g. relevant information for adding new domains.

2. Getting Started

Bringover -p /Cyan/Imaging/Top/CaminoReal.df. Type "CaminoReal" to a command tool. You will get a viewer named "CaminoRealItem" opened in the left column.

Typing "CaminoReal" again to a command tool will create another CaminoReal viewer.

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.

When the viewer first comes up, you should see a single placeholder. If not, it is probably just out of sight off the bottom of the viewer. Use one or more left mouse clicks near the top of the vertical scroll bar to bring it into view.

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?

You can select any Expression or subExpression.

You cannot select individual symbols in an Expression.

Example:

If you are editing a template for a summation, 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).

Since 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 three (well, really four) selection types, again 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.

Active keyboard selection (KB Selection):

This selection type cannot be applied by the user. The selected Expression

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

variable). Its purpose is mostly as an indicator. However, when template

wrapping is invoked from the keyboard, an active keyboard selection is used

like a primary selection. (yes, I know this isn't so great and should be made more uniform,

but I have a plane to catch - It wouldn't be too hard to fix).

How can you select?

You can select Expressions using either the mouse or keyboard (mostly the mouse).

To select an Expression 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

Blue => Primary Sibling Select

Shift Blue => Primary Child Select

Double Clicks:

Red => Extend Primary Selection to Parent

Shift Red => Extend Copy Selection to Parent

Ctrl Red => Extend Move Selection to Parent

Other:

DEL => Delete Primary Selection

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

6. Entering Expressions

Using Menus:

ReplaceWithAtom:

Replaces the primary selection with an atomic Expression. The type of atom is chosen from a pop-up menu. Depending on the type of atom selected, the atom value is either obtained from additional pop-up menus or from a Tioga viewer selection. For example, "ReplaceWithAtom Integer" tries to get an integer from an active text selection, and "ReplaceWithAtom GreekVariable" provides a pop-up menu of choices for the variable.

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

Replaces the primary selection with an atomic mathematical object, e.g. an integer, or matrix.

For vectors, sequences, and matrices, 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

'— => binary difference

'- => unary negation

'* => binary product

'/ => binary fraction

'^ => binary pow

'← => binary subscript

', => binary list

'? => binary function

'( => unary parentheses

'{ => unary curlyBrackets

'[ => unary squareBrackets

'! => unary factorial

'$ => unary exists

'@ => unary forAll

'& => binary and

'| => binary or

'~ => unary not

'= => binary eqFormula

'> => binary gtFormula

'< => binary ltFormula

'# => binary notEqFormula

Ctrl-P => "select parent"

Ctrl-I => "select entire Current Expression"

Ctrl-K => "select child (das Kind)"

Ctrl-L => "select sibling (Lateral movement)"

Ctrl-H => undo previous keystroke

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

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 X, use the keystrokes "x", "^", "2", ctrl—P, "+", "1", ctrl-P, "=", "0".

For the unary operators, the input paradigm is "prefix". E.g. to enter X, type the keystrokes "x", "$", "(".

(Note: This method is far from ideal. The user should be able to type "soft" parentheses which would elminate the need for most ctrl-P's. This also opens up the can of worms called "operator precedences" and "automatic parentheses generation" which should be considered in the future).

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

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 (30 pt, 20 pt, 15 pt), obtained by setting the Expression's PointSize to the appropriate value (i.e. 30, 20, 15):

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

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

Let's place this expression here:

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.

3. Items, Expressions, Domains, Objects

A Item is just another name for a CaminoReal viewer tool. An Item has a name, displayed in the viewer banner. You can change an items name by typing a new one in the ScratchPad and clicking the SetName menu button. You can get a new Item at any time by bugging the "NewItem" button in an existing Item, or typing "CaminoItem" to a command tool.

An Expression can be displayed and edited, but is not capable of having algebraic manipulations performed on it. Every Expression is attached to some Item; every Item has one and only one (possibly null) Current Expression, which, at any moment, is what you see.

Strictly speaking, a Domain is just a set. Typically the Domains of interest are also algebraic structures, e.g. the integers, 2 x 2 matrices of complex numbers. Associated with any Domain is a certain collection of operations, such as conversion of Domain elements from Ropes or elements of other Domains, and arithmetic.

Abstractly, an Object is an element of a Domain. CaminoReal Objects possess Display Expressions, which we look at to see what Object we've got. Given an arbitrary Expression and an arbitrary Domain, the Expression may or may not be interpretable as an element of that Domain (obviously a Display Expression can always be interpreted as an element of its Object's Domain). In other words, from a given (Expression, Domain) pair we may or may not be able to construct an Object.

Every Object is attached to some Item, and every Item has one and only one (possibly empty) Current Object. The Domain to which an Item's Object belongs is the Item's Object Domain. Items also have a Working Domain, which can be edited at will. A common action is to set an Item's Current Object by interpreting its Current Expression as an element of its Working Domain; this is done by bugging SetObject with the Current Expression being the primary selection ("primary selection" is defined below).

When an Item has a nontrivial Object, it will usually be the case that the Item's Current Expression is the Object's Display Expression, but this is not necessarily so. We may edit the Current Expression, and the changes have no affect on the Current Object until we explicitly request that a new Current Object be established (e.g. by bugging SetObject with the appropriate primary selection (see below) in effect).

9. The Evaluator

This is the most basic way to do algebra.

This is actually a part of the AlgebraStructures package; it is currently in an experimental state. There are two buttons

EvalPrimaryInPlace button

EvalTiogaButtonInPlace button

11. Operating On Objects

We use CaminoReal Selections to indicate operands to operations.

Eval of the first arg gives you its domain.

Once you have a Current Object, bug the OperateObject button to get a list of available operations. The current PrimarySelection is the implicit first operand to any of these.

10. Domains

The ground domains are Bools, Integers (Mesa INTs), Rationals

Bools

Integers

Rationals

Reals

Complexes

Variables

The following are structured domains. Many are just

Matrices

Polynomials

10. Creating Domains

Bug the

Working Domain

button in the control panel. You'll get a pop-up menu of choices. Some of these are Ground Domains, and others are Domain Structuring Operations. The current Ground Domains likely to be of interest to the general user are:

Bools, Colors, FormulaOperators, Integers, Rationals, Reals, Complexes

You must initially select one of these; 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 rings of square 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".

12. Algebra-format Ropes for Objects

The reader may find it a useful exercise, for each of these examples, to create an Item, set its WorkingDomain appropriately, Tioga-select the Algebra-format Rope given below for a sample element of that Domain, bug the OperateWorkingDomain button, and choose the FromLinearRope operation. In each instance, you should get a new Current Object and corresponding Display Expression.

You can always see what CaminoReal thinks is an appropriate Algebra-format Rope for the Primary Selection by bugging the "ToASRope" button.

1. Complex Numbers

Algebra-format Rope: (-38368.0 + 22976.0 i )

Display Expression:

At present, CaminoReal insists that anything that is to be considered a complex number must be created with the complex template from the menu, and hence be displayed in the form X. Thus for example, complex zero must be dealt with as X (or X; the presence or absence of decimal points doesn't matter) and complex one asX. Also, complex numbers with negative imaginary part will appear as in this example: X. Given this rigidity, one can perhaps live with the fact that complex numbers are not enclosed in parenthesis, e.g. here's an example of how CaminoReal currently prints a polynomial in x with complex coefficients: X

2. Polynomials

A polynomial is written as a sequence of terms in the variables of that list. Order of terms doesn't matter. Multiplication is implicit (whitespace between coefficients and variables). Exponentiation is indicated by either "^" or "**". Order of occurrence of variables in a term doesn't matter (no duplicate monomials allowed, however). Error if a variable not in the variable sequence occurs, but not all variables in the list need occur in any given polynomial. Case matters in variables. Order of occurrence of variables in a term doesn't matter.

No simplification currently supported in input, e.g. (x + y)^2 is illegal.

For example, suppose Domain is Polynomials in (x, y, z) over the Rationals.

Algebra-format Rope: x z^33 - 92837498279872983749734 / 33 y**23 + x y z - 1

Display Expression: i

3. Matrices

Domain is 2 x 2 Matrices over Polynomials in (x) over the Complexes.

Algebra-format Rope: [ [ x , (1.0 + 1.0 i ) x^12 + (0.0 - 1.0 i ) ] , [ x^3 , x ] ]

Display Expression: X

4. Algebraic Numbers (see Section 14)

Suppose the domain is extension of Rationals by the unique real root of X between -2 and -1.

Algebra-format Rope: [ x^3 + 647364/19 x^2 - 3 x + 1/8 ]

Display Expression: X

13. 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 somewhere

on 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 CaminoRealTool. Copies Working Domain but not the Current Object (if any)

14. 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.