Fargo is a rich product, but there are so many things people want to do with outlines, we can't possibly add commands for all of it. That's why we have created a simple scripting interface for the Fargo outliner. This document both explains how it works today, and gives an idea of how it will evolve.

We don't need to create a scripting language for Fargo, as we did for earlier outliners -- because it's already embedded in a powerful scripting environment -- JavaScript running in the browser. So all the scripts you write for Fargo will be in JavaScript.

That's got its pluses and minuses. It's good because JavaScript is fast, and a lot of people know how to program in it. But JavaScript is more of a systems language than a scripting language. It can do a lot, but sometimes even simple things are a bit complicated.

So JavaScript is the syntax of scripting in Fargo, what about the nouns and verbs -- the things it operates on and the things it can do.

In Fargo, you're operating on the current outline, the one in the selected tab, and the item that the bar cursor points to. For example, a script can move the cursor relative to its current location, reorganize the outline, expand and collapse, get an OPML version of the outline.

We also have hooks into the file system, which is of course Dropbox. You can write a file anywhere in the Fargo folder, and can get a public URL for that file.

You can also call any built-in JavaScript function, but be careful, as explained in the next section.

Up till now we've said emphatically that Fargo is not a platform. This is because you could get in and script stuff in Fargo, if you're willing to do a lot of work. But we're not committing to the internal structure of the program. If you call code inside Fargo from your scripts, you should assume that your code will break in the next Fargo update.

But now we're making an exception to the no-platform rule. We're going to slowly build a set of safe functions you can call, ones that should not change over time. Because we're making that commitment, evolution of this set of verbs will be done carefully and slowly with much consideration toward backward compatibility.

A caveat: While no-breakage is an ideal, sometimes breakage happens anyway. These verbs are as safe as they can be. We've had good luck with this in the Frontier scripting platform. Scripts written in the early 90s in Frontier still run today. But you never know what can happen. So it's not a contractual no-breakage rule, rather it's a statement of principle.

Today we have an initial set of verbs that you can try out the scripting interface with. We will take suggestions for new verbs, on the smallpicture-script mail list, preferably in the form of links to blog posts where the idea is explained, and discussion can take place.

The safe verbs are in a file called fargoVerbs.js.

When looking through that list, focus on the interfaces, not what's behind them.

It's the interfaces that are safe.

So if you want to make a beep sound on the speaker, call speaker.beep (), not the code inside it.

Create a new file in your Fargo folder called menubar.opml.

The top level headlines in this file are the names of the menus.

The second level heads are the names of scripts.

The text under the second level heads are the scripts themselves.

When you make a change to the script, Fargo automatically rebuilds the menus.

Here's an OPML file that contains a few very simple example scripts.

These are meant to get the ball rolling, more coming soon.

It's important that discussion about scripting in Fargo be limited to the smallpicture-script mail list. You can talk about your work there, even point to software that people can download. Please do not discuss scripting on other smallpicture mail lists. Thanks.