README.org

What is Leisure?

Simply put, Leisure is a document-oriented, exploratory computing environment for what we call Illuminated Programming. Leisure documents are:

• editable
• collaborative
• interactive
• web-based (zero install)

Illuminated Programming is our term for application, source code, and data, all rolled up into one interactive, collboratively editable document. A Leisure document might hide its code and data and appear to be just an app or it might present the code and data along with the app(s), like this Leisure game does, or it might be mostly a document with interactive examples in it.

A lot of this has been around for quite a while, Hypercard and Mathematica are interactive documents that contain code and data, and people are starting to work on modern interactive documents, like Jupyter (based on the iPython Notebook).

Leisure is a little different because it’s purely web-based, no install needed, and it’s collaborative. We’ve been working (relatively) quietly on Leisure since 2011.

We think it’s well past time for an open-source, web-based Illuminated Programming environment for everyone.

Leisure connection mode for Emacs

This is a minor mode that connects an emacs buffer to Leisure web page.

NOTE: LEISURE CURRENTLY ONLY RUNS IN CHROMIUM-BASED BROWSERS (LIKE CHROME).

If you are viewing this in Emacs and you already have leisure-connection-mode loaded, you can try this out by CLICKING THIS LINK.

NOTE: We’re not orgmode experts and we need help from people who are!

Bidirectional connection to Emacs

Leisure uses orgmode as its file format and it can hook up to Emacs.

Toggling leisure-connection-mode will open and close a web page associated with the current buffer.

You can also start in Leisure and connect to Emacs, provided that Emacs is running the Leisure service. Leisure-connection-mode automatically turns on the service but you can also control it with the elisp:leisure-start and elisp:leisure-stop commands.

Once connected, changes in Emacs are mirrored in Leisure, and vice versa. In Leisure, if you hit C-C C-C or click an elisp link, it will delegate that to Emacs. Leisure will also attempt to fetch “file:” image data from Emacs so it can display the results of your file-based computations.

Work in progress

Leisure is not quite stable, yet

• Leisure is a work in progress
• It’s NOT HARDENED
  • Don’t rely on Leisure for super-important tasks yet!
  • Leisure won’t destroy Emacs’ undo history, so it should be safe to use
• It doesn’t support parts of orgmode, yet
  • Like tables
  • And stuff
  • We’ll get there
  • There’s a lot to do, pitch in and help!

But that doesn’t mean you can’t use it!

• You can still benefit from Leisure’s features, like interactive views, value sliders, etc.
• You can edit in Emacs and keep a Leisure browser next to it to see your formatted document as you type
• Leisure just changes the document text and then sends to Emacs.
• If Leisure gets messed up, you can just reload the webpage one of these ways!
  • revert the buffer
  • use the leisure-reload command
  • use the browser to reload the page
  • close the page and reopen it from Emacs
  • execute elisp:leisure-connection-mode to close and open the browser window
  • Leisure will connect right back to your Emacs buffer
• You can use Emacs’ fabulous undo support if you use Leisure to make a change and it somehow messes up.
  • Leisure and Emacs are just sending text changes to each other

Emacs code-execution

(Wanna see the source? Click the martini glass.)

Leisure can use orgmode’s code execution features.

If you hit C-c C-c in a language that Leisure can’t execute (e.g. sh), Leisure will attempt to execute in Emacs. You can try it here:

ls /tmp

Webby code blocks execute in the browser directly.

Go to Leisure and hit C-C C-C in this block:

alert 'hello'

This is a dynamic block. Go to Emacs and alter the code in this block and Leisure will update the results as you type.

3 + 4

Clicking an elisp link in Leisure will run it in Emacs. Click this and it will show a message in Emacs.

(Why) does Leisure flicker after an Emacs command?

• When Emacs asks you permission to execute a code block, the Emacs

window takes input focus

• After the command executes, the Leisure connection code in Emacs attempts to send focus back to the browser.
• Browser focus is a tricky thing because of spammers

You may notice a popup notice in your browser’s location bar. If you enable popups from Leisure, the browser will be able to take focus back after it executes a remote Emacs command.

Once you enable popups, the browser will flicker, slightly when it takes focus back. This is because in order to reactivate the browser, Leisure has to quickly open a temporary window and that is what causes the flicker.

Emacs file service

When connected to Emacs, Leisure uses Emacs to access file: links so that it can display them in the browser.

Here’s the emacs logo from a file link:

When not connected to Emacs, Leisure attempts to use local urls instead. Sometimes that works :).

Code syntax highlighting

Leisure uses Prism to highlight syntax as you type. Here’s an example:

# Some CoffeeScript
@maluba = (x)-> x + 52

Source and slides

• You can click the martini glass to view/edit orgmode source
• You can use the toolar to start a slideshow using top-level headlines as slides

Themes

Leisure was built to be modded.

• You can choose themes in the Leisure toolbar
• You can set a default theme in the Emacs leisure customize group
• Your documents can override a lot of how Leisure renders
• You can experiment with the built-in themes in the “Visual” panel above

Views

Leisure uses Handlebars to define HTML views for different types of data. This is what it uses for its normal display (called “fancy mode”).

• You can tweak Leisure’s rendering by overriding parts of defaults.lorg in your document

HTML templates

Leisure uses Handlebars templates and it use data from the document when it renders them.

This is Fred. The HTML snippet below displays Fred’s name and the name’s length. Change it to see the HTML below update.

name: Fred

Here’s some Html that uses Fred and Fred’s controller.

Hello {{name}} Name length:

This is Fred’s controller

@initializeView = (view, data)->
  $(view).find('[name=len]').html data.name.length

View definitions

Leisure uses “leisure:” links to display data, based on the data’s “type” field. You can nest views and even pick alternate views for the same types of data by specifying a view name in the link. At this point, Leisure uses YAML data for its views.

Leisure uses this presentation system when it displays every Leisure document and you can redefine how Leisure displays its document parts in the documents themselves (but you have to be verrry careful when you redefine things at such a low-level. So a lot of Leisure’s document display is defined in Leisure. It’s so meta

This YAML data controls the rotating square and line below.

• Click the degrees value and move the slider that pops up
• When you let go of the sider, it snaps to the middle so the value can keep changing
• Watch it update in both Emacs and Leisure
• You can edit the value in Emacs and it will update in Leisure

type: rotator
degrees: 90

leisure:rotator leisure:rotator/two

Fiddle with these view definitions and you’ll see the views change.

<div style='padding: 25px; display: inline-block'>
  <div style='transform: rotate({{degrees}}deg); height: 100px;width: 100px;background: green'></div>
</div>

<div style='padding: 25px; padding-left: 100px; display: inline-block'>
  <div style='transform-origin: 5px 100px; transform: rotate(calc(90deg - {{degrees}}deg));height: 100px;width: 10px;background: red'></div>
</div>

You Can Has Media Because Web

Here is a nice video by John Kitchin about Orgmode.

Babel

If you are connected to Emacs and have access to plantuml and ditaa, you can change these diagrams and the pictures will update in Leisure.

Features in Old Leisure

This new version doesn’t have all of the features of the old version, yet…

Local headlines

Top-level headlines marked “local” are copy-on-write and the copy is optionally stored in your browser’s local storage. This isolates user changes from the main document and lets users make (potentially persistent) changes that don’t leave their browser.

Also, this is very important for collaboration (see below) because it lets users have their own versions of shared objects, like data. This allows, for instance, a named data block to contain different, user-specific GUI state for each user.

#+RESULTS[0e2f17b475aa320de4bf4a5d0444c17f7732b883]:

Collaboration

The new version will take a more peer-to-peer approach but, because symmetric NAT remains a crippling problem for WebRTC, it will use a server as a message-passing “switchboard”. The session-initiator will serve as the “session master”.

#+RESULTS[611e8190dd1c9956a6caeeae655284026beb965f]:

Imports

Imported document data is merged into the current document using copy-on-write.

Code Discussions

The old version uses GitHub issues so other people can discuss your code. but we may switch to a service(s) like Disqus.

Test cases

Converting code into a visual test case result is an imporant feature we plan to bring back very soon.

Some Leisure History

Leisure started out as an experimental, dynamically typed, lazy, functional programming language with strong support for metaprogramming (quite a mouthful, isn’t it?). Soon, TEAM CTHUHLU wanted to extend our experiment into programming environments. Leisure was already web-based, why shouldn’t it exploit the powers of the Web?

We didn’t start from orgmode – we hadn’t even heard of it. We did, however, already know the power of text; we had experimented with text-based computing environments more than 10 years ago, we even had a text-based auto-formatted table that could use spreadsheet formulas! So when we did learn about orgmode, we immediately felt a great affinity for it.

We started with Markdown and it was great. For a while. When we decided that Leisure documents should contain data, as well as code, we started running up against Markdown’s lack of metadata.

Since that time, there have been several architectural overhauls and now the architectore seems to be relatively stable and simpler than it has been in the past.

Investigations pointed us towards orgmode.

Orgmode features missing from Leisure

Leisure is a stand-alone computation environment that uses orgmode’s excellent file format, it’s primary purpose is not to be an extension of orgmode. Nevertheless, using it as such is a fine way to use Leisure, if that’s all you need it for.

There are a lot of things left to do!

• orgmode-style collapse-cycling
• more org structure support
  • tables
  • tags
  • lots of other things :)

How you can help!

• Report bugs
• Contribute code
• Contribute documentation
  • We need a lot of it
  • In Leisure documents (of course)
  • With interactive examples (illuminated documents)
• Request features

Hidden slides

There are some hidden settings and you can reveal and hide them by clicking Show/Hide at the top of the page.

Settings