Paolo Amoroso's Journal

sysrama

I'm examining in depth NoteCards, the hypermedia environment of Medley Interlisp well described in the 1987 paper NoteCards in a Nutshell.

To experiment with the NoteCards API I set out to explore the space of possible answers to the question: what if Lisp programs were represented as NoteCards hypertexts? Leveraging NoteCards to play with the idea seemed like a natural extension to Sysrama, my Interlisp documentation tool for presenting information on the objects of Lisp programs.

The rich environment of NoteCards allowed me to quickly put together what I wanted as the system provides an extensive, well designed, well documented, and easy to use API.

Generating hypertexts with NoteCards and Sysrama

As a start I wrote a Sysrama function that produces a hypertext representation of a program by querying the File Manager. The function, appropriately named CODECARDS, creates a notefile and populates it with cards and fileboxes.

In NoteCards, a “card” is the unit of information the nodes of a hypertext network store and present. A card can hold text, media, and more. A “filebox” is a container of cards and fileboxes. The fileboxes and cards of a hypertext are stored on disk in a “notefile”.

CODECARDS, which is passed the file name of a program as the only argument, sets up a filebox for every non empty File Manager type of the program. It further creates one card for every Lisp object of the type, fills the card with information on the object, and files the card under the type's filebox. The fileboxes are filed under the Table of Contents filebox. A side effect of filing the cards and fileboxes is the creation of a series of system links to construct and navigate the hierarchical structure.

The generated cards and fileboxes can be manipulated with NoteCards' suite of hypertext editing and navigation tools such as the graph browser.

After evaluating (CODECARDS 'SYSRAMA) to process Sysrama's own code, opening some fileboxes and cards, and arranging them on the desktop the Medley screen may look like this:

Some fileboxes and cards of a NoteCards hypertext on Medley Interlisp.

The Table of Context filebox in the top row of windows, between the NoteCards icon and the Medley logo, contains links to the fileboxes of the File Manager types. The links are the rectangular outlines with an icon at the left and a textual description in the rest of the outline.

Clicking on the VARS (variables), FNS (functions), and EXPRESSIONS (expressions) links of the Table of Contents opens the corresponding fileboxes of the middle row of windows. Section FILE BOXES has no entries because the fileboxes contain only cards.

The leftmost in the bottom row of three windows is the filebox of the type FNS (functions). Every one of its links leads to the card of the Lisp function indicated by the link name. The two rightmost windows of the bottom row are the cards of functions CODECARDS and DESCRIBEFNS with the shown signatures ((CODECARDS FILE) and (DESCRIBEFNS FNS TYPE)) and type (EXPR LAMBDA-spread).

The window at the bottom left of the screen is a browser, a NoteCards editing and navigation tool for visualizing and manipulating a hypertext as a graph. The trees in the browser represent the hierarchical structures of fileboxes and cards CODECARDS produces.

Note the VARS, FNS, and FILEVARS fileboxes at the roots of the trees in the browser. The leaves are cards.

Sysrama and the File Manager

The Medley File Manager should not be confused with the similarly named tool of desktop operating systems for navigating and manipulating files and folders. As I wrote in a post on using Common Lisp in the residential environment:

The File Manager, also known as “File Package” (not to be confused with Common Lisp packages), is a facility that coordinates the development tools and code management tasks. It notices the changes to Lisp objects edited with SEdit or manipulated in memory, tracks what changed functions and objects need to be saved to symbolic files, and carries out the actions for building programs such as compiling or listing them. The File Manager has some of the functionality of Unix Make.

The File Manager stores Lisp sources in “symbolic files”, which are code and metadata databases rather than ordinary source files.

Sysrama and CODECARDS query the File Manager metadata associated with a program to present information about its Lisp objects, such as functions and variables, and build a notefile.

Next steps

So far CODECARDS doesn't do much as it's an early proof of concept to explore the idea of representing programs as hypertexts. The evolution of the feature will point to where the idea can lead.

The hypertext functionality of Sysrama relies only on system links and doesn't define user links, i.e. user defined connections that establish typed relationships between the end points. Also, I'm thinking about whether and how to update the notefile with the changes the associated program undergoes during development.

The next tasks I'll likely work on are fleshing out the information in the Lisp object cards and defining some user links.

#Interlisp #sysrama #Lisp

Discuss... Email | Reply @amoroso@fosstodon.org

I'm writing another Interlisp program, Sysrama, an Interlisp documentation tool for presenting information on the Lisp objects of a program. It produces reports that list the types and signatures of functions, the fields of records, global variables, property lists, Executive commands, and more.

The way I reference the details of Lisp objects when coding gave me the idea for Sysrama.

I often forget the names and signatures of the functions or the names of the record fields I need. Browsing or looking up the code for referencing them is a source of friction.

Interlisp comes with the powerful program analysys tool Masterscope that gives its best with answering specific questions on the internals of programs. But it has a steep learning curve and it doesn't provide the kind of big picture view I seek. Instead, I wanted a simple tool for producing an overview of the main Lisp objects in a program.

This is a sample report Sysrama prints on another of my Interlisp programs, Stringscope:

Sample output of the Sysrama documentation tool for Interlisp.

The main sections group objects under the same File Manager types, such as FNS or RECORDS. This is because Sysrama can extract information only from programs under File Manager control.

Suppose you want to analyze the Lisp program MYPROG. Once Sysrama is in memory, load MYPROG:

(LOAD 'MYPROG)

To have Sysrama print a report with information on MYPROG evaluate:

(SUMMARIZE 'MYPROG)

You can narrow down the information to specific File Manager types such as FNS and RECORDS:

(SUMMARIZE 'MYPROG '(FNS RECORDS))

or to specific objects like the function MYFUN:

(SUMMARIZE 'MYPROG 'FNS 'MYFUN)

More documentation is available at the project repo.

Sysrama already does most of what I had in mind but I'll implement a few more features.

I'll tweak the reports to show more information on some Lisp objects. And I'll add the ability to redirect the output to a scrollable window rather than to the primary output stream. By default Interlisp windows don't save the output history and can't be scrolled back, so such a feature will help review reports that don't fit in a window.

#sysrama #Interlisp #Lisp

Discuss... Email | Reply @amoroso@fosstodon.org