Labs/Bespin/UserGuide

Disclaimer

Please consider that this documentation is still under hard development, and may change. This documentation is for Bespin version 0.1.5 "Nonchalant Nimbus+" but it will be updated as new releases come out.

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.

Dashboard

The Dashboard is the main view of your projects, files, opened sessions, and statistics (in a future version).

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 do:

 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 do:

 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 [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 [[1]], 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 check out) 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.

Additionally, you need to tell where Bespin where to find the remote repository.

(more to come)

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

Not included in this version. It will be available in version 0.3 (See Roadmap)

Syntax Highlighting

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

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

projects

Show a list with your projects.

help

Displays a list with the available commands.

createproject [projectname]

Create a new project with the desired name.

export [projectname] [archivetype]

See Projects

import [url] [projectname]

See Projects

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

Note: The keyboard shortcuts are the same for Windows, GNU/Linux and Mac OS, there is no Cmd equivalent.

Control-J: Takes you to the command line.

Emacs Style Shortcuts

There are some shortcuts implemented that are similar to Emacs. They are:

• 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 to it 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

Themes

Only three themes are currently supported:

• Coffee (default)
• White
• Black

You can change between themes typing in the command line:

 set theme <theme-name>

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