ScriptedDocsDesignNotes.tioga
Polle Zellweger (PTZ) January 8, 1987 6:54:32 pm PST
Show Script command:
Option 1 =
x: novice#1
y: novice#4
z: novice#2
real problems for branching scripts!!
Option 2 =
arrows
grey/dashed for multiple branches?
could show different scripts in different colors
Tioga documents vs. Interpress documents
Interpress documents are not editable, but they do have a concept of pages, which Tioga documents lack. You would use an x-y coordinate scheme to mark locations.
Representation of links:
use scrollbar thumbnail with arrows? limited real estate in scrollbar, mult locations on a single line difficult to represent.
want picture of document with view of script, also want script-ordered view (which becomes more complex in the presence of branching.
Dan suggested using an entry keyword, with a way of generating something if the user doesn't specify one (for scripting ease): perhaps a creation timestamp? which may be useful anyhow. That leads to the idea of colored script building, analogous to voice editing.
Want to see the script entries in context, if possible => that leads to fisheye view idea.
Instead of a textual representation, use a popup window with frames? Script entry location is mouse-sensitive?
Intermedia uses a select loc1/start link/select loc2/stop link paradigm. Their links have names (descriptors) attached, so that a user can filter links to a desired set. A user issues the Follow command to go from one location to another (unclear what happens if there are multiple links from that spot/is this allowed? Looks like there would be multiple separate link marks, and user could follow whichever one was desired; of course only some of them might be visible at a given time.) From picture in paper, appears that linkage map shows only linkages between documents, rather than finer grain. Any selection can be a source/dest. Links appear to be bidirectional.
This brings up some implementation restrictions: by only allowing a location to be scripted (by an arbitrary number of script entries) or not - desire to avoid changing typesetting is a partial goal. Whether or not each scripted location is visible or only script beginnings is important. The former says that this is an annotation system that also supports sequences of annotations, while the latter says that you can only play a script from its start (choice of single-step vs. continuous, however). If this is an annotation system, then labelled and filtered links/actions become interesting, but the meaning of those things in a script is less clear: what does it mean to view every other action of a script -- the author can no longer rely on what the user has or hasn't seen.
Other ease of use issues:
a "start recording action/stop recording action" interface would be easier than typing text into an action field.
Want to capture "mouse" motions? Drive a Magnifier around the screen? Yow!!! Perhaps these will become special animations for a later implementation/design. This moves toward Windex, ToolDriver, user interface notions. Some similarity to Brad Myers's virtual mouse/UI by example stuff? Eric Bier's Gargoyle scripts? Could capture Inscript? but if the user had any different windows open, there would be trouble!!! If individual applications implemented scripts, or allowed themselves to be driven in that way, would be okay. In a sense, ToolDriver+Brad's virtual mouse is exactly what you want:
CreateVirtualMouse {or CreateMagnifier}
MoveTo[FindViewer[ScriptedDocsDesignNotes.tioga].Save]
Wait[.5 sec]
MouseButtonDown[yellow]
Wait[.1 sec]
MouseButtonUp[all]
If you can't do these things, in what sense are actions at all useful? Real demos need to drive the mouse (!?)
Contributions/distinctive aspects of scripted docs
can layer on top of existing (lengthy) documents
want this to work in an open environment, other windows on screen, etc.
There is a major difference between showing (coarse-grained) links between small hypermedia documents for browsing and showing (fine-grained) links between scripted locations inside larger documents for sequential viewing (it's a much harder visualization problem). A generalized annotation system, with actions, could be implemented under some sort of button in the document.
actions are open-ended
has a variety of audio capabilities
can specify a sequence of actions/commands => toward XDE ToolDriver
Problems/outstanding design decisions:
1. What does a scripted location/annotation look like in a document?
a. Intermedia: a small dot represents a link, apparently a separate dot for each link.
b. If we want annotations to be playable outside a script (which may not make sense -- a previous scripted location may need to have set some variable or opened a file or something), then each one must be separately visible. Certainly if there were such a annotation/button capability, then scripts could make use of them. If annotations aren't playable outside scripts, then Suresh's suggestion to make only the script starting location visible has merit.
c. One of Stephen's goals was to make voice annotations noninvasive to a document's appearance. Thus you can't have more than one on a given character. They can also only be placed on a single character. (When a selection is longer than a single character, TiogaVoice will place the annotation on the last character.) A generalized annotation capability would allow multiple annotations per character, with tags on the annotations so that they can be filtered. (Could easily be added to TiogaVoice through char props.)
2. Are there attributes other than script names for a scripted location?
a. Certainly action annotations, or annotations in general,
3. How does one insert/specify a new entry in a script?
a. Intermedia: select loc1/start link/select loc2/stop link paradigm. A user issues the Follow command to go from one location to another.
b. Current design: each entry has a sequence number. The user edits the sequence number field (and other fields, such as action & timing) in the script tool as desired, selects the desired location, and then clicks AddEntry. The entry is added to the script after that sequence number. This and the above show only the current entry (but can do FindEntry on prev or next to discover info about them).
c. Have scripting actions automatically build up a textual script in an associated viewer. To map from the document to the associated script entries, want script entries to be visible (at least during script writing).
4. How to show a script to a writer? to a reader? (related to 3 above)
a. Intermedia: a map of a hypermedia document is a thumbnail sketch of each portion (they tend to be small), with the links between the portions shown (apparently not to specific places in each portion).
b. Connectivity:
c. Document context:
d. Document locality & sequentiality:
e. All, but not very visual: textual representation, with ways to map from script to document & vice versa.
5. A problem with the design as outlined in the Scripted Docs draft for scripts across multiple docs was how the first doc in a script was identified (seqNum = 1 for that script, chain in whatever direction needed to get there -- a disaster, could be very slow to find!). A much better plan would be to store <script name, unique id, script starting file> in a system-wide (LoganBerry) database. (script name may not be necessary here - can just store that in doc header, and use scriptUID otherwise.) Need to consider what can profitably be stored in LoganBerry dbs: whole scripts (just store script entries in doc)?
Dan suggests that you might store most of scripts in db, so that you can overlay a script on an immutable file version. That is, you use entry uids at scripted locations iff they are there. When they are, the file is editable without destroying the script; otherwise not. From the user's viewpoint, you would like it to be easy to specify which kind you are creating, and you would like to be able to change kinds in the middle.
Dan also had an idea about using scripts for debugging: collect breaks into groups (say for logging), then connect them with a named script so that they can be browsed easily. All of this also suggests that you want to (in addition to other capabilities) be able to visit all scripted locations and perform some action (registered somehow, in tool, ??). In this case, it might be SetBreak, or it might be some editing actions, etc. => scripting as a generalized grouping mechanism.
6. Implementation:
For all of the following, store list of <scriptUID, entryUID> on doc chars as $script property.
a. Storing (relevant) script linking info in doc:
store list [scriptID1, [eid,eid,eid,filename,eid,eid,filename,eid,eid]]
b. Storing script in (LoganBerry) db:
i. If store nothing in document, how do you discover that the document has scripts associated with it?
ii. Accelerator would store list of <scriptUID, entryUID> on doc chars as $scriptEntries property; list of scriptUID (possibly with script name) on doc root as $scriptIndex property.
iii. Store character positions in script in db?
7. Research aspects:
Generalized annotation mechanism
Active locations
initial: items that can be specified to CommandTool. XDE ToolDriver functionality, while backwards, would be useful. Also, the ability to drive a simulated mouse around to point things out could be very useful.
How to specify/load (correct versions of) program pieces
initial: assume programs installed unless they install themselves? Use StatementInterpreter or write standalone programs for real program fragments.
Editing annotated docs
initial: for internal scripts, use char props to allow editing. Copying, or changing/deleting named script entries (altering others repair themselves automatically?), are problems
Annotating public/private docs
initial: scripts stored in db. internal scripts use char props => docs are editable; external scripts use char positions (could use unique string? dumb, I think) => applies to unique version. Both types use unique entry ids
Multiple annotations at a single doc location
initial: allowed, and script/annotation tool is required to sort out which is which in this case. Visualization of overlapping locations is a problem using some sort of square; may be better with some sort of oval.
Generalized scripting mechanism
Multiple docs in a single script (w/ version mgmt)
initial: store doc global names in db w or w/o version, depending on internal/external script
Branching scripts
initial: use label or unique entry id; a bit clumsy
User interaction
initial: could do something in the tool - this one needs more thought
Generalized grouping mechanism
Applying a single action across a group of locations
initial: use script tool to type in desired action?
User interface research
Visualization of annotations/scripts/groups
Architecture to support user interaction
Ease of use
Simplicity/intelligibility of user model
8. User interface ideas:
To handle branching, with multiple annotations/entries at a single doc loc, have an operation that takes a doc loc and opens a window for each annotation/entry that refers to that loc (in the given script only? If not, then how to find public and private scripts? AHA! use LoganBerry public/private merging capability! User will have a private script db specified in user profile and system will have a public one, just as telephone directories.). Then the writer can point to the desired window and say branch to that entry. Need a way to copy script entries from one script to another -- could use the preceding mechanism, by allowing the windows to be editable, so the user can edit in the changed script name (system provides script uid?).
December 31, 1986 12:10:03 pm PST
store scriptUID#start => starting filename in db (also other info, like script description?).
store <scriptUID, filename> pairs in db.
allows lookup from fname to find all scripts, lookup from scriptUID to prefetch files if desired.
store entryUID => entry info in db.
if scriptUID & filename are keyed attributes, can look up all entries w/ same filename and then prune those to find all different scripts that touch that file. Similarly to look up all entries w/ same scriptUID, then prune to find all files that script crosses. BUT the multiplicities will slow things down over a single <scriptUID, filename> pair.
A. store list of scriptUID#entryUID on doc chars as $script property.
to find first entry of script, peel off scriptUID and look for scriptUID#start entry in db.
B. store list of entryUID on doc chars as $script property.
to find first entry of script, look up entryUID in db to find scriptUID
then look up scriptUID#start entry in db.
If next and prev information are part of the entry, then each entry will be unique (unless there are infinite loops, which we don't want (?)), except that next could be computed somehow.
Note that playing a single entry may refer to uninitialized variables when actions can set variables. Might one want to restrict some scripts to only being played all the way through? Perhaps the script system could take care of that: there could be a utility routine that would ensure that the previous entry had been executed (or one could just provide default values for variables).
There may also be a lot of contention for writing in the global public database.
January 6, 1987 1:27:50 pm PST
idea: scriptUID#start could be the UID of the first entry in the script.
unfortunately, this probably won't quite work, because the user could add a new entry to the beginning of the script. At that point, could give this (old) entry a new UID, and have the new one become scriptUID#start. Would require possibly complex updates if other entries point to (in their next or prev field) that entry. (But prev field doesn't work for nonsequential scripts anyway.) If sequencing info is part of each entry, then a next field that points to the first entry in a script represents an infinite loop (for infinite demos?)
better idea: have scriptUID#start as the UID of a script descriptor entry.
best idea: store script descriptors in a separate db. That way, if one looks up a filename in the script db, will get only scripts that start in that file (maybe interesting), or could store a list of fnames as an accelerator if it becomes necessary.
January 7, 1987 2:52:00 pm PST
When to store things in the (LoganBerry) db?
A. Keep an internal representation until the document is saved, then write to the db.
B. Write to the db as soon as a script or entry is created.
Discussion: A makes less sense when scripts can cross document boundaries (which was one of the reasons for storing them separately from the underlying document, in a db), because scripts now have essentially separate lives. However, B does not have the semantics that we have become accustomed to, where one creates/edits a temporary file, whiteboard, or whatever, and saves it explicitly when desired. This temporary behavior allows experimenting with changes without committing oneself to them. (On the other hand, some systems already have permanent behavior: for example, changes to one's Walnut db while reading mail are permanent updates.) So....
C. Keep an internal representation until the user issues an explicit SaveScript command, then write to the db.
D. Write to the db as soon as a script or entry is created, but allow undo to a previously-marked spot.
More discussion: C is the obvious right choice, although it does require a new command for the user (who may be glad of the separation anyway). D does not work because a single user may be working on multiple scripts simultaneously, or multiple users may be updating the same db.
E. Use a Cypress db instead. Write to the db as soon as a script or entry is created, but only commit the transaction when the user issues an explicit SaveScript command.
Still more discussion: E accomplishes the same effect as C without the effort of an internal representation, but requires the extra effort and unknown constraints of interfacing to Cypress rather than LoganBerry.
January 7, 1987 5:15:10 pm PST
A problem with editing documents containing nonsequential scripts:
If a script entry is deleted by removing its character(s), the thread of the script is irretrievably lost, and there is no way to go on to the next entry (the next field is gone). This might be a particular problem when a document is edited outside the scripting system's knowledge.
Never mind: this is not true now that scripts have a separate Save operation. Instead, the script entries will remain, but will point to file versions/character positions that no longer match. This is a much safer situation, because that entry could just be skipped (albeit with possibly odd results) or the user could be asked to help position the entry.
Actually, it wasn't true before either: the entry in the document text is only positioning information. The scripting information was to be stored in the root of the document and would be undamaged unless the user explicitly deleted it. In some ways this is preferable, because Tioga could more easily have been changed to update the script info in the root on each edit. But perhaps a more general thing could be added to Tioga: a character-independent marking capability (that would live in the root or something, Tioga would update on edits, and clients would use as desired. TiogaVoice could use the same mechanism). Maybe Tioga has this already?? TiogaOps.PutTextKey/GetTextKey => NodeAddrs.PutTextAddr/GetTextAddr is almost what I want, but seems to be limited to a single editing session. Dan says it doesn't quite work right anyway. He thinks you want something more general still: a way to register routines to be called whenever certain events happen to certain properties (which is more specialized than registering a procedure to capture all edits of a given type throughout the machine -- and the current implementation of that is at too-high a level anyway: not at the TEdit level).
January 8, 1987 2:52:22 pm PST
How do we tell that a script is internal vs. external? How do we know whether a filedate must be consulted? Could use the convention that if a version is specified in the filename field in the db, then only its associated date is acceptable, otherwise any date is ok. That would require doing a prefix query on the filename field, using LoganBerryTools.