Scheda and the seven issues

Introduction

Scheda answers three of the seven issues Frank Halasz raised in 1987 in substance: search, versioning, and tailoring without programming. It answers three in part: composites, virtual structures, and computation. It leaves collaborative work out by design. Its strongest answer is versioning: every card keeps every saved version, with its links and attributes, and nothing in the history is rewritten.

In "Reflections on NoteCards: Seven Issues for the Next Generation of Hypermedia Systems" (Hypertext '87, November 1987) Halasz 1987: Reflections on NoteCards [1], Halasz used NoteCards as a foil to name the limits of the hypermedia systems of his day. NoteCards, built by Randall Trigg, Thomas Moran and Halasz at Xerox PARC, offered a network of electronic cards joined by typed links, with two specialised cards: browsers, which draw a diagram of part of the network, and fileboxes, which hold cards in a hierarchy.

Scheda is a new implementation of the same idea, written in C++ with Qt, with SQLite compiled in. It is a single desktop application for one person working with ideas. It keeps NoteCards' cards, typed links, link icons, browsers and fileboxes, and opens a NoteCards file by making a copy of it. Its core (cards, storage, versions, links, search) is separate from its interface and depends on nothing but Qt's base library and SQLite.

The cards of the box "The Seven Issues" take the issues in Halasz's order. Each states what he asked for, what Scheda does, and what remains open. Collaborative work is treated as out of scope: Scheda is meant for one author and one file, and shared editing would break the simplicity that makes it fit that use.

The seven issues

1. Search and query

Scheda makes content search a primary way in, beside navigation, and offers a first, programmatic form of structure search. A query language for sub-network patterns does not exist.

What Halasz asked for

NoteCards relied on navigation, which failed for large, unfamiliar or changing networks: users "get lost" though they can describe what they want. He called for search raised to an access mechanism on a par with navigation. He distinguished content search (cards matching a description) from structure search (sub-networks matching a pattern, such as a circle of Supports links). He also wanted query to act as a filter throughout the interface.

What Scheda does

Content search. Every card's title and searchable text go into a full-text index (SQLite FTS5) in the same transaction that stores the card. The core accepts words, quoted phrases, prefixes and AND, OR and NOT. Pending changes are searched straight away, so a card is findable while it is being written. Each kind of content says what its searchable text is:

• text cards give their paragraphs and table cells;
• an external link gives both its name and its address;
• a reference card gives the address it stands for;
• a sketch gives its labels;
• attributes are indexed with the card.

In the file window, the search box narrows the list of all cards as one types; the last word counts as a prefix.

Attributes as query terms. Typing Status: draft in the search box lists exactly the cards whose Status attribute is draft. Status: lists every card that has a Status, whatever its value. Try Status: Partly in this file.

Structure search, in part. Two mechanisms come close to what Halasz described:

1. A browser card computes, each time it is shown, the network reachable from its root cards by chosen link types, in a chosen direction, to a chosen depth. The card "Map of the paper" is one.
2. The structure API's find() combines conditions on title, card type, filing (in a box, or anywhere below it), attribute and value, and words in the text. Links in and out of any card can be followed in code, so a program can find a circular argument by walking Supports links.

What remains open

There is no declarative language for patterns over sub-networks, and no structure search engine. Old versions are not searched: the index holds each card's current state. Virtual structures would build on search: 3. Virtual structures (below).

2. Composites

Scheda does not add composition as a primitive. Instead it separates reference from containment more cleanly than NoteCards did, and gives collections a name and properties of their own.

What Halasz asked for

NoteCards had only cards and links. A document built from section fileboxes could be compiled into one card, but only as a copy, and it could not be zoomed between levels of detail. He wanted collections of cards and links reified as single entities, holding their parts by reference. He traced user confusion to fileboxes and browsers mixing reference and inclusion, and asked whether a node may belong to several composites and how composites relate to versions.

What Scheda does

Fileboxes as declared reference. A box files cards and other boxes through two reserved link types, filed-card and sub-box. They may appear only inside a box, and never as ordinary card links. So filing is never mistaken for an ordinary See or Supports link. Halasz's design questions get these answers:

• Several composites: a card can be filed in any number of boxes.
• Cycles: filing a box inside its own sub-box is refused.
• Versions: filing a card changes the box, not the card. The box gets a new version; the card does not.
• Mechanism: specialised links. Their reserved types keep them apart from links that only refer.

Properties for a collection. Any card, a box included, can carry attributes such as Status: settled or Convincing: yes. This meets the request to mark a set of argument cards as a whole. It still relies on the workaround Halasz noted, letting one card stand for the set. A box copied is copied empty, because copying by inclusion would file every card in it a second time.

Richer cards. A card's content can now be structured within itself. Text cards hold tables whose cells contain paragraphs and link icons. Sketch cards hold shapes, labels, link icons and images on a canvas. Reference cards stand for a web page or a file.

What remains open

There is no composite card that shows its parts in place by reference, and no outline view that zooms from chapters to full text. Writing a structured document still means a box hierarchy and opening one card at a time, as this file shows. This is the largest gap between Scheda and Halasz's agenda.

3. Virtual structures

Scheda removes most of the pressure towards premature organisation that Halasz described. It offers one kind of computed structure, the browser card. Nodes and links defined by a query do not exist.

What Halasz asked for

NoteCards made users cut ideas into cards, title them and file them before they understood their material. Experienced users worked around this: one long text card first, piles of link icons on a sketch card, one catch-all filebox. He asked for looser organisation and easier restructuring. More fundamentally, he asked for virtual structures: nodes, links and composites defined by a description and recomputed on access, like views in a relational database.

What Scheda does

Less to decide up front. Scheda drops the rules that forced early commitments:

• A card need not be filed. Cards filed nowhere are listed under To Be Filed until the user is ready.
• A card need not have a title; it is shown as Untitled.
• Sketch cards are a first-class place for piles. Link icons can be dragged into groups and later filed. The card "Status at a glance" is such a pile.
• Refiling is a drag in the box tree, holding the copy key to file in a second box.

Restructuring is safe. Renaming or relinking a card adds a version to its history; refiling adds one to the boxes concerned. Since Scheda keeps every version, an obsolete organisation is not lost, only superseded.

Browser cards are computed. A browser stores its root cards, link types, direction, depth and the positions the user gave some nodes. Its graph is computed afresh each time it is opened or the file changes. Links drawn in the browser become real card links, and a card link removed there is gone from the network. A link written into a card's text is removed in that text instead: the browser opens the card with the link selected.

Search cards. Like browser cards, search cards hold a query and are computed. They list all cards that match the query (as in the All Cards tab), and they display their matches as virtual entires in the file window's Fileboxes tab.

Templates. A template is an ordinary card that is copied. It speeds up repeated structures without fixing them in advance.

What remains open

Scheda has no computed link, such as one to "the newest card containing hypertext".

4. Computation

Scheda stays a passive system, as NoteCards was, but it gives an outside computation a clean way in. The core has hooks on every card operation, and the structure API is a documented interface tested against its own guide. Scripting inside the application is planned, not built.

What Halasz asked for

NoteCards stored and displayed the network but did not act on it. Engines such as a tutoring driver worked from outside, through the programmer's interface. Its built-in triggers were weak: defined per card class only, not on links, and unable to reach the full system. He weighed an external engine with well-chosen hooks against an internal, active one such as a rule system, and called the choice a trade-off of efficiency against generality.

What Scheda does

Scheda takes the external road and builds three things for it:

1. Hooks. The core announces each card operation (create, edit, save, discard, delete, undelete, restore) before and after it happens. A "before" hook may veto the operation; an "after" hook runs once the change is committed. Links are part of the card that holds them, so a change to a card's links is announced with it.
2. Rules per card type. A card type may check the links a card is about to contain and refuse them. This is how a box keeps its hierarchy free of cycles.
3. The structure API. Structure gathers finding, filing, linking, attributes, copying and saving behind one class that needs only the core. Its guide holds ten worked examples, and the build compiles and runs every one.

Computed views. Browser cards compute their graph and its layout. The history window computes a word-by-word comparison of two versions.

What remains open

There is no inference or rule engine, and no scripting from inside the running application. The plan is to expose Structure for scripting once it is clear what scripts should do. Scheda deliberately has no user plugins: 7. Extensibility and tailorability (below).

5. Versioning

Versioning is where Scheda goes furthest beyond NoteCards. Every card keeps every version it was saved in, with its links and attributes, and nothing in the history is ever rewritten. Versions are linear per card; there are no branches, version sets or layers.

What Halasz asked for

NoteCards altered cards and links in place, with one version of each. Neptune kept a linear thread per node; PIE versioned both entities and the network as a whole. Halasz asked for versions and deltas that can be addressed and searched. He asked what a link refers to: a specific version, the newest one, or one found by a query. He also wanted coordinated changes to many entities gathered into one version set.

What Scheda does

The saving model. A card has at most one working revision with pending changes. Typing is stored into it a moment after it stops, so nothing is lost in a crash. Save freezes it into the card's history, Discard returns the card to its last saved state, and closing a card with pending changes asks which. Commands that change a card from outside its window, such as filing it, are saved at once, unless the card already has pending changes, which they then join.

Links have versions too. A link exists in the version of the card that holds it, so an old version keeps the links it had. "Linked from" can be asked as of any moment. A link points to a card, not to a version of it, so following it shows the card as it is now. The history answers how things stood then.

The history window. For any card, the history window:

• lists its versions newest first, with pending changes on top;
• shows any version as it was, in the card's own editor, read-only;
• compares a version with the one before it, word by word, and lists title changes, links added and removed, and attributes added, changed or removed;
• brings back an old version as pending changes, to be saved as a new version or discarded.

Bringing back never deletes the versions in between. Deleted cards keep their history too: links to them show as DELETED, and the card can be brought back. Open the history of "Summary and conclusion" to see a correction made while writing this paper.

Provenance. A copy records the card it was made from with a Copied From link. Like any link, it is kept in the copy's history and can be drawn in a browser card.

What remains open

• Versions are linear; there are no branches or alternative versions. This is a deliberate decision as branching (and the consequent merging of branches) would introduce usage complexity that Scheda tries to avoid.
• Changes to several cards are not grouped into one version set or release.
• Deltas are computed for display, not stored as entities that can be found or annotated. As cards are intended to contain a single thought or piece of information, they tend to be small—deltas would likely not have a significant impact on storage, thus are left out of Scheda for the time being. Should the future show a significant benefit for storing deltas, the topic will be revisited.
• Search covers each card's current state only.

6. Collaborative work

Scheda does not support collaborative work, by design. It is for one person thinking with one file, and shared editing would cost the simplicity that makes it fit that use.

What Halasz asked for

He found that most idea processing is collaborative, in groups of two to ten. He noted that systems offered the mechanics of multi-user access but not support for the social side. He asked for automatic change histories, tracking of each person's contributions, ways to enforce conventions, and a shared "rhetoric of hypermedia".

Why Scheda leaves it out

Supporting even a small group would bring in, at every level:

• identities and permissions;
• concurrent access, with locking or merging of edits;
• a server or a shared store, in place of one file on one disk;
• conventions to be agreed and enforced.

Each of these would be felt by the single user too, in setup, in the interface, and in what can go wrong. Scheda's file is one SQLite database the user owns, opens from Finder and backs up like any document. The application needs nothing else to run.

What one person still gets

• the automatic change history of 5. Versioning (above), which records the author's own past contributions;
• conventions of the user's own, held in link types, attribute names and templates;
• a file that can be handed to someone else to read, or copied for them to continue.

What this costs

Scheda is not a tool for a team's shared network, and it will not become one. Two people can take turns with a file, but Scheda neither knows nor helps. Cards can be copied or moved to other Scheda files, allowing sharing of work, but real-time collaboration on a single file is explicitly excluded fromScheda's scope: it would introduce a lot of administrative to the user and therefore be against Scheda's fundamental requirement of simplicity. Groups of the size Halasz described need a different kind of system.

7. Extensibility and tailorability

Scheda shifts the weight from programming to what Halasz called "small" tailorability. A user without programming can shape a file with link types, attributes and templates. Programmers extend Scheda in its source, through registries, not through user plugins.

What Halasz asked for

NoteCards' Lisp programmer's interface, over 100 functions, was used to build many tailored systems. Its goal of letting non-programmers make small changes with little work "was simply not met". The challenge he set was to make it easy for the typical user to fit the system to a task or a working style.

What Scheda does {#what-scheda-does-6}

Small tailoring, without programming.

Mechanism	What the user does	How it holds
Link types	Adds, renames and removes the file's kinds of relationship (Supports, Contradicts, Source)	Links record the type's id, so a rename shows everywhere at once; a type in use cannot be removed
Attributes	Gives any card names with values (Status: draft, Year: 1987); Tools ▸ Attributes… renames or removes one in every card	Names already used are offered while typing, so a file keeps one vocabulary
Templates	Files model cards in a box named Templates; New ▸ Copy of a Card… offers them first	A copy keeps content, attributes and card links, is filed where the original is, and remembers its origin
Duplicate	Copies any card (Cmd+D in the file window)	The same copy rules; a box is copied empty
Fonts	Chooses the fonts cards are shown in	A setting of the application; cards store no fonts

Together these let a user build a working method in a file: an argument schema in link types, a status scheme in attributes, a form in a template. This file uses all three: the link types Source and Depends on, the attributes Issue, Status and Pages, and the template "Issue (template)".

Extension by programmers. The core is taught what kinds of content, card, embedded object and reserved link type exist through registries. The interface has matching registries for editors, renderers, the New menu and inserters. Every kind of card Scheda has (text, reference, filebox, sketch, browser) is added this way, so a new kind is a new module, not a change to the core. Content the running build cannot read is kept untouched, byte for byte.

No user plugins. Scheda's direct predecessor had plugins; Scheda deliberately does not. Plugins would bring an interpreter, a loading mechanism, reliability and compatibility promises into a one-binary application. The structure API is the planned extension surface for users, through scripting.

What remains open

A non-programmer still cannot define a new kind of card or a new view. Whether scripting over Structure makes that easy enough is the open question Halasz left: tailoring that takes a small effort for a small change.

References

[]{#reference-1}[1] Halasz 1987: Reflections on NoteCards. doi.org/10.1145/317426.317451