OUT OF DATE

This document has been replaced by

https://bespin.mozillalabs.com/docs/userguide/index.html

What is Bespin?

Bespin is an experiment in trying to create a web-based web-focused extensible code editor from Mozilla Labs. It's made by Dion Almaer and Ben Galbraith. This editor is based on new technologies regarding HTML 5.

How can I use Bespin

Requisites

To use Bespin, it's recommended that you use Firefox or Webkit Nightly Builds browsers.

Despite of this, Bespin should work in every modern browser that supports HTML 5 property "Canvas" (this excludes Internet Explorer), has a text rendering API, and support JavaScript.

Browsers that support Bespin:

• Firefox 3.x
• Webkit Nightly Builds (development version of Safari)
• Google Chromium (development version of Chrome)

Browsers NOT supported:

• Internet Explorer
• Google Chrome 1.x
• Opera 9.6x
• SeaMonkey
• Camino 1.6.6
• KHTML (Konqueror)

Making an account

To use Bespin you must create an account into Bespin Website and then log in. You'll be facing your Dashboard, welcome aboard the cloud!

Installing Bespin Locally

ATTENTION: This section has been made redundant with the introduction of the Developer Guide. Effort should be made to integrate any new details listed here into the Developer Guide, and then remove this section from the User Guide.

If you don't want to use Bespin 'in the cloud' you can install an instance of it in your computer. Or maybe you want to install it for a local network.

This section is still in development.

Python server

Firstly, you will need to grab the source. If you have mercurial installed then just do a

 hg clone http://hg.mozilla.org/labs/bespin/

Otherwise just download the tarball and extract it somewhere in you home directory.

Once your have everything on your hard disk open a terminal and go into the Bespin directory. Then change into the backend folder

 cd backend/python

and install all the requirements with

 python bootstrap.py 

This will take a few moments. After it is finished configure your installation and start the local server with the following three commands:

 source bin/activate
 paver create_db
 paver start

If you see something like Server starting on localhost:8080 in the terminal it means everything went well and you are good to go. Just point your browser to http://localhost:8080 and off you go.

Java server

This section is still in development.

Projects and File Explorer

The file explorer is the main view of your projects, files, opened sessions.

Projects

This section is still in development.

Importing

You can import projects to your Bespin account from the web. To import a project you can use the "project" meta command:

 project import <url with file> <project name>

Projects must be hosted on-line and compressed in ZIP or TAR.GZ formats.

Exporting

To export a project to your computer you can use the "project" meta command:

 project export <project name> [<archivetype>]

<archivetype> can be ZIP or TGZ. If archivetype is not passed it defaults to ZIP

Version Control

Bespin is able to use a version control system (VCS) to keep track of the history of your project's files. Using Bespin in conjunction with an external VCS is also a great way to get files in and out of a Bespin server.

The Basics

Bespin currently supports the Mercurial distributed VCS. You can add version control to a project using the command hg init. If you have never used a distributed VCS before, you might consider reading the Wikipedia article on the subject.

If you are starting to use Bespin with an existing project, you can clone a remote repository.

Securely accessing remote systems

In order to access remote VCSes, Bespin stores your login information for those remote systems in a private keychain. Your keychain file is encrypted with a password that is distinct from your login password and that you will need to type in whenever Bespin is accessing the remote system. Using a distributed VCS, you don't need to type this password in often.

Bespin supports username and password-based access to remote systems. It can also use SSH, and Bespin will generate a public/private keypair that you can use on the remote system. The private key is stored in your keychain. You can get your public key using the command:

 vcs getkey

If your remote repository is at a site like Bitbucket, it is easy to copy and paste this public key into the web interface of the site to get read and write access to your repositories from Bespin.

VCS Commands

For security reasons, Bespin supports only a subset of VCS operations. We plan to expand the number of commands and VCSes supported over time.

vcs clone

The clone command will clone (or checkout) a remote repository. This command provides an interface for entering the different parameters needed to get set up. Since clone provides access to remote resources, you will need to enter your keychain password.

The main fields are:

URL

URL of the repository (generally an http, https or ssh URL)

Project name

name of the project to create in Bespin. You can leave this blank, and Bespin will use what comes after the last / in the URL.

VCS Type

which version control system is used by this repository

VCS User

For distributed VCSes (Mercurial, Git), what username should appear in your commits for this project. You can also use the global Bespin setting "vcsuser" to set this value.

Authentication

None (used for read-only access to public repositories), Only for writing (if it's a public repository that you have write access to) and For reading and writing (if it's a private repository)

If you tell Bespin, via the Authentication options, that you have write access to the repository, additional fields will be displayed so that you can configure the write access.

Keychain password

password used to store your remote login credentials securely on the Bespin server

Push to URL

Sometimes you will use a different URL for pushing than pulling, perhaps using http to pull and ssh to push. This allows you to set the URL for pushing.

Authentication type

Bespin can use SSH for authentication or username/password. See the vcs getkey command for more information about Bespin's SSH authentication.

Username

You should always fill in the username that you will be using to log into the remote system

Password

If you are using username/password authentication rather than SSH, you will type in your password here. This password will be stored in your encrypted Bespin keychain.

hg init

If you don't need to maintain your files in a remote version control system, you can use the hg init command to initialize a Mercurial repository for the currently selected Bespin project.

vcs add

Adds files to the version control system. This concept is familiar in most VCSes. If you create a new file, it is not automatically placed under version control. vcs add on its own will add the current file to the VCS. vcs add -a will add all files. You can also list specific files within the currently selected Bespin project.

This does not access remote files, so you will not need your keychain password for this command.

vcs commit

Commits changes to the local repository within Bespin. You need to provide a commit message, which you should put in quotes on the command line.

This does not access remote files, so you will not need your keychain password for this command.

vcs diff

Shows you the differences between your current set of files and what's checked into the local repository in Bespin. Without any options, vcs diff will show a diff for the current file. vcs diff -a shows diffs for all of the files and you can also list specific filenames within the current project for which you'd like to see diffs.

This does not access remote files, so you will not need your keychain password for this command.

vcs getkey

As mentioned in the section Securely accessing remote systems, Bespin will generate an SSH public/private keypair for you. The vcs getkey command will display your public key so that you can copy and paste it into the remote host. After you do that, Bespin should be able to access the remote system.

When your key is first generated, you will need to enter your keychain password so that Bespin can securely store your private key in your keychain file. After this initial key generation step, you will not need to enter your keychain password for the vcs getkey command.

vcs push

Push committed revisions to the remote repository.

This will require your keychain password.

vcs remove

The files that you list for this command will be deleted and removed from version control.

This does not access remote files, so you will not need your keychain password for this command.

vcs resolved

If you pull changes from a remote repository and the resulting merge had conflicts, the vcs resolved command will allow you to tell the VCS that the conflicts have been resolved so that you can then commit the merge to the local repository.

Similar to other VCS commands, by default vcs resolved will mark the current file as resolved. vcs resolved -a will mark all files as resolved, and you can also list individual files in the current project.

This does not access remote files, so you will not need your keychain password for this command.

vcs revert

If you decide that you're not happy with changes you've made, you can revert your checked out copies of the files to the last revision in the local Bespin repository. vcs revert will revert the current file. vcs revert -a will revert all files, and you can also individually list files in the current project that you'd like to revert.

This does not access remote files, so you will not need your keychain password for this command.

vcs status

Display the status of your working copy (which files have been modified, added and removed, for example).

This does not access remote files, so you will not need your keychain password for this command.

vcs update

Update your working copy with changes from the remote repository, merging them in as necessary. For Mercurial, this is equivalent to "hg fetch" (which in turn is "hg pull" followed by either "hg update" or "hg merge" depending on whether there were any changes).

File View

The file view opens up when you click on any project. You can open a file by double clicking on it.

Open Sessions

This is where opened files appear. Every file shown here is still active, and you can access it by double clicking on it.

It's stablished on the Roadmap that every file will contain information about date, last modification, etc.

Editor

This is the main editor. You can edit your files here. It has syntax highlighting and the most commons tools for an editor:

• Cut/Copy/Paste
• Preview on Web (does not work on Webkit)
• Undo/Redo
• Save/Close
• Change font size
• Line numbering

Collaboration

Enhanced collaboration is one of the best reasons to do an IDE on the web. It’s possible in a traditional IDE or code editor, but there are lots of features of a web based editor that make it an obvious thing to do on the web.

Our new collaboration feature is still fairly new, and like the rest of Bespin, still fairly beta, but we’ve got it working in Firefox, Safari and Chrome right now.

Taking it for a spin

Want a go real quick? Here are the steps:

• Sign up or login to Bespin.
• Press CTRL+J/CMD+J to open the command line.
• Type follow joewalker to get someone to share files with. I've shared a project called pubproj globally.
• Type project list. You should see joewalker+pubproj in your list of projects.
• Type set collaborate on to turn on shared editing.
• Open a shared file by typing open /joewalker+pubproj/example.txt.

Or, in one graphic:

You should then be in a collaborative editing session with the rest of the Internet.

Click on the collaboration icon (2 people) in the top right hand corner show you who's editing with you.

How it Works

Collaboration adds 3 or 4 new commands:

• follow/unfollow: allow you to decide whose shared projects you want to see in your project navigator. As we evolve Bespin this will become a way to get all sorts of information about the people you are working with
• group: allows you to put the people you are interested in into groups to make it easy to manage sharing
• share: allows you to export your projects read-only or editable to individuals, groups, or to everyone

Expressing an interest in someone is as easy as follow username. You can then group these users together to make sharing easier. So for me to add kevin, Ben and Dion to a group, I would do group add mozlabs Kevin ben dion. Grouping people like this is totally optional, but it will make maintaining sharing rules a lot easier going forward, when you’re working on a number of projects.

Then if you want to share a project in read-only mode, to someone that is following you, you just type: share add projectname username. Replace username with groupname to share with one of your defined groups, or with everyone to just throw everything wide open. To allow editing you add “edit” to the end. So for ultimate wiki-like promiscuity: share add projectname everyone edit.

Projects shared to you by people you follow will now show up in your file-explorer, or you can edit them from the command line. Type open /owner+projectname/path/to/file.

Syntax Highlighting

Right now only CSS, JavaScript and HTML syntax highlighting are supported. This will be improved in the near future.

The syntax highlighter keys in on the file suffix (e.g. .html will cause HTML highlighting).

If you need to manually force a particular highlighter you can run the set command and pass in the particular language:

 set language html

If you want to add a new syntax highlighter you can do so by loading highlighter code and registering it:

 // load the file first (e.g. dojo.require("...."))
 bespin.syntax.simple.Resolver.register("Arduino", ['pde']);

Command Line

It shows at the bottom of the page. Here you can type some commands to do things that are not available trough the UI.

Commands

Global Commands

alias [command] 

Create an alias between a word and a command. For example:

 alias close closefile

This creates an alias that closes without saving the file you are currently working.

set [variable] [value] 

This sets values to variables in the configuration. If parameter is not passed a list with the available variables will be displayed. See settings. For example:

 set theme white

project

Various commands to manage projects

project [command] [parameters]

Command	Description	Parameters
create	create a new project	[projectname]
delete	delete a project	[projectname]
export	export the given project with an archivetype of zip or tgz	[project] [archivetype]
help	show subcommands for project command	[search]
import	If a URL is given, import that URL (e.g. project import http://foo.com/bar.zip MyProject). If only a project is given, then a file upload dialog will ask to upload a local file (e.g. project import MyProject).	[url] [project]
list	show projects
rename	rename a project	[currentProject] [newProject]
show	show the current project

Dashboard Specific Commands

history 

Show command history.

version 

Show Bespin version.

files [project] 

Show the files inside a given project.

Editor Specific Commands

Some commands still missing

clear 

Clear the content of the file.

closefile [file] 

If file parameter is passed, closes the specified file, if not, closes the current open file.

clipboard 

Saves the file contents into the clipboard.

dashboard 

Go back to Dashboard.

editconfig 

Open the editor's configuration file.

logout 

Logout the editor.

goto [line number] 

Moves cursor to the desired line number.

load [filename] 

Loads the file specified in [filename]

newfile [filename] 

Creates a new file with the name specified in [filename]

preview [filename] 

Preview the file in the web browser (does not work on Webkit)

project [name] 

Creates a project with the desired name

Keyboard Shortcuts

When the term "CMD" is used it refers to the Apple/Command key on Mac OS, and the Control key on Windows / Linux.

• CMD J: Takes you to the command line. Brings up the command popup if hidden. If the file browser is visible, it jumps to the command line history
• CMD I: Toggle Quickopen
• CMD O: Open File Browser
• LEFT_ARROW: Move Cursor Left
• RIGHT_ARROW: Move Cursor Right
• UP_ARROW: Move Cursor Up
• DOWN_ARROW: Move Cursor Down
• ALT LEFT_ARROW: Move Word Left
• ALT RIGHT_ARROW: Move Word Right
• HOME: Move to start of line
• CMD LEFT_ARROW: Move to start of line
• END: Move to end of line
• CMD RIGHT_ARROW: Move to end of line
• CTRL K: Kill entire line
• CMD L: Goto Line
• CTRL L: Move cursor to center of page
• BACKSPACE: Backspace
• CTRL BACKSPACE: Delete a word to the left
• DELETE: Delete
• CTRL DELETE: Delete a word to the right
• ENTER: Insert newline
• CMD ENTER: Insert newline at end of current line
• TAB: Indent / insert tab
• SHIFT TAB: Unindent
• ESCAPE: Clear fields and dialogs
• CMD A: Select All
• CMD F: Search in this file
• CMD G: Find Next
• CMD, SHIFT G: Find Previous
• CTRL M: Open Pie Menu
• CMD B: Preview in Browser
• CMD Z: Undo
• CMD+SHIFT Z, CMD Y: Redo
• CMD UP_ARROW: Move to top of file
• CMD DOWN_ARROW: Move to bottom of file
• CMD HOME: Move to top of file
• CMD END: Move to bottom of file
• PAGE_UP: Move a page up
• PAGE_DOWN: Move a page down
• CMD, SHIFT F: Execute command: 'format'
• CMD, SHIFT U: Execute command: 'uc'
• CMD, SHIFT L: Execute command: 'lc'
• ALT, SHIFT O: Execute command: 'outline'
• CMD S: Execute command: 'save'
• CTRL, SHIFT N: Execute command: 'newfile'
• SHIFT SPACE: Execute command: 'complete'

Emacs Style Shortcuts

There are some shortcuts implemented that are similar to Emacs. To turn these on you need to have a setting turned on:

 set keybindings emacs

which gives you:

• Control-B: Move cursor left
• Control-F: Move cursor right
• Control-P: Move cursor up
• Control-N: Move cursor down
• Control-A: Move cursor to line start
• Control-E: Move cursor to line end

User Configuration

Configuration File

You can access the configuration by typing in the command line:

 editconfig

This will open a new file called "config.js"

Settings

Parameters that you can change via set:

collaborate [on|off] 

Set collaboration mode. Default value: off.

syntax [auto|css|html|javascript] 

Set the highlighting language. Default value: auto.

autocomplete [on|off] 

Set command autocompletion. Default value: off

theme [name] 

Change theme. Currently there are only three suported themes. See Themes section for more info.

fontsize [number] 

Change default font size. Default value: 10

keybindings [emacs] 

Set emacs style keybindings.

Example:

 set autocomplete on

For a detailed list of settings see the main settings page

Themes

Bespin has the ability for you to change the look through theming.

Some themes are already packaged and available:

• Coffee (default)
• Pastel
• White
• Black

You can change between themes typing in the command line:

 set theme <theme-name>

To get tiger stripes, you can use the theme name + "zebra" (e.g.

 set theme blackzebra

Creating your own theme

Your BespinSettings project has a "themes" directory. In there you will see a sample theme for you to play with.

Copy that chap and create a new file as <yourtheme>.js. Tweak it, and then you will be able to

 set theme <yourtheme>

Frequently Asked Questions

You can see them here

Tips and Tricks

You can see them here

Known Issues

You can see them here

Bug Reporting

Have you find a bug? Tell us! Make a bug report