Bluefish: The Definitive Guide

Due to the small number of volunteer developers, the progression of Bluefish's development often fluctuates. For this reason, a long time may pass between each release. After all, the developers volunteer their time and effort because they actually want to use Bluefish :-)

Because of the long periods of time between releases, the current CVS or CVS snapshots may be what you want to use. Bugs will be fixed and new features introduced. We do try to keep the CVS version usable at any time (actually, the CVS version is used by most of the development team on a daily basis).

Bluefish has been reported to work on a number of systems. The Bluefish team mainly support these platforms:

Actually, any GNU/Linux distribution with GTK2 is fine and many distributions include Bluefish. In fact, Bluefish will likely work quite well on any POSIX compatible OS where GTK2 is available. Bluefish has been reported to work on the following:

This is the short installation description. Consult the other chapters if you are in doubt.

Bluefish is installed using the standard 'configure, make, make install' steps. Assuming you have downloaded a bluefish source package, for instance bluefish-ver.tar.gz (naturally, change the filename to what's appropriate), you complete the installation with the following steps:

The configure script is used to automatically find the appropriate settings for your system. Because of differences between systems, this compile-time configuration is necessary, and configure solves this challenge easily -- with an added bonus of telling whether you have everything you need to compile.

The configure-script can be, um, configured. This is something you most likely won't need to do, but it's easy to do if necessary. For a complete list of configure options, see Section 5, “Configure Options”

You can get the latest Bluefish version via CVS using the instructions in Section 3, “Latest Developmental Version” Enter the directory containing the bluefish source files:

$ cd bluefish-gtk

Next, you need to generate the configure script. That's accomplished by running

$ autoconf

Then, you run configure with whatever options you might want. This example will cause make install to install Bluefish with the specified directory as prefix (i.e. the binary is installed in /usr/local/bf-cvs/bin/bluefish). This is most likely not what you want -- just run configure without parameters instead.

$ ./configure --prefix=/usr/local/bf-cvs

If configure fails, it'll probably give a hint telling you what's missing or wrong. Assuming it completed successfully, your next step is to compile Bluefish. To do this, run

$ make

When make has completed, you can install Bluefish: (su to root first, unless you specified a user writable prefix to configure)

# make install

To update the sources at a later time, you run the command cvs -z3 -q update from within the bluefish-gtk2 directory.

Can't compile? Well, your first step is to make sure you have the necessary utilities and libraries. See Section 1, “Requirements”. Next, see if your system is mentioned in Section 3, “System Specific Installation Issues”. Below is list of well known problems that have been mentioned on the bluefish-dev list. If you're unable to find a solution (or if you think you have a solution others might want), feel free to contact us on the bluefish-dev list (See Section 2.4, “Contact Us”).

There are several useful command line options.

Many programs like browsers, email clients and file managers can be configured to open files in Bluefish. For example bluefish '%s' will open a file in the current window, bluefish -n '%s' will open a file in a new window, and bluefish -p '%s' will open a project file.

Apart from using File->New (Ctrl-N) or the New icon to create a new file, you may also use File->New Window (Shift-Ctrl-N).

Both methods create an untitled file of type text with the default character encoding defined in preferences.

Through File->Open... (Ctrl-O) one or more files can be opened. As for creating files, you may want to open the files in a new window. In this case, use File->New Window to first open the new window and then open the desired files as usual.

Figure 3.12. Bluefish Open File Dialog

Recently opened files can be opened by selecting them from the list within File->Open recent. The number of files in this menu can be set in the preferences under Files.

The file browser in the side panel can also be used to open files. It supports filtering files, by right clicking the contextual menu in the filebrowser.

Figure 3.13. Filtering Files with the Bluefish File Browser

The available filters may be modified in Preferences. For more information, see Section 5.4, “Modifying the files filters”.

If you right click a directory, you can make this directory the base directory for the filebrowser using the Set as basedir option. Then you can access it directly from the popup menu in the upper part of the file browser.

By default the filebrowser follows the document focus. If you change to a different document, the filebrowser will show the contents of the directory where this document is located. This behaviour can be changed on the bottom of the filebrowser.

Information about currently opened files can be seen if you move the mouse over the document tab (by default on the bottom of the screen). A so called tooltip will be shown with information about the full path, size, permissions, filetype and encoding of the file.

Figure 3.14. Info on open file with the Bluefish File Browser

An interesting feature of Bluefish is the ability to open files by selecting the text of a currently opened file. For example, if a filename is shown in say a terminal application, you can select the filename, and use File->Open from Selection to open that file. The file, if it exists, will be opened in another tab within Bluefish.

Finally, files can be opened via the command line by feeding filenames to Bluefish as arguments. This can even be done while Bluefish is running and the resulting file will then show up in its own tab.

Files can also be opened by clicking on the Open... icon in the main toolbar.

If a document is modified, the filename is shown in red in the document tabs, and also if you right click on the tabs, the full path is shown in red in the list that will pop up.

Figure 3.15. Tool Tip for Modified File

To save a document, you can use the File menu, the Save icon in the toolbar, or press the shortcut key combination Ctrl-S. By default a backup is made during save. The original file is copied to the same filename with a tilde ~ appended. This suffix and the backup behaviour can be changed in the preferences under Files.

Before saving the file, Bluefish will check if the original file was changed on disk, using the last modified time and the file size. On some filesystems the last modified time is sometimes not very precise (most notably on samba mounts). This makes Bluefish think the file is modified when it is not. This check can be changed in the preferences under Files.

You can also save a document under a different name, using the Save As... (Shift-Ctrl-S) menu entry, or the Save As... icon in the main toolbar. The original file will still exist.

Figure 3.16. Saving a File under a new Name

To save all modified files, you can use the File->Save All menu entry. This will save all documents that have been modified and bring you a save dialog if some files are new files.

It is also possible to move or rename a document, using the File->Rename... (F2) menu item, or right-clicking the file name in the side panel and choosing the Rename item.

Figure 3.17. Moving a file to another location

When you want to close a file quickly, click on the close icon in the document tab. You may also use the Close icon in the main toolbar, or the File->Close (Ctrl-W) menu item.

Figure 3.18. Closing a file with the document tab icon

If the file is unchanged, it is merely closed. If the file has been modified, you will be presented with a save dialog.

Figure 3.19. Closing a modified file

When dealing with multiple files, you may want to use the File->Close All (Shift-Ctrl-W) menu item.

For each modified file, you will be presented with a save dialog, where you can choose to save the changes, close the file (i.e. discarding any change), or cancel the operation.

Figure 3.20. Closing all files

Note that the File->Close Window menu item offers the same behaviour.

You can insert any file into the current document with the File->Insert... menu item. The file will be inserting at the cursor location.

For more in-depth information about dealing with files, see Section 2.9, “More on files”.

The file type of a file changes the behaviour of Bluefish. File types are recognised by their extension, or by the beginning of the content of the file. The current document type is shown in the far right of the status bar. How these extensions and patterns can be changed is described in Section 5, “Customising Bluefish”.

If the type of a file is not properly detected, you can change the type using the Document->Document Type menu.

The editing area is a standard GTK editing area. This means there are many keyboard shortcuts available to navigate through the text.

These shortcuts are also available when selecting text. Some examples:

Navigating through a large list of documents can be difficult. But if you right-click the document notebook tabs, you get a list of all opened documents.

Navigation between documents can also be done using the Go menu, or its shortcuts.

Figure 3.26. Bluefish Go Menu

The shortcuts are the following:

The Go->Goto Line (CtrlL) offers an interesting feature.

If there is some number in the document, you may select it, then click the From selection label in the Goto line dialog. Bluefish will fill in the Line number field with that number and go directly to it.

Figure 3.27. Using the Goto Line dialog

The same feature is available from the Go->Goto Selection.

Figure 3.28. Bluefish Project Menu

The projects are a sort of 'saved state' of Bluefish. All files open when the project is saved, are automatically opened the next time you open the project. Also the recently used files in that project are shown in the recent menu. Furthermore, a basedir can be set, so the file browser in the left panel will only show the files in the basedir and its subdirectories. If Bluefish is installed with gnome-vfs support the basedir might be remote, for example sftp://someserver/somedir or smb://user:password@server/someshare/.

If the webdir is entered in the project settings, Bluefish will launch the browser to the appropriate URL. If your basedir for example is /var/www/ and your webdir http://localhost/ Bluefish will use this information to launch the browser to the correct URL. This can be very convenient for testing server side scripting languages like PHP, JSP or other.

The template field can point to a template file. If the 'new file' button is clicked, the contents of this file will be automatically loaded into the edit window.

The projects will be expanded to have more Bluefish settings, so a project can be a bit of customized Bluefish setup. Currently the state of various tool bars and menu bars is saved in a project file.

The project file itself is simply a text file in the standard Bluefish format (same format as the config file). This format is 'key: value'.

In Bluefish you can add bookmarks to a line in the text, and you can later use the bookmark to quickly jump to this location. Bookmarks can be temporary or permanent, the default can be configured in the preferences.

Bookmarks can be added to the current cursor location by using the menu /Edit/Add bookmark, or by using the shortcut key combination control+d. You can also add bookmarks by right-clicking in the text, and selecting add bookmark.

Bookmarks can be temporary or permanent. Permanent bookmarks are stored, and temporary bookmarks are gone after Bluefish is closed. The default is set in the preferences under Editor. If you right click a bookmark and select Edit you can change this setting for a bookmark.

SCREENSHOT BY ????

A way to add many bookmarks at the same time is using the Find dialog. Check the 'Bookmark results' option, and all search results will be added to your bookmarks. For example this manual has sections, and each section is identified by a header like '<sect1 id="bluefish-ch-4-sect-6">'. A way to automatically get a bookmark to every section is to search for the following regular expression pattern: '<sect[0-9]+ id="[^"]+">' and bookmark all results.

Bookmarks can be found in the side panel, sorted by document and line number. If you right click a bookmark, you get a pop up menu with several options. Among the option is edit, which allows you to change a bookmark from temporary to permanent or the other way around, and you can name bookmarks.

The edit menu features several options for Find and Replace. The Find... (Ctrl+F) and Replace... (Ctrl+H) menu items will simply start the dialogs described elsewhere in this manual. The Find again (Ctrl+G) item will repeat the last used search. It will continue the search after the position where the previous search was stopped. If the end of file is reached, it will restart at the beginning or continue with the next file, depending on the search options used.

SCREENSHOT BY ????

The Find from selection item will search for the currently selected text. If you select for example the name of a function, in bluefish, or in any other program, and you choose find from selection Bluefish will start a new search for this selected string.

The shift-right and shift-left items in the menu, or the buttons in the tool bar, will indent or unindent the currently selected text. It will normally use tabs for indenting, or spaces if you have 'indent with spaces' selected in the preferences. The number of spaces used is the same as the 'tabsize' option in the preferences.

SCREENSHOT BY ????

By default, Bluefish will automatically produce closing tags for HTML and XML documents. For example, if you type <p> within an HTML document, bluefish will produce </p>. So, as soon as you finish typing a non-empty HTML tag, meaning the tag is supposed to have a closing tag, Bluefish will help you out and close the tag automatically. For empty tags, like <br>, Bluefish correctly does nothing. This feature can be turned off by unchecking the menu option Document > Auto Close HTML Tags.

Bluefish has two modes for tag closing, an XML mode and an HTML mode. In XML mode, Bluefish will add a closing tag to any tag that is not closed itself with />. In HTML mode, Bluefish excludes all known tags that do not need a closing tag, such as <br> and <img>.

Bluefish will choose the mode based on the filetype of the document. In the filetype preferences the default mode for each filetype can be set.

Figure 3.29. Bluefish Spell Checker

Bluefish uses aspell for spell checking. If the aspell libraries are not installed on your system, then the spell checking feature will not be available. To launch the spell checker, select Document > Check Spelling...

The spell checker will launch in a separate window, which you can keep open as you edit files. You have the option to check a whole document or just a selection. Click on Spell Check to start spell checking the current document. As you run across misspelled words you want included in the dictionary, click on the Add button in the spell checker window. This will add words to a personal dictionary.

Key words for different languages can be ignored using filters. Currently, the only filter is for HTML. If you want to help write more filters, join the mailing list.

The function reference browser is a place where reference information about a certain language can be found. Currently Bluefish comes with a PHP reference, a CSS 2.0 reference, an HTML reference and a Python reference. The functions are grouped depending on the language, by type, module, object, etc.

The function reference browser can show a info window on the bottom. Check the 'Show info window' checkbox. In this window some information about the currently selected item can be shown. What exactly is shown can be chosen in the right-click context menu.

SCREENSHOT BY ????

Every item in the function reference can simply insert text, show an info window, or show a dialog that can be used to insert text. In the right-click context menu each of these functions are accessible. One of these functions can be bound to a left-double-click action. This is also configurable from the context menu.

HTML is obviously the most supported language in Bluefish. There is a special HTML tool bar with many dialogs, and several menu sections to work with tags. You can also right-click a tag and bring up the dialog from there. The preferences have several settings on HTML style under HTML.

In the reference tree on the left panel there is also HTML reference available.

There are several special search and replace actions in the menu Edit-Replace special. These can be used to convert special characters (like < and &), or ISO characters to their HTML entities.

Bluefish can automatically generate thumbnails for images. ..... TO BE WRITTEN BY ???

SCREENSHOT BY ????

The quick bar is a user defined tool bar. All HTML tool bar buttons can be added to the quick bar by simply right-clicking them and selecting "Add to quick bar". If you want to remove items from the Quick bar, right-click them and select "Remove from Quick bar"

SCREENSHOT BY ????

The custom menu allows you to add "often used" strings or search and replace patterns to a menu. Upon install Bluefish will create some default entries, these will give you an idea what can be done with the custom menu.

The location for entries in the custom menu is defined by their menu path. A menu path looks like /Main menu/submenu/item or /Main menu/item.

There are two types of items in the custom menu. First is the Custom dialog, which will insert a string, optionally based on values asked in a dialog. Second is the Custom Find and Replace, which will run a replace, also optionally based on values asked in a dialog.

The most simple custom dialog item has a menupath, for example /MySite/author, and a Formatstring before, for example 'written by Olivier'. If you add this item, you can add this string by selecting the menu item.

SCREENSHOT BY ????

In another example, you have a string you often need to set before and after some block of text. For example <div class="MyClass"></div>. Now you choose menupath /MySite/div with class and you choose <div class="MyClass"> as formatstring before, and you choose </div> as formatstring after. Click add, and the item is in the menu. If you now select some text, and activate this menu item, you will see that the first bit of text is added before the selection, and the second bit is added after the selection.

Suppose you want to improve this last example. You have both MyClass1 and MyClass2. Now use 'Number of variables' 1 in the custom menu editor. As you see a new entry appears where you can enter the name for variable %0. As name we enter 'MyClass number', and now we change the formatstring before to <div class="MyClass%0">. If you now activate this menu, it will ask you for a value for 'MyClass number', and then insert the strings, using the value you provided.

SCREENSHOT BY ????

Find and replace items are no different. The dialog has some more options, each of these options correspond to the regular replace dialog. Again you can use variables like %0, %1 etc. to make a certain menu item more flexible.

SCREENSHOT BY ????

You can integrate external commands such as browsers, or text filters. If you want to use for example a sed command as a filter, you can add it like this to the external commands and filters (in the preferences dialog): sed -e 'some sed command' > '%f' < '%s'

Figure 3.30. Bluefish External Menu

To add items to the external menu:

I WILL ADD AN EXAMPLE HERE LATER

Items within External > Outputbox allow for programs to give feedback by opening an output box within Bluefish's main window. To create an Outputbox menu item:

Many menu entries are accessible via key combination; also called a shortcut. For example, pressing the Ctrl+S keys saves the current file to disk. If available, shortcut key combinations are shown on the right of the menu entry.

What many people do not know is that they can be changed. Move the mouse over a menu entry, and press the key combination you would like to use. Immediately this combination will show up on the right of the menu entry. An entry can also be removed, press the backspace key when you move the mouse over a menu entry to remove the shortcut.

To save the shortcut key combinations for later Bluefish sessions you can store them. In the Edit menu choose Save shortcut keys. This will store the settings in file ~/.bluefish/menudump_2. If you want to restore the default combinations simply remove this file and restart Bluefish.

The font of the editor can be set in the preferences under Editor.

A frequently asked question is how to change the background color of the editor in Bluefish. Bluefish uses the default editor background color as set in your GTK theme. If you want to override the color of the theme, edit ~/.gtkrc-2.0 and add this section:

style "EditorStyle" {
        base[NORMAL]="#eeeeee"
}
class "GtkTextView" style "EditorStyle"

Obviously, #eeeeee should be your preferred background color.

Here you can define all file types that should be recognised by Bluefish. The defaults for these file types are retrieved from a file called file types.default in ${prefix}/share/bluefish/.

The file types consist first of a name (this name is also used in the file filters, and in the highlighting patterns). Second is a list of extensions, separated by a colon (:). Third are the highlighting update characters. Upon a key press of one of these characters, the highlighting engine will refresh the highlighting around the cursor. If this field is empty, any character will force the highlighting engine to refresh. Special characters like the tab and the newline can be entered as \t and \n, the backslash itself is entered as \\. Fifth is the icon location for this file type. Sixth is whether this file type is editable by Bluefish (whether or not Bluefish should try to open it after a double click). Seventh is a regular expression that can be used to detect the file type if a file without extension is loaded. Eight is the auto-tag-closing mode. A value of 0 means that Bluefish should not close XML/HTML tags, a value of 1 means it should close the tags XML style (<br />), a value of 2 means HTML style.

TO BE WRITTEN

The highlight patterns are build from Perl compatible regular expressions. A pattern has options for coloring and style of the text it matches. Within a match other patterns can be used to color parts of that match. There are three types of patterns:

One specific pattern can also be used within several other parent patterns. The parent-match option is a regular expression that defines all parents for a certain pattern. If empty it will default to ^top$, so basically it will be on the top level.

So how does it work? Lets take a look at a little example text, a piece of PHP code within some HTML code:

<p align="center">
<?php
// this is a comment ?>
?>

The first thing the highlighting engine does is finding the pattern that has the lowest match. Using the default patterns for PHP, the pattern named html has a match at position 0:

<p align="center">

So now the highlighting engine searches for the lowest match in all subpatterns of html, in the region matched by the type 2 html pattern. Again, the lowest match will count. The pattern named html-tag has a match at position 1. This pattern is a type 3 pattern, so it matches a subpattern of the parent:

p

the match from subpattern html-tag ends at position 2 and it does not have any child patterns, so the highlighting engine continues at position 2 with all subpatterns from html. A type 2 pattern named html-attrib has the lowest match:

align="center"

This pattern does have a child pattern, again a type 3 pattern called html-attrib-sub2 matching:

"center"

The pattern html-attrib-sub2 does not have any child patterns, and subpatterns of html-attrib do not have any more matches, and also html subpatterns do not have any more matches. So we are back on the main level, the remaining code to highlight is:

<?php
// this is a comment ?>
?>

Now a pattern named php has the lowest match. This is a type 0 pattern, so the highlight engine continues with all the remaining code, but it will not only search for the lowest match of the child patterns of php, but it will also use for the end pattern of php. The lowest match in this example is a pattern named php-comment-C++ As you can see the ?> within the comment does not end the php pattern, because it lies within a subpattern of php:

// this is a comment ?>

The pattern php-comment-C++ does not have any child patterns, so the remaining code for the php subpatterns is:

?>

It is very obvious now, the lowest match will be the end pattern of the php pattern, so we're back on the main level, and we have matched all of the code!

Figure 3.31. Syntax highlighting example

The config file for highlighting is a colon separated array with the following content:

mode:
patternname:
case_sensitive(0-on/1-off):
start reg-ex:
end reg-ex:
start & end pattern(1), only start(2), subpattern(3):
parent-match:
foreground-color:
background-color:
don't change weight(0), non-bold(1), bold(2):
don't change style(0), non-italic(1), italic(2): 

The same options are found in the syntax highlighting preferences.

SCREENSHOT BY ????