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
© Copyright 1986 Xerox Corporation. All rights reserved.
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 [this is a bug].
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:
ReplaceWithObject:
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, "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 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 of one argument
'( => 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:
X
This is a plain line of text which happens to be below a Expression.
The following is a large Expression:
Y
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):
A
X
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:
X
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. The Evaluator
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.
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.
11. Operating On Objects
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.
10. Domains
1. What they are
The ground domains are Bools, Integers (Mesa INTs), Rationals
Expressions (i.e. general expressions)
Variables
Bools
Integers (i.e. Mesa INTs)
Rationals (BigRats)
Reals (i.e. Mesa REALs)
Complexes (built from Mesa REALs)
The following are structured domains.
SingleSet
FamilyOfSets
Sequences
Vectors
Matrices
Polynomials
2. Creating Domains
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. 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 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".
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 CaminoReal viewer.
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.