> title: Symbolics Concordia in a Virtual Lisp Machine
> date: 2016-04-04T22:29:00-05:00
> tags Symbolics Concordia Genera VLM

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 {a @ href
https://github.com/ynniv/opengenera/blob/master/README.md : 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:

> jump

| Command: Load System Concordia

[img @ src /blog/assets/load-system-concordia-short.png
     @ alt: Depiction of loading the Concordia system]

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 ({tt: c-X c-S}) a new
buffer to {tt GENERA {& `#x2011`} HOST:/var/lib/symbolics/test.sab}, an error will
occur.

; By the way, a bare #x2011 above is interpreted as a Scheme number by zmarkup and is
; converted to base 10, which fails because & is expecting a named entity such as
; `#nnnn`.  And raw UTF-8 chars are broken and need fixing.

[img @ src /blog/assets/concordia-lock-failure.png
     @ alt: An example lock failure error]

(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

[img @ src /blog/assets/add-lock-simple-service.png
     @ alt: Depiction of adding the lock-simple service]

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

[img @ src /blog/assets/namespace-editor-lock-simple.png
     @ alt: Namespace editor screen showing the lock-simple property]

Now Concordia can lock and save files.

[img @ src /blog/assets/concordia-lock-success.png
     @ alt: A successful lock message]

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.

[img @ src /blog/assets/concordia-workbook-record.png
     @ alt: Example Concordia workbook record]

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