Datalab

Sidepad User Guide

SPARCE Home ] Up ] [ User Guide ] TOC ] Quickstart ]

 

Dept. of Computer Science
Portland State University

 

1. Introduction

Related information: Table of Contents

Sidepad is a superimposed application. It lets you create labeled notes, and link and group the notes.

You can use Sidepad as a drawing tool and as a research tool. You can create concept maps, ER diagrams, flow charts, or you can create diagrams in your own model. You can also use it as a research tool because you can maintain notes and reference external documents and sub-documents from any component of your drawing. For example, you can reference a text selection in a PDF document or a range of cells in an MS Excel workbook from a note. Here is a complete list of document types you can reference from Sidepad:

  • MS Word document, MS Excel workbook, MS PowerPoint presentation
  • PDF
  • HTML
  • Audio and video

Sidepad uses SPARCE, a middleware architecture and implementation for superimposed information management, and the SPARCE SDK to reference external documents. You can support other document types using the SDK.

1.1 Prerequisites

Related information: Table of Contents

You need the following software to run Sidepad :

  • MS Windows XP (Service Pack 2 recommended, but not necessary)
  • MS Office XP (to reference information created by these applications)
  • Windows Scripting Engine (VBScript required). Freely available from Microsoft.
  • Adobe Acrobat 5.0 or better; full version (to reference information in PDF documents)
  • MS Internet Explorer 5.0 or better (to reference information in HTML pages)
  • Windows Media Player 9 or better (to reference information in audio and video files)
  • Sidewalk Tools (Sidepad is a part of these tools)

We assume you are familiar with terms such as superimposed information, mark, context and superimposed applications. We also assume you are familiar with Windows user-interface elements such as tabbed property pages and file-selection dialog.

1.2 Overview

Related information: Table of Contents

Figure 1.1 shows a Sidepad document. The blue boxes are items (Sidepad's term for notes) and the grey boxes are groups. The arrows are links. This document has nine items, two groups, and six links. Four of the links are between items (all originating from the item 'Introduction'). The other two links are from an item to a group (from the item 'Modern Information Retrieval'). In Sidepad, nodes (a common term to mean items and groups) and links have a label. In addition, items may also contain a descriptive text. The item 'Motivation' contains such a text.

 Figure 1.1: A Sidepad document

If this Sidepad document reminds you of concept maps, it is no accident. The contents of this Sidepad document are based on some concept maps in the GetSmart online repository. The item 'Reference' cites this source.

Sidepad nodes and links may reference external documents and sub-documents (selections in documents). These references are called marks. When you activate a mark, you will be taken to the document or the sub-document the mark corresponds to. Figure 1.2 shows the mark associated with the Item 'Motivation' activated. Here the sub-document referenced is a selection in an HTML page, resident on the web. It has been activated inside MS Internet Explorer.

 Figure 1.2: An HTML mark activated

A mark is similar to a URL resource in concept map tools. In fact, a mark may be represented as a URL. The resulting URL can be used as a resource in GetSmart and IHMC CMapTools. Sidepad is different from concept mapping tools in at least two aspects: the ability to place nodes in a group and the ability to associate marks with links. IHMC CMapTools and GetSmart both allow URL resources only with concepts (nodes in Sidepad).

Components of a Sidepad document do not need to reference external documents and sub-documents. [Download sample documents that do not reference external documents: ER Diagram, ER Diagram (UML Notation).]

1.3 The Information Model

Related information: Overview, Table of Contents

Figure 1.3 shows the Sidepad information model in an UML diagram. From the figure we see that a Sidepad document is a collection of nodes. A node has an ID, a name, location, size, and a few display attributes such as font and color (not shown). A node may be an item or a group. An item adds a description attribute to a node, whereas a group gives a node the ability to contain other nodes (items and other groups). An item does not need to be contained in a group--it may be directly contained in a document.

A link may be established between two nodes. The association class 'Link' models a link. The classes 'End 1' and 'End 2' model the linked nodes. [These intermediary classes were required because the drawing tool we use, MS Visio, does not allow segments in the line connecting the associated classes.]  A link has a name. It is always binary, but it may be directed, undirected, or bidirectional. It also has display attributes such as font and color (not shown).

Figure 1.3: The Sidepad Information Model

2. Getting Started

Related information: Overview, Table of Contents

The installation process creates a program group (default name 'Sidewalk Tools') and installs a few shortcuts in that group. Use the shortcut labeled 'Sidepad' to start Sidepad. Figure 2.1 shows the default program group in the Windows Start menu.

Figure 2.1: The Sidewalk Tools Program Group

Sidepad affords many operations for nodes (items and groups) and links. You can create new nodes; you can group nodes, exclude nodes from groups, remove groups, and link nodes. You can rename, resize, and change visual characteristics such as color and font of nodes and links. You can associate external documents and sub-documents with nodes and links, and navigate to the sub-documents. [We only mention sub-documents from this point forward, but all operations associated with sub-documents are also possible on documents.] You can also browse information from the context of a sub-document. The context information includes information such as excerpt, containing paragraph, font, and color.

You perform most operations we describe in the context of a Sidepad document. We assume you have started Sidepad and have a document open. (A new document is automatically opened when you start Sidepad.)

As we described in the overview, you work with items, groups, and links in Sidepad. We use the term node when describing an operation or concept that applies to both items and groups. We use the term object when describing an operation or concept that applies to items, groups, and links.

We frequently refer to operations available from context menus. A context menu is a menu that is opened by clicking the right-mouse button on a document or on an object. A context menu contains item that pertain to the document or object clicked. You open a document's context menu when you right-click in an empty space in a document. You open an object's context menu when you right-click on that object.

Some of the items in a context menu might also be available in the main menu or in the toolbar. Other items might be available exclusively in the context menu. Many entries in an item's context menu are also available on the toolbar and in the Edit menu. We omit references to these alternatives for brevity. In general, we describe the "normal" means of accomplishing a task. We describe alternatives only when they are significant.

In this guide, we describe the features of Sidepad Version 2.1.4. Use the About box to determine the version of the application you are running. Use the 'Help/About' main menu item to open the About box.

2.1 Working with Items

Related information: Overview, Table of Contents

In this section we describe operations related to items. An item is a labeled note, with an optional descriptive text called comment. The application defines no semantics for an item; you may assign it any semantics you like. For example, if a document contains a concept map, you might treat an item as a concept.

Parts of this section might also apply to groups (when we use the term node) and to groups and links (when we use the term object). We describe most operations in the context of a single item, but some of the operations might apply to more than one item. Use the Edit menu to operate on more than one item at once.

You select an object left-click when you left-click it once. To select additional objects, hold the CTRL key down as you click You can also select objects by drawing a bounding box around those objects with the left mouse button. You can select all objects in a document by pressing CTRL+A, or by using the 'Select All' item in the Edit menu.

2.1.1 Creating an Item

Open the document's context menu and select 'Markless Item' in the 'New' sub-menu. Alternatively, press the keys 'n' and 'l' (the letter 'el') in sequence, after opening the document's context menu. This action creates a new item with the default name 'New Item' and an empty comment. This item is mark-less because it does not reference any document or sub-document.

2.1.2 Item Properties

You change most of the properties of a node in its property pages. Use the 'Properties' item in the node's context menu to open the node's property pages. The first property page labeled 'General' lets you rename a node, and add or alter the comment included in an item. A node name cannot be empty.

The property page labeled 'View' lets you alter the node's appearance. You can change the shape of the node, the drawing style, the width of the lines drawn, and create a shadow for the lines. The maximum drawing width is eight. A width greater than this limit is disregarded, and the default value (zero) is used. You can set the font used to draw the node's name and an item's comment using the button attached to the Font dropdown list. You can also change the color of the various components of a node using the button attached to the Color dropdown list. The Drawing color is the color of the lines that make up the shape. The Text color is the color of the text. The Fill color is the color of the node's inside area. By default, the node's inside area is transparent.

The View page also provides a preview of some of the changes you make to a node's appearance. The preview does not reflect the following properties: Shape, Shadow, and Fill color.

Note 1: You can set a node's shape as the default shape for future nodes created in a session (one Sidepad instance). Use the 'Set as Default Shape' item in the node's context menu to set the default shape. The default shape for items may be different from that for groups. [Defect: Default shape setting for groups is not effective.]

Note 2: The View page contains a button labeled 'Advanced.' We advise against using this button because it is a maintenance aid. Changes you make to a node's properties using this button might adversely affect the performance of the application.

2.1.3 Renaming an Item

Use the 'Rename' item in a node's context menu to rename the node. Selecting this menu item changes the name area of the node to an editable field. Overwrite the node's current name with its new name and hit Enter.

You can also rename a node in the General property page of a node.

2.1.4 Deleting an Item

Select the nodes you like to delete and hit the Delete key on your keyboard.

2.1.5 Changing Display Order

Objects are displayed in layers. Consequently, an object can obscure another object (the exact effect depends on the display properties of the objects in question). The most recently created object is placed in the top-most layer. 

You can move objects from front to back or back to front (one layer at a time) using the Order sub-menu of an object's context menu.

2.2 Undoing and Redoing Operations

Related information: Working with Items, Table of Contents

You can undo or redo many Sidepad operations. To undo an operation, hit CTRL+Z. To redo an operation, hit CTRL+Y. For example, you can undo deleting an item.

Sidepad maintains a stack of operations you perform (stack-size is limited). That is, you could undo several operations backward, and redo several operations forward. Note that undoing and redoing an operation does not require (or involve) selecting an item. These operations simply reverse or replay a past operation. Examine the Edit menu to determine which operation will be undone or redone.

Note: You may not be able to undo all operations. Even when an operation can be undone within Sidepad, you may not be able to undo changes made to the state of another application. For example, the affect on the Clipboard may not be undone when you undo a Cut operation in Sidepad.

2.3 Working with Groups

Related information: Working with Items, Table of Contents

A group contains zero or more nodes. That is, a group may contain another group. A node may be contained in at most one group. When you move a group, its contents move with it. The application defines no semantics for a group; you may assign it any semantics you like.

Some of the operations we describe in this section work on a single group (or node as appropriate) and on multiple groups (or nodes), but we describe the operations on a single group for simplicity. Also, Sidepad might enable some of these operations for nodes to which the operations do not apply. This choice is made for performance reasons. Inappropriate nodes are automatically excluded when the operation is actually carried out.

2.3.1 Creating a Group

Open the document's context menu and select 'Group' in the 'New' sub-menu. Alternatively, press the keys 'n' and 'g' in sequence, after opening the document's context menu. This action creates a new empty group with the default name 'New Group'.

To group selected nodes, select the nodes you like to group and click the 'Group' toolbar icon (or use the 'Edit/Group' menu item). When you group existing nodes, the new group will be large enough to contain the selected nodes.

2.3.2 Group Properties

Changing the properties of a group is similar to changing the properties of an item. Renaming a group and changing its display order are also similar to those operations on an item.

2.3.3 Excluding Nodes from a Group

When you exclude a node from its group (if any), you will dissociate that node from its group. For example, after this operation, moving the group the node was excluded from does not move the excluded node.

When a node is excluded from a group, the group is resized after the node is dissociated from the group. When the last node in a group is excluded from the group, the group gets a default size, but its origin (left and top) remains unchanged.

2.3.4 Deleting a Group

Deleting a group is similar to deleting items (hit the Delete key on your keyboard). However, deleting a group will delete all its contents. If you like to retain the group's contents, but just remove the group, use the 'Remove Group' operation.

2.3.5 Removing a Group

Select the group you like to remove and select the 'Remove Group' item from the group's context menu. Removing a group first dissociates all its nodes from the group and then deletes the group. That is, the group's contents are not deleted. Removing an empty group has the same effect as deleting that group.

[Defect: 'Remove Group' is disabled when an empty group is selected. Workaround: Use the 'Delete' operation.]

2.3.6 Moving a Group's Contents

You can move the nodes contained in a group freely, including moving it to outside the group's boundary. A group's node placed outside the group's boundary is still a part of the group. For example, moving the group node causes the node also to move (the position of the node in relation to the group is unchanged).

[Enhancement: A future version of the application will let you decide if a group's contents are rigidly positioned.]

2.3.7 Adding Nodes to a Group

Remove the group, and create a new group including the nodes you like to add to the group you removed.

[Enhancement: A future version of the application will let you add nodes directly to an existing group.]

2.4 Working with Links

Related information: Working with Items, Working with Groups, Table of Contents

You can create links between nodes. A link could be between items, between groups, or between a group and an item. A link is always binary. It may be undirected, directed, or bidirectional. When a linked node is moved, its link stretches or shrinks correspondingly.

A link can be reflexive. Linked nodes may form a cycle.

The application defines no semantics for a link; you may assign it any semantics you like. For example, if the document contains a concept map, you might treat a link as a proposition.

2.4.1 Creating a Link

Select a node and move the cursor to the center of the node (over the square selection point at the center). The mouse pointer changes to a vertical arrow. Hold the left mouse button down and drag the mouse until the pointer is over the other node you like to link. Release the mouse button. A new link with the name 'New Link' is created between the nodes.  By default, the link is directed from the first node to the second node.

2.4.2 Link Properties

Although a link has several properties such as color and font name, you do not have access to those properties. The link context menu includes a 'Properties' item, but it is a maintenance aid. Changes you make to a link's properties using this menu item might adversely affect the performance of the application.

2.4.3 Renaming a Link

Use the 'Rename' item in a link's context menu to rename the link. Selecting this menu item changes the name area of the link to an editable field. Overwrite the link's current name with its new name and hit Enter.

2.4.4 Changing Link Direction

You use a link's context menu to change the link's direction. A new link is directed by default, but you can change it: reverse the direction, make it bidirectional, or make it undirected. Table 2.1 shows the operations allowed based on the current direction of a link. The column 'Current state' lists the current directionality of the link. Each of the other columns indicates a context menu item. (In this table, we use the names 'A' and 'B' to for the names of the current origin and destination nodes of the link respectively.) An entry 'x' in a cell indicates that the menu item in that column is available for the link directionality the row represents. For example, when a link is directed, you can use any of the menu items shown. When a link is bidirectional, you cannot reverse its direction.

All menu items except the 'Reverse' item are "checked" items. That is, the context menu displays a check mark against a menu item, if that item has already been selected. Selecting a menu item that is not checked applies the operation that item indicates, and places a check mark on that item. Selecting a menu item that is already checked has no effect on the link's direction. The 'Reverse' menu item, when available, is a regular menu item. Selecting it simply reverses the link's direction.

Table 2.1: Operations related to link directionality

Current state

'A' to 'B' 'B' to 'A' Bidirectional Undirected Reverse

Directed

x

x

x

x

x

Bidirectional

x

x

-

x

-

Undirected

x

x

x

-

-

2.5 Clipboard Operations

Related information: Working with Items, Working with Groups, Working with Links, Table of Contents

You can freely cut or copy selected objects to the system Clipboard, and paste compatible objects in the Clipboard in to your document. In this section we describe only the Copy and Paste operations. Cutting objects copies them to the Clipboard, and it also deletes them from the source document.

You can paste objects copied from a document back in to the same document, or in to another document.

2.5.1 Copying Objects

Select the objects you like to copy and hit CTRL+C. You can also use the object's context menu or the Edit menu, or the toolbar icon. The Copy operation places a copy of the selected objects in the Clipboard (in a proprietary format).

Although you can freely copy any node to the Clipboard, you can copy a link only if you also copy both its end points. That is, when you select a link to copy, you must also select its end points. For ease of use, when your selection includes links, those links whose end points are not in the selection are automatically excluded from the Copy operation.

2.5.2 Pasting Objects

Hit CTRL+V to paste objects from the Clipboard. You can also use the document's context menu or the Edit menu, or the toolbar icon.

Pasting creates a replica of the source objects. Any change you make to a replica does not affect its source object.

The Paste operation is available only when the Clipboard has compatible data. For example, if you have previously copied some objects to the Clipboard.

2.5.3 Copying as Enhanced Metafile

You can copy objects to the Clipboard in the Windows Enhanced Metafile format (EMF). Use the 'Copy as Enhanced Metafile' item in the Edit menu to copy objects in EMF.

Applications such as MS Word are able to paste EMF data from the Clipboard. Those applications treat the EMF objects simply as drawings, not as nodes and links. Consequently, you can copy a link as EMF, independent of its end points.

[Defect: 'Copy as Enhanced Metafile' does not always succeed. Workaround: First copy the objects using CTRL+C. Then copy the objects as EMF.]

2.6 Working with Documents

Related information: Getting Started, Table of Contents

2.6.1 Creating a Document

You work with nodes and links in the context of a document. A new document is automatically created for you when you start the application (using the installed shortcut). To create a new document, hit CTRL+N. If you made any changes to the default document, you will be prompted to save the changes.

2.6.2 Document Properties

A document has no explicit properties. The document context menu contains a 'Properties' item, but it is a maintenance aid. Changes you make to a document's properties using this menu item might adversely affect the performance of the application.

2.6.3 Saving to Files and Opening from Files

You can save a document to a file-system file in any of the following file formats: Native (Sidepad document), RIDPad document (RIDPad is another superimposed application), XML, and Enhanced Metafile (EMF). You can save a Sidepad document in any of these formats, except in the RIDPad format. You can open a file in any of these formats, except the EMF.

To save a document to a file hit CTRL+S. When you save a document for the first time, you are offered a dialog to choose a file name and location. Future save operations on that document overwrite that file. To save a file as another file, use the 'Save As' item in the File menu. To open a document from a file, use the 'Open' item in the File menu.

You are offered the 'Save As' dialog when you save a document that you originally opened from a file in a non-native format (that is, not as a Sidepad document). You can still choose to save the document in any of the supported formats.

[Defect: The 'Save' item in the document context menu is not functional.]

2.6.4 Printing a Document

You can print a document or preview the print. Use the 'Print' item in the File menu to print a document, and the 'Print Preview' item to get a preview of the print.

The 'Print Preview' menu item and the corresponding toolbar icon act as toggle switches. Selecting one of these options when you are editing a document puts the application in preview mode. Selecting the option again returns the application to edit mode.

When previewing print of a document, double-click the left mouse button to zoom in. Double-click the right mouse button to zoom out.

[Defect: The 'Print' item in the document context menu is not functional.]

[Defect: The 'Page Setup' item in the File menu is not functional.]

2.6.5 Operating from the Windows Shell

The installation process registers a file type 'Sidepad Document' (files with .spad extension), and associates this file type with Sidepad. Figure 2.2 shows the icon associated with this file type.

Figure 2.2: The Sidepad Document Icon

The installation process also adds two items, Open and Pack, to the shell context menu of a Sidepad document. 'Open' opens the document (the default operation); 'Pack' helps you share that document. Double-clicking on a Sidepad document in the Windows shell also opens that document.

You can drag a Sidepad document or a RIDPad document from the Windows shell and drop it on to a Sidepad document window. This action adds all the objects in the dragged document to the current Sidepad document. Dragging and dropping is an alternative to copying all objects of a document and pasting them to the current document. [Caution: The behavior of the file drag and drop feature might change in future versions of the application.]

3. Referencing Sub-documents

Related information: Getting Started, Table of Contents

Sidepad nodes and links may reference documents and sub-documents. These references are called marks. When you activate a mark, you will be taken to the document or the sub-document the mark corresponds to. Figure 1.2 shows the result of activating an HTML mark.

3.1 Creating Marks

Related information: Overview, Table of Contents

3.1.1 Overview

You select a sub-document to reference from Sidepad in a "native" base application. For example, if you like to select a portion of a PDF document to reference, you use Adobe Acrobat.

The installation process adds plug-ins to some common base applications. You use a "selection" operation the plug-ins provide to gather the necessary information to reference your selection. The process of selecting sub-documents is called marking or mark creation.

Figure 3.1: Mark-creation scenarios

Figure 3.1 shows two possible mark-creation scenarios in an UML Use-Case Diagram. (The boxes in this figure denote system boundaries; the broken arrows denote object flows.) In the 'Copy' scenario, you use the conventional 'copy to Clipboard' operation in a base application. In the 'Mark' scenario, you invoke a function a plug-in adds in to a base application. For example, Figure 3.2 shows a 'Create Mark' function added in to MS Internet Explorer. Here a user has opened the context menu for a selection (the text 'The Retrieval Process') in an HTML page.

Figure 3.2: Creating a mark in MS Internet Explorer

Supporting the 'Copy' scenario requires cooperative base applications. Some base applications do not directly support Clipboard operations, or they do not allow interception of such operations (or they might require significant development effort to intercept Clipboard operations or interpret Clipboard data). However, many such applications provide mechanisms to extend their environments. You are able to use only the 'Mark' scenario in such applications.

In either scenario, you typically only select a menu item or push a button to start mark-creation. You complete mark-creation in Sidepad.

3.1.2 Base Applications Supported

Table 3.1 lists the base applications in which you can create marks. It also shows the scenarios supported, and how you access the special mark-creation function.

Table 3.1: Base applications supported

Base application Sub-document nature 'Copy' scenario 'Mark' scenario

MS Word

Text selection (not in header or footer)

Any supported means of copying except  CTRL+C and CTRL+INS

'Mark' button in the SPARCE toolbar. (See Figure 3.4)

MS Excel

A range of cells

Same as above

Same as above

MS PowerPoint

One of these: text selection, one or more bullets, one or more objects on a slide, one or more slides in Slide Sorter or Slide Outline

Same as above

Same as above

Adobe Acrobat (full version)

Text selection (using the built-in text selection tool). Marking is not supported in Acrobat Reader.

Not supported

'Create Mark' item in the Tools menu.

MS Internet Explorer

Text selection

Not supported

'Create Mark' item in the context menu exposed when you right click. (See Figure 3.2)

Enhanced Media Player

Any region of media (time offsets). Use the installed shortcut to start the player.

Not supported

Start and stop the red, round 'Record' button on the toolbar.

3.1.3 Configuring Base-Application Extensions

The installation process configures your machine and the base applications listed in Table 3.1. However, you are required to configure the extensions to MS Office applications explicitly. You need to configure these extensions only once on a machine.

Select the item 'Configure MS Office Add-Ins' in the Tools menu to configure the extension to MS Office applications. This action displays a dialog (shown in Figure 3.3) with the names of the applications for which extensions are available. Check ON the box next to the name of the application in which you like to use the extension. Leave the check box about overriding the copy operation OFF for now (The section Repository-Independent URI describes the use of this check box). Select the OK button to save the configuration and close the dialog. Changes to the configuration takes effect the next time you start the appropriate MS Office application.

Figure 3.3: Configuring extensions to MS Office applications

Enabling the MS Office extension for an application adds a toolbar named 'SPARCE' to that application. The toolbar is hidden by default. Use the Toolbars menu in the MS Office application to show this toolbar. Figure 3.4 shows this toolbar being used in MS Word. You can also use the 'Configure' button on this toolbar to configure the MS Office extension.

Figure 3.4: Creating a mark in MS Word

3.1.4 Behind the Scenes

The mark-creation process consists of two steps: (1) generating the address of the selected base information, and other auxiliary information (collectively called mark fodder) and (2) creating a mark object in the SPARCE repository.

A mark object is not immediately created when you create a mark in a base application. Instead, only mark fodder is gathered. When you complete the mark-creation operation in Sidepad, Sidepad interacts with SPARCE to convert the fodder to a mark object. Specifically, SPARCE creates a mark object, assigns it a globally unique ID, creates a descriptor for the mark in its repository, and returns the mark object to Sidepad. Sidepad uses the mark object as long as needed, but saves only the mark ID for future use. When you use the same mark in another Sidepad session, Sidepad retrieves the mark object from SPARCE (using the mark ID as the key).

Saving only the mark ID keeps the Sidepad information simple. Reusing a mark only requires the ID to be replicated (not the entire fodder or the mark object). However, it creates dependency on a SPARCE repository. The sections Mark as URI and Sharing Sidepad Documents describe means of being repository independent.

3.2 Incorporating Marks

Related information: Getting Started, Creating Marks, Table of Contents

3.2.1 Creating New Items with Marks

After you have selected a sub-document in a base application and marked it (in one of the two scenarios described in this section's overview), switch to Sidepad, and select to paste from the Clipboard (hit CTRL+V). This action creates a new item with the default name 'New Item'. The text excerpt of the sub-document you marked is automatically pasted as the descriptive text of the new item. Although you do not see any visual indication of it, the mark that corresponds to the sub-document you selected is also associated with the item.

You can also create a new item associated with a mark using the 'Item' entry in the 'New' sub-menu of the document context menu.

3.2.2 Item Properties Revisited

An item with a mark has three additional property pages compared to the property pages of a mark-less item. The 'Mark' page provides details of the mark associated with the item. The ID field shows the ID of the mark, and the Excerpt field shows a text excerpt from the sub-document (as it was at mark-creation time). The 'Container' and 'Application' pages provide details of the document and the application where the mark is made, respectively. None of the fields in these pages are (directly) editable. However, they support the 'copy to Clipboard' operation.

3.2.3 Greedy Marking

After you mark a sub-document in a base application, you do not need to immediately reference it in a Sidepad document. You can first mark as many sub-documents as you like in as many base applications as you like, and use the marks in Sidepad at a later time.

Select the 'Item from Clipboard' entry in the 'New' sub-menu of the document context menu. This action displays a window with a list of the marks you have created thus far (in this Sidepad session). Clicking on a listed mark shows the text excerpt for that mark towards the bottom of the window. Double-click on a mark to create a new item associated with that mark.

3.2.4 Reusing a Mark

You may associate the same mark with more than one item (in the same document or in different documents).

Select the 'Item from Mark' entry in the 'New' sub-menu of the document context menu. This action displays a dialog asking you to enter a mark ID. Enter a valid mark ID and hit Enter to create a new item associated with that mark (whose ID you entered).

The ID of a mark you have already used is displayed in the 'Mark' property page of an item.

[Enhancement: A future version of the application will provide a Mark selection facility.]

3.2.5 Associating Marks with Groups and Links

Groups and links are created mark-less by default. Use the 'Add Mark' sub-menu in the object's context menu to associate a mark with that object. This sub-menu contains three entries. The 'From Last Base Selection' entry associates the object with the last mark you created in a base selection. The 'From Clipboard' entry lets you create marks greedily. The 'From Mark Repository' entry lets you reuse the ID of a mark you have already used.

You can similarly associate a mark with a mark-less item.

The property pages of any object with a mark is extended (by three pages) to show the details of the mark, the base document, and the base application.

[Defect: The property pages of a link with mark do not include the three additional pages.]

3.2.6 Changing and Removing Marks

Use the 'Change Mark' sub-menu in an object's context menu to change or remove the mark associated with that object. This sub-menu contains four entries. The first three entries remove the mark currently associated with the object and change it to a different mark. These entries correspond to the entries in the 'Add Mark' sub-menu described in the section Associating Marks with Groups and Links.

You can remove the mark associated with an object using the 'Remove Mark' entry in the 'Change Mark' sub-menu. You can use the 'Add Mark' sub-menu of the object's context menu to again associate a mark with the object.

3.2.7 Changing the Location of a Base Document

Occasionally a base document might get relocated. For example, you might move a base document to a different directory. You can use the 'New Location' button in the 'Container' property page of an object (with a mark) to change a document's location. Use the dropdown attached to the button to decide the new location of the document. The 'File System Path' option in the dropdown lets you assign a file-system path to the document. If you choose this option, you are allowed to specify only a valid file-system path (the file must exist). The 'URL' option lets you assign a URL to the document. The URL you supply is not validated.

The ability to change the location of a base document can be useful when you work with marks made in remote PDF documents. The Adobe Acrobat plug-in to create marks shows the location of a remote PDF file to be the temporary file that Acrobat created (not the remote location you opened). You can correct the location of the base document using the 'New Location' button.

We advise caution when you change a base document's location. This operation changes the location of the base document for all marks in that document. You need to ensure that the document at the new location is "compatible" with the document where the marks were created.

3.3 Using Marks

Related information: Creating Marks, Incorporating Marks, Table of Contents

3.3.1 Navigating to a Sub-document

Double-click on an object associated with a mark to navigate to the sub-document the mark corresponds to. This operation is also called resolving or activating a mark This operation opens the base document in an appropriate base application, and makes the sub-document visible. In most cases, the sub-document is also highlighted. Figure 1.2 shows an HTML mark activated.

The appropriate base application must be installed locally on the machine where you perform the navigation operation.

You can also activate a mark associated with an object using the 'Goto Source' item in the object's context menu.

You only need the Adobe Acrobat Reader to activate a PDF mark (although you need the full Adobe Acrobat to create a PDF mark).

3.3.2 Browsing Context

Occasionally you might need certain information about a referenced sub-document, without activating a mark. For example, you might like to see the text excerpt, or see the containing paragraph of an MS Word mark. You can see such information related to a mark, called the context of the mark, in a Context Browser. Use the 'Context' item in an object's context menu to open the Context Browser.

The Context Browser displays information related to a mark in a hierarchical view. Figure 3.5 shows context information for the MS Word mark of Figure 3.4. The tree in the left pane of Figure 3.5 is showing a hierarchical list of context elements. The right pane is showing the value of a context element selected in the tree. Currently, the right pane is showing the text excerpt for the mark. As the figure shows, you can see other context information such as the text of the containing paragraph.

The context information the browser displays depends on the mark and the type of the base document.

Figure 3.5: Context Browser

3.4 Clipboard Operations Revisited

Related information: Clipboard Operations, Incorporating Marks, Table of Contents

You can cut, copy, and paste objects associated with marks just as you do mark-less objects (as described in the section Clipboard Operations). A replica of the object is created when you paste an object associated with a mark, but the replica and the original are both associated with the same mark. That is, the ID of the mark the two objects are associated with is the same. If needed, you can change or remove the mark associated with either object without affecting the other object. 

4. Referencing Sub-documents from Other Applications

4.1 Superware and "Otherware"

Related information: Referencing Sub-documents, Table of Contents

Superware (a superimposed application) [Prof. Lois Delcambre coined this term.] such as Sidepad is built from the ground up to incorporate marks. However, you might wish to incorporate marks in the information you produce with otherware (applications not designed specifically for superimposed information management). For example, you might like to incorporate marks in an HTML page or in a GetSmart concept map. The ability to incorporate marks in existing applications allows you to exploit both the (rich) information model of those applications, and reference sub-documents from applications that do not natively support that feature.

4.2. Mark as URI

Related information: Superware and "Otherware", Table of Contents

You use Universal Resource Identifiers (URIs) to reference sub-documents (and to navigate, and to browse context) from other applications.

The IETF RFC 2396 defines the general syntax of a URI. In simple terms, a URI includes a naming scheme (AKA namespace and protocol), and a scheme specific data. The scheme-specific data often includes a naming authority, some path information within that naming authority, and optionally a query specification or a fragment specification. Here are some example URIs:

  • http://www.w3.org
  • http://www.w3.org/XML/Core/#Publications
  • mailto:site-comments@w3.org

4.2.1 The sparce Namespace

You can represent a mark (or a base document or a base application) in a special namespace called 'sparce'. A URI in this namespace follows these general rules:

<sparce_uri>

 ::  

sparce:<scheme_part>

<scheme_part>

 ::  

<local_part> | <remote_part>

<local_part>

 ::  

<pname>=<pvalue>[?<pname>=<pvalue>]*

<remote_part>

 ::  

//<authority>[/<path>][/<resource>][?<pname>=<pvalue>]*

<authority>

 ::  

<<a naming authority as defined in RFC 2396>>

<path>  

 ::  

<<a hierarchical path; a '/' separates two segments>>

<resource>

 :: 

<<an entity such as an html or php page>>

<pname>   

 :: 

<idname> | markfodder | action | encoding

<idname>

 :: 

markid | containerid | appid | applicationid

<pvalue>

 :: 

<ObjectID> | <markfodder> | <action> | <encoding>

<ObjectID>

 :: 

<<SPARCE assigned MarkID or ContainerID or ApplicationID>>

<markfodder>

 :: 

<<encoded mark fodder>>

<action>

 :: 

go | goto | browsecontext | showcontext

<encoding>

 :: 

base64

In these rules, a pair of brackets denotes an option, a pair of angle brackets denotes a term defined in another rule, the asterisk denotes zero or more occurrences, and a pipe symbol defines an alternative.  The double angle brackets informally describe a term. You must use all other strings shown literally.

The part of a sparce URI after a question mark is similar to query strings commonly used on the web.

Like with web links, the default action performed on a sparce URI is navigation.

A sparce URI references a resource on your machine or a remote resource, specified in the syntax using the terms <local_part> and <remote_part> respectively.

Table 4.1 shows some example sparce URIs and describes briefly what the URIs represent. The first two URIs refer to local resources. The third URI refers to a remote resource. The last URI does not refer to a mark by its ID. Instead it contains mark fodder (and so is repository independent). A mark fodder is always serialized in an encoded form (such as Base 64). The example URIs intentionally use artificial, but readable, values for mark ID and application ID.

Table 4.1: Example sparce URIs

URI Description

sparce:markid=m45

Navigate to the subdocument that corresponds to the mark whose ID is m45.

sparce:appid=a84?action=goto

Open the base application whose ID is a84.

sparce://datalab.cs.pdx.edu/sparce?markid=93?action=browsecontext 

Browse the context for a sub-document that corresponds to the mark whose ID is 93.

sparce:markfodder=SU...Eu?action=browsecontext Browse the context for a mark whose fodder is serialized here in Base-64 encoding. Fodder shown only partially.

The rules we used construct a sparce URI can lead to semantically invalid URIs. (We presented these rules because they are simpler.) For example, you can create the following URI that purports to refer to a mark ID, but includes the application ID a84.

sparce:markid=a84       (a semantically invalid URI)

The section Constructing a sparce URI provides the correct rules to construct a sparce URI.

4.2.2 Constructing a sparce URI

You construct a sparce URI using the following rules:

In these rules, a pair of brackets denotes an option, a pair of angle brackets denotes a term defined in another rule, the asterisk denotes zero or more occurrences, and a pipe symbol defines an alternative.  The double angle brackets informally describe a term. You must use all other strings shown literally.

<sparce_uri>

 ::  

sparce:<scheme_part>

<scheme_part>

 :: 

<local_part> | <remote_part>

<local_part>

 :: 

<name_value>[?<name_value>]*

<remote_part>

 :: 

//<authority>[/<path>][/<resource>][?<name_value>]*

<authority>

 :: 

<<a naming authority as defined in RFC 2396>>

<path>

 :: 

<<a hierarchical path; a '/' separates two segments>>

<resource>

 :: 

<<an entity such as an html or php page>>

<name_value>

 :: 

<object_name_value>[?<action_name_value>]

<object_name_value>

 :: 

<id_name_value>| <fodder_name_value>

<id_name_value>

 :: 

markid=<MarkID> | containerid=<ContainerID> | <appid_name>=<AppID>

<appid_name>

 :: 

appid | applicationid

<MarkID>

 :: 

<<SPARCE assigned mark ID>>

<ContainerID>

 :: 

<<SPARCE assigned container or document ID>>

<AppID>

 :: 

<<SPARCE assigned application ID>>

<fodder_name_value>

 :: 

markfodder=<markfodder>[?<enc_name_value>]

<markfodder>

 :: 

<<encoded mark fodder>>

<enc_name_value>

 :: 

encoding=<encoding>

<encoding>

 :: 

base64

<action_name_value>

 :: 

action=<action>

<action>

 :: 

go | goto | browsecontext | showcontext

4.2.3 Using a sparce URI

You can use a sparce URI anywhere you can use a URI. For example, you can insert a sparce URI as the value of an A element's href attribute in an HTML page. You can also use a sparce URI as a resource in a GetSmart (standalone) concept map.

You must use the rules in the section Constructing a sparce URI to construct a sparce URI.

Though the syntax allows a sparce URI to reference a remote resource, no remote servers are operational at this time. That is, at this time you can refer only to local resources.

4.2.4 Repository-Independent URI

When you specify a resource using a mark ID, you also indicate the repository where the mark resides (local repository if you use the <local_part> portion of the rules, or a remote repository if you use the <remote_part> portion of the rules). When you specify a local repository, you are limited to accessing the repository on the machine where you created the mark. [Several challenges and solutions exist to this problem. We focus here on one solution.]

You can specify a resource using a mark fodder instead of using a mark ID. The mark fodder includes all the information necessary to address a sub-document.

A mark fodder specified in a URI is always encoded so as to not to conflict with other parts of the URI. Base 64 encoding is the default encoding (and the only encoding supported at this time).

4.2.5 Creating and Using a Repository-Independent URI

When you create a mark in a base document in the Mark scenario, a sparce URI using the mark fodder is also copied to the Clipboard (in plain text format). You can paste this URI anywhere you need it.

You can configure the extension to MS Office applications to also copy a sparce URI in the copy scenario. However, you need to override the application's built-in copy operation (because the Clipboard can contain only one instance of text data). Check ON the box with the label 'Override host application's 'Copy' operation' to override the built-in copying (see Figure 3.3). After this change, a sparce URI is copied whenever you copy data using the toolbar icon or the Edit menu in a supported MS Office application. You can still invoke the built-in copy operation in these applications using CTRL+C or CTRL+INS keys.

A repository-independent sparce URI tends to be long, quite often longer than 200 characters. The length of a URI could restrict you from using the URI in some applications. (The URI syntax does not restrict the length of a URI.) For example, MS Office applications limit the length of a URI to 255 when you use the 'Insert Hyperlink' dialog. However, the same applications do handle longer URIs if they are already included in a document you open. For example, MS Word does not restrict the length of URIs that already exist in an HTML page.

You can obtain a repository-independent sparce URI only, immediately, after you create a mark. There is no means of retrieving such a URI for an existing mark.

You cannot use a repository-independent sparce URI in Sidepad. Sidepad has a different approach to repository independence.

4.2.6 Resolving a sparce URI

Resolving a sparce URI requires special software (a namespace handler). The installation process installs a sparce-namespace handler on your machine, and configures your machine to invoke the handler when you activate a sparce URI.

The sparce namespace handler is invoked regardless of the repository a sparce URI specifies. The handler communicates with the appropriate repository. The handler is also invoked when you activate a repository-independent URI. That is, the handler is required to handle any sparce URI.

4.2.7 An http Proxy for a sparce URI

Some applications might not be able to handle a sparce URI. For example, you cannot readily invoke a sparce URI from a Java application. When you use a sparce URI in a Java application you are likely to see a "Malformed URL" exception. The URL class in the Java SDK throws this exception because it is not aware of the sparce namespace. Also it interacts with URLs independently of the operating system. That is, the URL class does not use the sparce namespace handler installed on your machine. (Supporting any new URI namespace in a Java application requires special classes to be developed.) GetSmart (web version) is another application that does not handle sparce URIs. [We believe it handles only URIs in the http namespace.]

You can use an http proxy in applications that do not directly support sparce URIs. The proxy is an http URL with a structure similar to a sparce URI. When you invoke the proxy, it rewrites the http URL to a sparce URI. Your browser will then activate the sparce URI. Your browser must support JavaScript (and script execution must be enabled) to use the proxy.

The sparce namespace handler on your machine is invoked even when you use the http proxy. The proxy only rewrites the URL it receives to a sparce URI.

Use the following procedure to create an http proxy URL for a sparce URI:

  1. From the sparce URI, extract the string to the right of the colon (:).
  2. Concatenate the base URL of the http proxy (http://datalab.cs.pdx.edu/sparce/mark/2sparce.html), with a question mark, and the string you extracted in Step 1.

Table 4.2 shows some sparce URIs (the first two URIs and the fourth URIs from Table 4.1) and their http proxy equivalents. For simplicity, we show the http proxy URL starting only with the last part of its base URL. When using the proxy you must use the entire base URL.

Table 4.2: Example http proxy URIs

sparce URI http Proxy URI

sparce:markid=m45

2sparce.html?markid=m45

sparce:appid=a84?action=goto

2sparce.html?appid=a84?action=goto

sparce:markfodder=SU...Eu?action=browsecontext 2sparce.html?markfodder=SU...Eu?action=browsecontext

5. Sharing Sidepad Documents

Related information: Referencing Sub-documents, Table of Contents

There are several opportunities to share Sidepad documents with others. For example, when you collaborate on a project, or when you to turn in your Sidepad document at the end of a school term. However, a Sidepad document may refer to external documents. Also, a Sidepad document contains only IDs of the marks it uses, not the mark descriptors. That is, a Sidepad document has information dependencies.

Sidepad includes a packing facility that analyzes the information dependencies of a Sidepad document and creates a single superimposed information package file. You can send a superimposed package file to anyone that has Sidepad. Sidepad also includes an unpacking facility to extract and set up the information needed to use a packaged Sidepad document.

5.1 Creating a Superimposed Information Package

Related information: Referencing Sub-documents, Table of Contents

To package a Sidepad document, open the document and select the 'Pack this Document' item in the Tools menu. This action displays a Wizard-style dialog.

The wizard takes you through two steps. In the first step you choose a name and location for the superimposed information package file (.sip extension). In the second step you choose the base documents you like to include in the package. Figure 5.1 show this step when packaging the Sidepad document of Figure 1.1. It lists the seven base documents the Sidepad document uses. It also shows that these documents are on the web. The checkboxes show that the user likes to include just one base document (the last one listed) in the package.

 Figure 5.1: Step 2 in packaging a Sidepad document

When you start Step 2, the wizard suggests you leave out documents available online, but include documents on your local and network file systems. However, you can choose the base documents to be included. For example, you might include a document on your Intranet if the receiver of the package does not have access to your Intranet. You might exclude a file on your network file system if the receiver also has access to it.

If you include a document resident online, the wizard will automatically download it before preparing the package. The string 'download' in Figure 5.1 demonstrates this situation.

After selecting the base documents to include in the package, select the 'Next' button and hit 'Finish'. The wizard will write out the package file. You can send the package file to anyone who has Sidepad. Though you don't see it, the package will include the Sidepad document and the descriptors of all the marks the document uses. [Download the superimposed information package for this example, referred to hereafter as 'the sample package'.]

The packaging wizard does not analyze the dependencies of a base document. For example, if you include an HTML base document in the package, the wizard does not include the image files the HTML page might reference.

You can also start the packaging process from the Windows shell. Choose the 'Pack' item in a Sidepad document's shell context menu to start package creation.

5.2 Opening a Superimposed Information Package

Related information: Creating a Superimposed Information Package, Table of Contents

The installation process registers a file type 'Superimposed Information Package' (files with .sip extension), and associates this file type with an application called SuperUnpack. Figure 5.2 shows the icon associated with this file type.

Figure 5.2: The Superimposed Information Package Icon

You can start unpacking a superimposed information package by double-clicking on the package file in the Windows shell. This action displays a Wizard-style dialog. The wizard will take you through four steps.

You can also start the unpacking process from Sidepad using the 'Unpack a Document' item in the Tools menu.

5.2.1 Viewing Package Description

The first step in unpacking a superimposed information package is to review the information and software dependencies of the Sidepad document inside the package. Figure 5.3 show this step when unpacking the sample package.

 Figure 5.3: Step 1 in unpacking a package

The package description is divided into three parts at the highest level: information dependencies, software dependencies, and SPARCE repository updates. Each of these parts is sub-divided. For example, software dependencies include base applications and context agents. Base applications are the applications needed to navigate to the sub-documents the packaged Sidepad document references. Context agents are software parts SPARCE uses to interact with base applications. The installation process installs these parts on your machine. However, you need to ensure that the base applications listed are installed on your machine.

Use the dropdown list in this step to see different parts of the package description. Click the 'Open' button to see a full description of the package in your HTML browser.

You can open the description of a package in your HTML browser from the Windows shell using the 'Describe' item in the shell context menu of the package file.

5.2.2 Choosing Base Documents to Extract

The second step in unpacking a superimposed information package is choosing base documents to extract from the package. Figure 5.4 show this step when unpacking the sample package. It shows the name GetSmart.html assigned to the only base document included in the package file.

 Figure 5.4: Step 2 in unpacking a package

When you start this step the wizard suggests you leave out base documents that are possibly registered in your SPARCE repository. You can still choose to extract some of these base documents.  The wizard requires you to extract an included base document, if it determines that the base document is not registered in your SPARCE repository.

You must assign a name and location for each base document to be extracted (a document with the checkbox ON). Double-click a document to assign it a name and location. Use the 'Set Folder' button to assign a location to multiple documents at once.

5.2.3 Handling Missing Base Documents

A superimposed information package may not include all the base documents the packaged Sidepad document references. For example, the sample package leaves out all but one base document.

In this step the wizard lists the missing base documents. You can assign a new name and location to some of these documents, but ignore the rest of the documents. If you ignore a base document, the Sidepad document will use the document's original location. Figure 5.5 lists the base documents missing from the sample package.

A missing base document does not pose a problem if you have access to it (at the original or at an alternative location).

 Figure 5.5: Step 3 in unpacking a package

5.2.4 Extracting the Sidepad document

The last step is to extract the Sidepad document itself. In this step, you only assign a name and location to the document. After this, select the 'Next' button and hit 'Finish'. The wizard extracts base documents, addresses missing base documents (if any), and extract the Sidepad document. If you like, it will also open the Sidepad document.

When you unpack the sample package, the extracted Sidepad document will look and function exactly like the document in Figure 1.1, even though you may have relocated some base documents.

6 Transformations

Related information: Referencing Sub-documents, Table of Contents

One of the benefits of using superimposed information is that you can organize existing information in different ways. You can superimpose a new information model, a new schema, and new data. Sidepad gives you one superimposed information model, but you might like to superimpose a different model. You can use marks represented as URIs in other applications to superimpose a different model, but you will need to recreate the superimposed data (that you added in Sidepad).

A transformation can convert a Sidepad document to another model or schema, while retaining the superimposed information.

6.1 Using Built-in Transformations

Related information: Referencing Sub-documents, Table of Contents

The Transform menu gives you access to some transformations. Some of the entries in this menu simply query a Sidepad document, the associated marks and context information, and return some useful information. For example, the transformation "List Base Documents" displays a list of base documents a Sidepad document references. Other entries transform a Sidepad document to another model or schema. For example, the transformation "Make HTML Table of Contents" transforms a Sidepad document to HTML.

Figure 6.1 shows the result of transforming the Sidepad document of Figure 1.1 to a table of contents in HTML. This transformation creates a list item for each group in the Sidepad document, and creates a sub-list for the group's contents. If a Sidepad node is associated with a mark, the corresponding HTML list item is enclosed in an A element (the value of the href attribute being a sparce URI). This transformation ignores links in the Sidepad document.

 Figure 6.1: HTML generated from a Sidepad document

The transformations that start with the name 'Create GetSmart Concept Map File' generate an XML file you can open in GetSmart (standalone). You can save the result of the transformation to a file using the 'Save Result As' item in the File menu (of the result window).

The concept map transformations generate a concept for each Sidepad item. One version of this transformation ignores groups. The other version converts each group to a concept. It also creates a link (proposition) from that concept to the concepts generated for the group's contents. These links are directed to the concept created for the group. All links have the name "is a".

Both transformations ignore links in the Sidepad document. Both transformations attempt to preserve the layout of the Sidepad document, but you should expect to alter the layout in GetSmart. Figure 6.2 shows the concept map generated from the Sidepad document of Figure 1.1 (opened in GetSmart). This concept map has been altered in GetSmart after the transformation. Specifically, the links generated for the groups have been deleted and the links that the transformations ignored are recreated. The layout is also altered. [Download the concept map file shown in Figure 6.2.]

 Figure 6.2: GetSmart Concept Map generated from a Sidepad document

The transformations also attach resources to concepts where appropriate. They add a Note resource for a concept that corresponds to an item, if that item has a comment. They also add a URL resource for each node that has a mark associated with it. The value of the URL resource will be a sparce URI.

The sparce URIs generated are repository-dependent because they include mark IDs (not mark fodders). You must unpack the sample superimposed information package before you activate the URL resources in this concept map.

6.2 Developing Custom Transformations

Related information: Using Built-in Transformations, Table of Contents

A transformation is a bi-level query over superimposed information and base information (using the context mechanism). A custom transformation is a custom query. You can write a query using XPath or XSLT (the XQuery option is disabled at this time). [The details of the query mechanism are beyond the scope of this guide.] 

Sidepad includes a bi-level query processor. Use the 'Query' item in the Tools menu to open the query-processor window. The processor window contains two panes: the Query and Source pane to the left, and the Result pane to the right. The Query and Source pane contains two tabs. You write queries in the Query tab. You can see an XML representation of the current Sidepad document in the Source tab. Use the Query menu to run your queries. You can see the results in the Result pane.

Use the following procedure if you like to see some example queries:

  1. Open the Sidepad document contained in the sample superimposed information package.
  2. Run one of the transformations. This action displays the transformation output in a new window.
  3. Leave the result window as is and switch to Sidepad.
  4. Select the 'Query' item in the Tools menu. This action activates the transformation output window, but the window now displays both the transformation query and the result.
  5. Examine the query and experiment.
  6. Repeat Step 2 with a different transformation.

Use the File menu in the query-processor window to save queries, source, and results.

 

Author: Sudarshan Murthy

Page modified: 14 Jun 2006 10:29 AM