Paolo Amoroso's Journal

Success!

My WebCard prototype made NoteCards visit a site on the World-Wide Web for the first time. Think of it as a wormhole that connects the old world of hypertext with the new world of the modern web. WebCard, a NoteCards extension for visiting websites, is my RetroChallenge 2024 project.

This is my Linux desktop just after NoteCards visited a website for the very first time:

The Table of Contents window near the bottom left of the screen is a filebox of a NoteCards hypertext. Under “NOTE CARDS” the filebox container card lists a link icon, a clickable area that leads to the indicated card “Medley Interlisp Project”. This card of type Web inherits from the type Text and holds a URL to visit.

When I clicked on “Medley Interlisp Project”, WebCard opened the corresponding card — blank in the screenshot — next to the Table of Contents. Then WebCard commanded Firefox to visit the URL https://interlisp.org stored in the card. The window of Firefox, already running, came to the foreground and displayed the website in a new tab.

This milestone comes after fixing a bug in the Web card constructor. To put my core idea to the test I deferred some non essential refinements and went straight for the website visiting functionality.

How does the functionality work? The NoteCards API provides a hook to override the operation of traversing links to specific types of card. To this effect WebCard sets an alternate function as the value of the LinkIconLeftButtonFn property of the symbol Web that names the type. NoteCards calls the alternate function when a clicked link has a Web card as the destination.

WebCard's alternate function is WCD.TraverseWebLink. It fetches the URL from a card, displays the card, and opens the URL in the system browser.

The screenshot shows both the Web card, next to the Table of Contents, and the code of WCD.TraverseWebLink in the Lisp editor at the top center. The comment, however, is out of date after fixing a series of issues.

What went wrong? A combination of misunderstandings and incomplete information made WebCard generate argument type errors, as I wasn't sure about the arguments of WCD.TraverseWebLink. On top of this, I called the internal function NC.TraverseLink that implements the default link traversal but I ended up not needing anyway.

Reading the sources of a few NoteCards functions cleared all doubts. To fix the issues I updated the code of WCD.TraverseWebLink but not the comment as I was eager for a test run.

The WebCard prototype is crude, but it works and validats my strategy of overriding the link traversal behavior.

An alternative I initially considered is to advise the NoteCards API functions for opening and displaying cards. However, unlike overriding link traversal which the API fully supports, advising is a fragile kludge that works around the API.

Now that the core feature of WebCard is in place I can continue the development.

WebCard is far from complete. There's still work to do to override editing Web cards, extend Web card construction, deal with input validation and error handling, check for visited URLs, and customize the bitmap of Web link icons. WebCard needs documentation and demo notefiles too.

#WebCard #Interlisp #Lisp

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

I fixed a bug in the initial code of WebCard, my RetroChallenge 2024 project.

An infinite loop in the constructor of the Web card type caused a stack overflow that aborted Medley. The Web constructor was supposed to call the constructor of the parent card type Text. But I misunderstood the NoteCards API and used NCP.CardTypeFn which ended up calling the Web constructor itself, hence the infinite loop.

The fix was easy: call the supertype's constructor with NCP.ApplySuperTypeFn. Troubleshooting the issue was a great learning experience.

With the bug out of the way I fleshed out a bit more of the Web card constructor. I wrote code to query the user for a URL and store it in the property list of the card. This gives persistence for free as NoteCards automatically stores properties to and retrieves them from notefiles.

There's still some card initialization to do in the case the constructor is passed the option to not display the card, but I'll leave it for later.

In my initial plan the constructor would query the user also for an optional card title but I dropped the idea. NoteCards already allows adding and editing card titles, so forcing this from the constructor seems redundant and possibly confusing. Like NoteCards, by default WebCard names new cards Untitled.

Reporting my progress and plans to the Medley Interlisp team sparked an interesting conversation on rapid prototyping in Interlisp and the Lisp development style. For example, I learned the Interlisp advising functionality was designed as a prototyping tool.

I'm not yet sure what to work next, whether to handle card editing or go straight for the website visiting functionality. The latter is the only missing piece of an early prototype.

#WebCard #Interlisp #Lisp

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

The initial Interlisp code of WebCard, my RetroChallenge 2024 project, defines the new type “Web” of NoteCards card. It's the first step for extending NoteCards to visit websites.

The main code is in the function WCD.CreateWebCardType, a thin wrapper around the NoteCards API function NCP.CreateCardType. The former passes to the latter the name of the new type Web, the name of the type Text it inherits from, an alist of functions that implement the overridden card operations, and an alist of customization parameters.

So far the only operation the Web type overrides is card creation via the constructor WCD.MakeWebCard. The function crashes Medley and ends the session but I left it there as I wanted to have something in place.

Although the initial code is little more than a stub, it's an important foundation the rest of WebCard will flesh out or build upon.

Next, I need to figure out why WCD.MakeWebCard crashes. Aside from removing a roadblock, the troubleshooting will provide insight into how card creation works.

The code is available at the project repo. WebCard function names and symbols start with the WCD. prefix as a form of limited namespace isolation as Interlisp has nod direct support for packages.

#WebCard #Interlisp #Lisp

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

Now that I entered the RetroChallenge 2024 the next step is to flesh out the scope and details of my WebCard project, a NoteCards extension for visiting websites. What will WebCard do? How will it work?

Specification

In NoteCards the area of a card or filebox that makes up a link icon, when clicked, displays a destination card or filebox. Links typically look like outlined rectangles that contain a bitmap and the title of the destination.

The destination of a WebCard link is a page on the World-Wide Web designated by a URL.

Clicking on a WebCard link icon, which has a custom bitmap, will launch the web browser of the host operating system, if not already running, and direct the browser to visit the URL associated with the WebCard link. WebCard will also display a stand in NoteCards card that shows the URL and title of the web page, advising to view the page itself in the browser. No text, links, or media can be inserted in the stand in card.

Clicking on the same WebCard link more than once will notify that the associated web page may already be displayed in the browser, offering to direct the browser to visit the page again.

Other than that WebCard and NoteCards will have no control over the browser and its tabs and windows, which the user may close or change at any time. Since WebCard is not a WebView it won't render web pages or HTML either.

To add a web link to a hypertext the user will create a card of type Web. WebCard will ask for the destination URL and an optional title and create a stand in card that displays the information. The user will then insert NoteCards links to Web cards with the usual link creation commands and specify an appropriate stand in card as the destination.

WebCard will come with basic documentation and sample notefiles that demonstrate web links.

Design

To implement this functionality WebCard needs a way of opening web pages in a browser and adding clickable web links to a hypertext.

Opening web pages

Opening web pages from Lisp is easy.

As part of the modernization effort the Medley Interlisp team implemented UNIXUTILS, a library of utilities for running Unix programs and controlling processes. The UNIXUTILS function ShellBrowse does exactly what I want: it executes the xdg-open command of the host operating system and passes it a URL to open in the system browser.

As a consequence of this decision the host operating system must support the relevant XDG specification.

Adding clickable web links

As for inserting clickable web links, the design of NoteCards funnels to a natural solution.

In NoteCards, the destination of a link must be a card or filebox. Therefore, for a link to lead to a web site, the link can have as its destination a special card that stands for the associated web URL. Traversing that link triggers the activation of the web browser.

The NoteCards API supports defining new types of cards with custom behavior implemented as a set of standard operations. Since card types are arranged in an inheritance hierarchy, defining a new type often involves overriding just a few operations and letting the system invoke the default behavior of the parent types for the others.

WebCard will define the new card type Web that inherits from the Text card. I expect to override a handful of operations, mostly for card creation and editing.

WebCard needs to activate the browser when a Web card is opened or displayed as a result of traversing a link. But since the API doesn't support overriding or hooking into these operations I'll have to come up with something different, such as advising the default behavior. The advice will direct the browser to visit the URL and pass control to the default behavior to open or display the stand in Web card in NoteCards.

The NoteCards API does allow to override the operation of traversing links to cards. I may augment such a behavior to also control the browser for Web card destinations, which may be easier and cleaner than adivising other operations.

As for editing, WebCard will allow changing only the URL and title of a card but not the content. Aside from that, I hope to get away with skipping the default editing behavior without having to interact with TEdit. It's an indirect way of making the Web card content read only.

Discussion

Along with the supporting functions and data, implementing this functionality should be achievable in one month or less.

WebCard will have little control over a web browser. In addition, web pages will be displayed only in a browser outside of NoteCards. Despite the limitations, I expect WebCard to provide genuinely useful functionality and allow integrating hypertexts with external content.

The design of WebCard is similar to traditional NoteCards extensions. When the system was in active use in the 1980s, some extensions invoked external functionality such as controlling laserdiscs or playing media, or connecting to dial-up databases to perform queries and populate cards with the results.

#WebCard #Interlisp #Lisp

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

Team Lisp is ready to play: I'm entering the RetroChallenge 2024 (RC2024) with a NoteCards project targeting Medley Interlisp.

The RC2024 announcement explains the point of the challenge is to do something new, learn, and have fun with retro systems:

In a nutshell, the RetroChallenge is a loosely disorganised gathering of RetroComputing enthusiasts who collectively do stuff with old computers for a month.

The goal of my RC2024 project, WebCard, is to extend NoteCards to visit sites on the World-Wide Web. The project logo borrows the NoteCards card box icon and its nice retro vibes:

NoteCards is a pioneering hypermedia system developed at Xerox PARC in the 1980s as a Medley Interlisp application. Since it's a pre-web system, NoteCards runs locally and never interacted directly with the web. So I'll develop an extension to open sites using the web browser of the host operating system Medley Interlisp runs under.

However, WebCard is not meant as a WebView or anything like that. Although it will just open websites by calling a modern browser, the feature will expand the hypertext capabilities of NoteCards in interesting ways.

My main motivation for the project is to continue the learning and fun I'm having experimenting with NoteCards.

This is also an opportunity to bridge the past and present of hypertext. And, since I'm in the Medley Interlisp project team who comprises some of the original developers, including NoteCards co-creator Frank Halasz, I'll be able to discuss and learn the system from its own implementors. Which, again, is a way of bridging the past and present of computing.

I will host the code on the WebCard repository, publish reports on the project blog (feed), and post short but more frequent updates on my @amoroso@fosstodon.org Mastodon account under the RC2024 hashtag.

This idea is a crazy frankentext but it can work. I look forward to clicking the start link.

#WebCard #Interlisp #Lisp

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

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:

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

Although online access to Medley Interlisp is convenient and prebuilt binaries are available for all major operating system, it's also possible to compile it from source.

I first built Medley from source when I wanted to run it on my Raspberry Pi 400 and no ARM64 binaries were available. I later built Medley on Linux to try other options such as SDL2 support instead of X11. Since the build process is simple and fast, even on low-end devices such as the Pi 400, now I often do it on Linux.

There are some compilation instructions and notes for Maiko and Medley (see also the scripts README) but not a full build guide, so I fleshed out the details with the help of the project team.

I initially didn't write down the process as I relied on memory, which sometimes made me take wrong turns and waste time. This post finally puts together all the required steps and information for my own reference, and I hope it will be useful to you too.

Building Medley involves downloading the sources, configuring the environment, compiling the Maiko Virtual Machine, and generating the Medley system image.

What to build

Medley provides a number of compilation options, such as SDL2 support as an alternative to X11, with configurations that range from a minimal system to a complete build that includes all the Lisp applications like NoteCards.

These instructions cover building the complete system, which Medley veterans frequently refer to as the “apps sysout” as a sysout is a Lisp image.

Assumptions

The process I describe assumes you'll build the system on Linux using Clang. If you prefer Gcc the Maiko README file explains what to do. In addition I assume you're familiar with the Unix C toolchain and the shell.

Although the instructions may work on similar platforms, if you're not on Linux you'll need to adapt them to your setup.

The setup

The tools to compile Medley are the same as for C development on Linux, with a few additional dependencies. Make sure the following packages are installed on your system:

• Clang: clang
• Make: make
• X11 development libraries: libx11-dev
• SDL2 development libraries (optional): libsdl2-dev

libsdl2-dev is needed only if you want SDL2 instead of X11.

I store the Medley sources under ~/interlisp and the build instructions assume this location. Change to the ~/interlisp directory and download the required files.

The Medley Interlisp project automatically publishes weekly binary builds whereas the project repositories hold the source tree. Since there is really no stable source release per se, these instructions assume you use git to download the sources of Maiko, Medley, and NoteCards:

$ cd ~/interlisp
$ git clone https://github.com/Interlisp/maiko.git
$ git clone https://github.com/Interlisp/medley.git
$ git clone https://github.com/Interlisp/notecards.git

The repos are pretty large, so to save space and bandwidth you may want to run git with the --depth 1 option.

After the download the source directory will contain the following subdirectories:

.
├── maiko
├── medley
└── notecards

The build steps

The Medley system consists of two layers, Maiko and the Medley environment.

The bottom layer is the Maiko Virtual Machine, written in C, which implements the evolution of the microcode of the Xerox workstations that ran Interlisp-D in the 1980s. The rest of the system in the top layer, the actual Medley environment the user interacts with, is written in Lisp.

The build process reflects this layered organization. You first compile Maiko with the C toolchain, then run the scripts that drive the Lisp environment to compile the Lisp sources and produce a loadable image, i.e. a sysout.

Building Maiko

Start by changing to the maiko/bin directory of your source tree. To build Maiko for X11 clean up any leftovers from prior invocations and run the build:

$ cd ~/interlisp/maiko/bin
$ ./makeright x cleanup
$ ./makeright x

Next, build the ldeinit Maiko tool required for producing the apps sysout:

$ ./makeright init

These steps create the executable files lde, ldex, and ldeinit under ../ostype.cputype, e.g. ../linux.x86_64 on typical Linux systems. Move the lde* programs to or symlink them from somewhere in your executable path.

If you want the SDL2 version instead of X11 substitute sdl for x in the above build commands:

$ ./makeright sdl cleanup
$ ./makeright sdl
$ ./makeright init

On my Linux system these compilation steps collectively take a dozen seconds of runtime.

Doing the loadup

The final step is to make the apps loadup.

A “load up”, or just “loadup”, is a platform independent Lisp image generated by the Lisp side of the build process. Historically, building the Medley sysout was called “doing a loadup”. Along with an image, doing the loadup produces a set of compiled Lisp and supporting files.

To do the loadup change to the Medley directory ~/interlisp/medley, remove the loadups subdirectory to clean up any leftovers from prior builds, and launch the driver script loadup-all.sh in the scripts subdirectory:

$ cd ~/interlisp/medley
$ ./scripts/loadup-all.sh -apps

The Medley graphical environment will open several times and print log messages on the files it is compiling or other status information.

During this step it is amazing to watch the Medley window and log messages zip by in seconds in a process that took many hours back in the day. On my Linux system this step completes in about 3 minutes and 10 seconds.

Testing the build

Your environment is already set up for building Medley and no additional steps are required for installing and running it.

When the build ends, test Medley by launching the medley command. For example, execute medley with the -a option to load the applications, -e to start an Interlisp Exec, and -n to remove the screen scroll bars that are not much useful:

$ cd ~/interlisp/medley
$ ./medley -a -e -n &

Execute ./medley --help to get a brief help message with a list of the command line options, and ./medley -z to read the manual page.

#Interlisp #Lisp

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

I upgraded my System76 Merkaat mini PC from Linux Mint 21.3 Cinnamon to Mint 22 “Wilma”. It didn't go as hoped but some extra effort eventually made Mint 22 run fine.

I began by starting the upgrade process from Mint 21.3.

I didn't get a good feel for the upgrade tool, with a confusing user interface that labels some buttons Fix when “proceed” is actually meant. But it didn't matter as the tool aborted with this error that, while totally obscure, made it very clear I'd face an uphill battle if I dared to proceed and troubleshoot the issue.

I didn't want to stay on 21.3, so the only option was a full install of Mint 22.

The Merkaat initially reported a media error when booting the Mint 22 USB stick, which is unexpected since it's a Philips unit bought less than a month ago and used only a few times. A restart of the Merkaat resolved the issue and the Mint 22 installer finished smoothly.

With a backup of the Mint 21.3 user data handy, it took me about three hours to reconfigure the system. But I'm finally writing this from Mint 22.

I originally intended to do full installs only for major Mint releases, and go through the upgrade process for point releases. But, since I'm new to Mint, I was curious to try the upgrade tool now.

The failure of the tool is surprising because I ran it under the most favourable conditions, i.e. on hardware designed for Linux, under a Linux system installed less than a month earlier with minimal changes or bitrot. However, since it's so unreliable I will always upgrade via full installs.

#Linux

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