Appendix E: NoteCards Library Packages 
SASI Final Report
Appendix E:  NoteCards Library Packages
The following NoteCards library packages are described in Appendix E:
1. NCFileCard - defines a card type for external file reference 
2. NCChain - defines a card type to create a linked chain of cards
3. NCCluster - defines a card type to create a templated set of cards
4. NCHacks - extends various aspects of system functionality
5. NCKeys - provides an alternate (command line) interaction mode
6. NCMergeFiles - provides functionality to merge two notefiles
7. NCScreen - extends screen management functionality
8. NCTableTop - functionality to save the screen as a tabletop
9. ARIDemo - example of program-controlled notefile
E.1  NCFileCard
The NCFileCard package provides an external file reference facility for NoteCards.  It implements the File card type and its underlying FILE substance type.  A FILE substance consists of a full path name (including host and directory) for some file outside the NoteFile in which the substance resides.  The FILE substance does not include version numbers.  Thus the FILE substance always references that latest version of the file.  This feature is particularly useful in group authoring efforts, since modifications to the file don't always take place from the context of a single notefile.
When a File card is created, the user is asked for the name of an external file.  If the file doesn't exist, the user will be given the choice of creating the file or aborting the creation operation.  The title of the card is automatically set to the file name, omitting the host and directory components of the full path name.  Properties are added to the card's property list containing the full file name and the current version number of the file.  The version number property is updated every time a new version of the file is created.
When a File card is brought up, it invokes TEdit on the file referenced by its underlying FILE substance.  If the referenced file no longer exists, the user is given the choice of creating the file or aborting the retrieval operation.  When the File card is saved, it does a TEdit Put on the referenced file if the file has been modified.
The FILE substance and the File card do not support local links.  Therefore, no links can be inserted into the TEdit of a File card. The File card, however, does support global links such as Source links.
E.2  NCChain
The NCChain Notecards library package defines one new card type, Chain.  Chain cards can be used when the contents of a large text card needs to be distributed among several new cards.  This is done by creating a circular linked chain of cards, each with links to the previous and next cards in the chain and each linked to the main card.  Chain cards were originally designed to provide a way to segment long mail messages into a linked "chain" of notecards and inherit the behavior of text notecards.
Chain cards are created by choosing "Chain" from the middle button Create menu.  A Chain card is just like a Text card, except that the left button title bar menu has an additional entry labeled "Make Chain."  Selecting this option brings up a menu containing two entries: "Next Chain Card" and "Done."  Selecting the former allows the user to create a new element in the chain.  Each new card has a title formed by concatenating the title of the main card with a number, indicating the position of the card in the sequence.  The new card comes up empty except for a link to the previous element of the chain (or to the head card if it is the first chain element).  The user is prompted to copy or move text into the chain card.  When she next clicks on "Next Chain Card," another new card is created with a link to the first one, while the first card gets a link to the new one.  In this way a chain of cards is created, presumably containing some portion of the text of the main card.  In addition, for each chain element, a link is created from the main card.  Thus, one can jump into the chain at any point from the main card, or step along the chain by following Next (or Previous) links.
The location of each new chain card depends on the location of the previous one.  If the previous card in the chain is on the screen, then the new one is positioned directly under it.  If not, then the new one is positioned next to the head card.
E.3  NCCluster
NCCluster defines several new Notecards types to create a card clustering facility.  The principle use of clusters has been in the legal case analysis demo designed by Art Farley.  Other applications requiring specialized clusters may use this package as an example.
This subsection describes the new types defined by this package and the legal motivation for the CaseCluster.  Further discussion of the legal case analysis application may be found in Section 2.>>subsection #<<
The Cluster card type:
The main new card type is called a Cluster.  Unlike other card types, creating a Cluster causes an interlinked network of cards to be created.  One of these cards is called the head cluster card.  In some sense control rests with this head card - the other members of the structure aren't "aware" that they are participating in a larger network.  Operations that need to be performed to the cluster as a whole are directed from the head card.  In addition to the head card there are one or more cluster "children" cards which can be of any type and are linked together at cluster creation time.
Currently there is no way for the user to create an instance of the generic Cluster type (it doesn't appear in the global "Create" menu).  In that sense, Cluster serves as a "mixin" for specialized cluster types.  The cluster specialization described here is the CaseCluster used for experimenting with legal case analysis.
The CaseCluster card type:
Like every cluster type, CaseCluster has a head card, which in this case is a text card containing links to a 4 child cards.  After creating a CaseCluster card, the user is asked to provide a title.  This will become the head card's title and will be used to generate titles for the child cards.  These child cards represent Issues, Facts, Decision, and Rationale.  Their titles are constructed by concatenating the cluster's title with the strings ":Issues", ":Facts", ":Decision", and ":Rationale."  The Issues and Decision cards are simply empty text cards.  The Facts card is an instance of the new card type Facts, a specialization of a text card in which certain predefined text appears automatically at creation time.  The only one of the four children containing further structure is the Rationale card, an instance of the new Rationale type.
The Rationale and Argument card types:
The Rationale card contains the arguments used to reach a decision for the case in question.  Creating a Rationale card causes one sample argument to be constructed in the form of an Argument card and linked as a child of the Rationale card.  Argument cards are instances of the Argument type, a specialization of Browser, which browse a predefined substructure.  An argument structure consists of four cards representing rules and support for those rules.  Specifically, there is a DecisionRule card, a LegalStatusRule card, and two RuleSupport cards.  These are simply text cards containing predefined text and links.
Thus, creating a CaseCluster actually builds two levels of structure, one from the definition of the CaseCluster type and a second from the Argument cards.
Operations performed on a cluster as a whole:
Because the head cluster card "knows" who its children are, certain operations can be performed on the entire group at once.  This is always done from the head cluster card - individual child cards of the cluster can be manipulated independently in the usual ways.
The left button title bar menu of the head cluster card has an entry called "LayoutChildren".  From this, the user can either layout in "Cascade" or in "Square".  In the first case, the cards are moved from their current locations on the screen (or opened if not currently visible) and stacked under the head cluster card.  Section 7 describes the NCScreen library package used to provide the screen layout capability in NCCluster.  Layout in Square causes the cards to be positioned in a non-overlapping manner on the screen, if possible.
If the head cluster card is closed, then any open children will also be closed.  If the head cluster card is brought up (by following a link to it), then its children are also brought up and arranged in a cascade.
The legal motivation of the NCCLUSTER package:
The basic elements of a case brief are represented by the four cards that come up upon creation of the cluster.  It is assumed we are briefing a court decision.  The FACTS card holds the case history, both in terms of agreed upon facts that occurred in the world giving rise to the case and the history of legal moves made thus far (petitions, decisions, appeals).  The ISSUES card is used to hold significant points about the case (like head notes for legal decisions).  The decision indicates what was decided in the court decision at hand, being briefed. 
Finally, the RATIONALE card holds a structured representation of the arguments presented for and against the decision.  A decision structure is made up of elements known as legal rules. of which there are several types.  A Legal Decision rule concludes a decision, given a legal context and actions or states of the world (e.g., a contract exists and has been breached and x dollars has been spent in reliance on the contract, then x dollars rewarded to relier).  A legal context is established by Legal Status and Legal Action rules that translate real-world actions into legal consequences (e.g., a letter with certain content constitutes an offer, the receiver being then in the status of offeree).   Every legal rule has associated with it a SUPPORT card indicating its basis for existence (statute, principle, case law).
Rules can be used in many cases.  The construction and specialization of legal rules is a primary activity in the formation of legal arguments.
E.4  NCHacks
The NCHacks package contains programmer's interface-based functions to provide useful extensions to the system.  They also provide models of the type of code that can be written using the programmer's interface and facilitate programming-by-example efforts.
The NCHacks functions may be applied to sets of cards in an open notefile to perform global searching, replacing, and chain creation.  These functions each take an argument bound to either a single card ID or a list of card IDs.  The function may be run over all cards in the notefile by passing the value returned by the programmer's interface function NCP.AllCards or allow user selection of cards by passing the value returned by the programmer's interface function NCP.SelectCards.
NCHACKS.TextSearch performs a search through a list of cards looking for occurrences of the specified text string which may contain wild card characters.  For example, the pound sign character (#) matches any single character and an asterisk (*) matches any sequence of characters.  This function returns either a list of cards containing at least one occurrence of the text string or a list of lists, each containing a card ID followed by the locations of occurrences of the string.  Any non-text cards in the search are ignored.
NCHACKS.GlobalTextReplace replaces every occurrence of a specified text string by a substitute string in a given list of notecards.  This function also accepts wild card characters within the text string it is looking for and ignores any non-text cards in the search.
NCHACKS.DateSearch looks for occurrences of card parts modified between the dates it is passed.  Either temporal delimiter may be set to NIL to specify a point at the beginning of notefile time or the current time.  This function enables the user to retrieve cards by temporal information independent of the card's content.  The function returns a list of lists, one sublist for each card modified between the given dates.  This sublist consists of the card ID followed by two-element lists containing the card part name that was modified and the date of last modification.  For example, if there were two hits, the function might return an expression of the form ((NC00001 (SUBSTANCEDATE "23-Aug-85 19:15:27") (TITLEDATE "23-Aug-85 19:15:44"))(NC00023 (LINKSDATE "23-Aug-85 19:16:16")))
NCHACKS.MakeChain  creates links between successive cards in Cards each of the specified link type at a given position (either START, END, or an integer value for the link's position in the card's substance).  Thus the first card in the list of cards will be linked to the second, the second to the third, etc.  (No link will be built from the last card in Cards.)  The function applies only to text cards.
NCHACKS.RemoveDeletedIconsFromTextCards removes all deleted link icons from the text of those cards in Cards having TEXT substance.
E.5  NCKeys
The NCKEYS package provides a command line interface to several of the most common NoteCards operations.  NCKEYS is implemented as a set of LISPX commands that can be typed to the Lisp Exec.  For example, typing "> Phones" in the tty window will bring up from the currently open NoteFile the NoteCard or FileBox entitled "Phones".
The available NCKEYS commands are:
> PathName œ retrieves and displays on the screen the NoteCard or FileBox specified by PathName.  (See below for description of PathNames).
< TitleSpecifier œ quits and saves all cards on the screen whose title matches TitleSpecifier.  TitleSpecifier is any string of characters.  A match occurs when these characters form a substring of the title string of a card.  If TitleSpecifier is not given, the last card retrieved using the > command is assumed.
? Command <argument> œ carries out the command specified by Command.  Command can be one of the following:
CLOSE œ closes the currently open NoteFile. The <argument> is ignored.
OPEN œ opens the NoteFile specified by <argument>, e.g., "? OPEN {DSK}HALASZ".
CHECKPOINT, CHKPT, CHECK œ checkpoints the currently open NoteFile.  The <argument> is ignored.
RETRIEVE œ does the same as >.  The <argument> is the PathName of the card to be retrieved and displayed (see discussion of PathNames below).
QUIT œ does the same as <.  The <argument> is the TitleSpecifier discussed under the < command above.
PathNames
For the task of retrieving a NoteCard or FileBox from a NoteFile, the card is specified by a PathName.  A PathName is a character string of the form x/y/z, where x, y, and z are arbitrary character strings.  The string z is a substring of the title of the target card.  If the string y is specified, it specifies a substring of title of the FileBox in which the target card must be filed.  Similarly, if x is specified, it is a substring of the title of the FileBox in which the FileBox specified by y is filed.  The PathName can consist of an arbitrary number of FileBox title substrings separated by "/".  Search for the card that matches a given PathName begins in the "Table of Contents" box (i.e., card NC00001) and traverses the FileBox lattice in a depth first manner.  The card retrieved is the first match to the PathName.
Examples:
"Phones"  matches any NoteCard or FileBox with "Phones" as a substring of its title.
"Smith" matches any NoteCard or FileBox with "Smith" as a substring of its title.
"Phones/Smith"  matches a NoteCard or FileBox with "Smith" in its title and which is filed in a FileBox with "Phones" in its title.
"People/Phones/Smith" matches a NoteCard or FileBox with "Smith" in its title and which is filed in a FileBox with "Phones" in its title and which itself is filed in a FileBox with "People" in its title.
E.6  NCMergeFiles
The NCMergeFiles package is used to merge two NoteFiles into a single combination NoteFile.  A function call may be used copy all of the cards from a source notefile onto a destination notefile, updating all ID and links as necessary.  The three top level boxes from the source notefile are automatically filed in the Table of Contents filebox in the destination notefile and the root name of source notefile is appended to their title.  The link label lists from the two files are also merged.  The source notefile remains unchanged by this operation.  This library package provides an initial tool for collaboration.
E.7  NCScreen
The NCScreen package provides a set of user-callable functions that can be used to manipulate cards on the screen.  Several other NoteCards library packages including NCCluster and NCChain currently use NCScreen functions.
Some of the functions included in the package allow cards to be laid out in special configurations.  For example, cards may be automatically placed in a square arrangement, given the position of the upper left corner of the first card.  Another function lays out the cards in a specified list in a cascaded overlapping deck with the upper left corner of the first, deepest card at a given starting position.  This function relies on a lower-level function to determine the position for the next card in a cascade.  Another screen management function arranges the cards in a list around three sides of a specified central card.  Cards are placed in order down the right side, the left side, and along the bottom.  Finally, a function is available to arrange the child cards of the filebox around a specified card.
The package also includes utility functions to move a card's window to a specified screen position, to return the positions of the various corners of a window, and to shrink a window and place so its upper left corner is at the upper left corner of its former position.
E.8  NCTableTop
The NCTableTop NoteCards library package allows a user to cache a NoteFile's tabletop status when that NoteFile is closed, and restore it the next time that NoteFile is opened. The cards and fileboxes open before the NoteFile was closed will be re-opened and restored to the screen locations they formerly occupied.
This package checks each NoteFile as it is opened to see if it contains a tabletop cache; if a cache is present, the user will be prompted to determine whether restoration of the NoteFile to its cached status is desired.  This package provides a mechanism for saving state, while allowing a notefile to be saved and its host system powered down.
E.9  ARIDemo
The ARIDemo package is an example of how the programmer's interface can be used to build a small system to demonstrate a notefile under program control.  Users building their own demos may want to use this as a model.
ARIDemo first opens a specified notefile and then allows the user to select from a menu consisting of the titles of each of the children of the Contents box.  (There is also a **QUIT** menu option for closing the notefile and exiting ARIDemo.)  After choosing a child card, say C, ARIDemo put up a menu with title C's title and with options First, Next, Previous, and EndLesson.  Selecting one of the first three brings up a child of C in the order that they appear in C.  Next goes forward down the list, Previous goes in reverse direction, First jumps to the head of the list, and EndLesson returns to the top level menu.  At all times, only one card is displayed on the screen.

(LIST ((PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (FAMILY NIL OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (270 36 72 36) NIL) (HEADING NIL (HEADINGTYPE DOCUMENT) (72 756 468 36) NIL) (HEADING NIL (HEADINGTYPE CHAPTER) (72 756 468 36) NIL) (TEXT NIL NIL (72 72 468 648) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (FAMILY NIL OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (270 36 72 36) NIL) (HEADING NIL (HEADINGTYPE DOCUMENT) (72 756 468 36) NIL) (HEADING NIL (HEADINGTYPE CHAPTER) (72 756 468 36) NIL) (TEXT NIL NIL (72 72 468 648) NIL))) (PAGE NIL NIL (0 0 612 792) ((FOLIO NIL (PARALOOKS (QUAD CENTERED) CHARLOOKS (FAMILY NIL OVERLINE OFF STRIKEOUT OFF UNDERLINE OFF SLOPE REGULAR WEIGHT MEDIUM)) (270 36 72 36) NIL) (HEADING NIL (HEADINGTYPE DOCUMENT) (72 756 468 36) NIL) (HEADING NIL (HEADINGTYPE CHAPTER) (72 756 468 36) NIL) (TEXT NIL NIL (72 72 468 648) NIL)))))
Ô
PAGEHEADINGDOCUMENT
ÔPAGEHEADINGCHAPTER
$$
Â
Â
Ô

Ô
TIMESROMAN

TIMESROMAN
TIMESROMAN
TIMESROMAN

TIMESROMAN
TIMESROMAN(


(F



/



5

6




/
	


5



-



'




.




&
P
SÍ
A
±ªö

Ô#'
.
ÌLGf2�
ËÙ		


Me,.
	Ö//:�


æ
ò
…']
K#M-
?x1


(+

#
0



`



•


.
@
w
_

K
MKv·kß-

<
Z
Ú©
K¦
5z¹