3e8.org

This is a short guide to starting up Symbolics Concordia in a Virtual Lisp Machine (VLM) running OpenGenera. It was written because the existing tutorials on the Symbolics VLM teach you the basics of building one and starting it up, but stop after the login prompt.

Concordia is a software documentation tool that produces output that can be read in Genera's Document Examiner, an early hypertext browser. The documentation system was extremely advanced for its time and can still be admired today for its usefulness, thoroughness, and excellent technical writing; it is worth exploring.

We assume you've already started up a VLM and configured it for your site, that the VLM machine is called GENERA, and the VM host system is called GENERA-HOST, as in this tutorial. We'll also pretend you used ARIANA for your site name when you defined your site at first boot. You should have run through the Genera Workbook in Document Examiner to become familiar with Genera as well. At the very least, you will need to know where a few important keys are, such as <Select> on F1, <Help> on F12, <Abort> on F6, and <Super> on F7.

Concordia won't be available as an Activity (selectable application) nor will its documentation appear in Document Examiner until you load the Concordia system:

Command: Load System Concordia

The necessary pieces are loaded into memory, including the documentation, and the Concordia activity is made available on <Select> W. You can see this with <Select> ?.

Now we need to enable file locking. Without this, Concordia will refuse to save files, and you can't generate any docs. For example, if you try to save (c-X c-S) a new buffer to GENERA‑HOST:/var/lib/symbolics/test.sab, an error will occur.

(Press <Super> A or <Abort> to continue after this error — hopefully, you figured out where your keys are.)

We will enable locking (LOCK-SIMPLE protocol over TCP) on host GENERA (our local VLM) and specify it as a surrogate locking server. This surrogate server will handle locking for servers that do not support the LOCK-SIMPLE protocol, such as our GENERA-HOST file server where the Concordia system and our files reside.

Update the VLM's HOST namespace object to advertise the LOCK-SIMPLE service:

add services to hosts lock-simple tcp lock-simple GENERA

Enable the LOCK-SIMPLE service:

enable services lock-simple

Now set GENERA up as a surrogate locking server by editing the namespace object for the entire site ARIANA, and adding a property which instructs everyone in the site to fall back to GENERA for locking:

edit namespace object site ARIANA
 -> User Property: LOCK-SIMPLE-SERVER GENERA
 -> Save Object
 -> Quit

Now Concordia can lock and save files.

At this point you can read the Symbolics Concordia Workbook through Document Examiner, which walks you through creating a simple document. Below, <Select> should be on the F1 key.

<Select> D
Show Documentation Symbolics Concordia Workbook
<Select> W
; start creating documentation!

Here is an example of the record you'll create in the first section of the workbook.

The lock-simple service runs on TCP port :666. For further details, try:

Load System version-control-doc
show doc The Lock-simple Network Service
show doc Symbolics Concordia Installation Guide