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 needed to compile.

The configure-script can be, um, configured. This is something you most likely will not need to do, but it is easy to do if necessary. For a complete list of configure options, see the section called “Configure Options”

You can get the latest Bluefish version via CVS using the instructions in the section called “Latest Developmental Version”. Next, install it with the following steps:

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

If compilation fails, first make sure you have the necessary utilities and libraries. See the section called “Requirements”.

Next, see if your system is mentioned in the section called “System Specific Installation Issues”.

Below is a 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 the section called “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 the Files tab in the Edit->Preferences menu option.

Through File->Open... (Ctrl-O), one or more files can be opened. When creating new 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.13. 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 file browser.

Figure 3.14. Filtering Files with the Bluefish File Browser

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

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

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

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 tool tip will be shown with information about the full path, size, permissions, file type and encoding of the file.

Figure 3.15. 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 tool bar.

Be aware that if the file is huge it may take a very long time to get the rendering if syntax highlighting is enabled. The GTK editing widget used in Bluefish, furthermore, is not very good at handling files with very long lines, and that could also slow down Bluefish considerably.

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.16. Tool Tip for Modified File

To save a document, you can use the File menu, the Save icon in the tool bar, 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 tool bar. The original file will still exist.

Figure 3.17. 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 present you with 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.18. 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 tool bar, or the File->Close (Ctrl-W) menu item.

Figure 3.19. 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.20. 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.21. 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 inserted at the cursor location.

For more in-depth information about dealing with files, see the section called “More on files”.

Bluefish offers a wide range of find and replace methods in the Edit menu, also available through the contextual menu within a document. Here we will explore the most basic ones. For advanced find and replace methods, see the section called “Find and Replace”.

Searching for a word within a whole document

Choose the Edit->Find... (Ctrl-F) menu item. A Find dialog will be displayed. Enter the word to search for in the Search for: field. Then click OK.

Figure 3.24. Finding a word in a document, from start to end

If the word does not exist in the document, a small window pops up.

Figure 3.25. Unsuccessful search window

If the search is successful, the document window scrolls up to the first occurrence of the string in the document and highlights it.

Below is an example of a search applied to a shell script.

Figure 3.26. Highlighted search result in the document window

To find a subsequent occurrence of the string, use the Edit->Find again (Ctrl-G) menu item. If no further occurrence is found, a dialog will be displayed notifying you that no match was found.

Setting limits to the search scope

You may want to search for a string from the cursor location till the end of the document. Here is an example to search all name == occurrences within a python script from a given location.

Procedure 3.2. Searching from selection

1. Put the cursor where you want to start the search from in the document window

   Figure 3.27. Setting the cursor location

   

2. Open the Find... dialog

3. Enter your search string in the Search for: field

4. Choose Current position till end from the Starts at: pop up menu

   Figure 3.28. Choosing a limited search method

   

5. Click OK.

Here is the result:

Figure 3.29. Limited search result

Notice that the search does not take into account the occurrence of the same string at line 50, since it is outside the search scope.

You can also limit the search scope to a selection range. In that case, highlight the selection before the search, and choose Beginning of selection till end of selection from the Starts at: pop up menu in the Find dialog.

Case sensitive search

By default, the search process is case insensitive. If you want to make it case sensitive, just check the Match case box in the Find dialog.

Figure 3.30. Making the search case sensitive

Here is the result applied to a ruby script:

Figure 3.31. Case sensitive search result

Notice again that the result does not catch the XML string at line 45, since the search string was xml and case sensitive search was requested.

Overlapping searches

It may occur that the document contains some kind of palindrome you want to search for. The "normal" find process does not retrieve all occurrences of that kind of string.

In this case, you have to check the Overlap searches box in the Find dialog to retrieve all occurences of the string.

Figure 3.32. Finding overlapping strings

Applied to a shell script, the second search (with Ctrl-F, then Ctrl-G) will give the following result:

Figure 3.33. An overlapping string retrieved with the Find dialog

Retrieving previous search strings

Notice that the pop up menu to the right of the Search for field in the Find dialog allows you to retrieve previous search strings. They are listed in reverse order by search history, providing quicker access to the most recent searches.

Figure 3.34. Retrieving recent searches

Replacing features

The Edit->Replace... (Ctrl-H) menu item works the same way and has all the features, the Edit->Find... (Ctrl-F) menu item offers.

The Replace dialog is also accessible through the contextual menu within a document.

For the features common to the Find dialog, see the section called “Searching for a word within a whole document”.

Here we will explain the features unique to the Replace dialog.

Figure 3.35. The Replace dialog

Changing letter case when replacing

If you want to change letter case when replacing, use the Replace type pop up menu.

The default choice is Normal, that is the case is not changed.

With the Uppercase replace type, the search string will be replaced with its uppercase translation.

Likewise, with the Lowercase replace type, the search string will be replaced with its lowercase translation.

Figure 3.36. Changing letter case when replacing

Notice that in this case, the Replace with field is deactivated, thus not taken into account even if you have entered some string in it.

Choosing strings to replace

It may occur that you do not want to replace all search strings retrieved by the search process, but only some of them. In this case, check the Prompt before replace box. A Confirm replace dialog will appear for each retrieved string where you can choose to Skip this string, i.e. leave it as it is, Replace it, Replace all strings within the search scope, or Close the dialog, i.e. cancel the process.

Figure 3.37. The Replace confirm dialog

If you want to replace only the first occurrence of a search string, check the Replace once box instead.

Different file types can change the behaviour of Bluefish. File types are recognized by their extension, or by the beginning of the file's contents. The current document type is shown in the far right of the status bar. If the type of a file is not properly detected, you can change the type using the Document->Document Type menu. See the section called “Customising Bluefish” to change these extensions.

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.41. Bluefish Go Menu

The shortcuts are the following:

The Go->Goto Line (Ctrl-L) 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. The same feature is available from the Go->Goto Selection.

Figure 3.42. Using the Goto Line dialog

The projects are a sort of saved state of Bluefish. Thus, they are a very convenient way to work with files scattered all over your disks or to pick up only the files you are interested in within a huge tree. Projects features are accessible through the Project menu.

Figure 3.43. The Bluefish Project Menu

To open a project, you have the choice between Project->Open Project... or Project->Open recent. When you choose the former, a Selecting a Bluefish Project dialog is presented to you.

Figure 3.47. Selecting a Bluefish Project

To save the project under its current name/location, use Project->Save or Project->Save & close; to save it under a new name/location, use Project->Save as.... If any file in the project has changed, a dialog will allow you to save the file, discard the changes, or cancel. All files open when the project is saved are automatically opened the next time you open the project.

Figure 3.48. Opening a Bluefish Project

Notice that the side panel only shows the tree related to the project.

Also, the recently used files in that project are shown in the File->Open recent menu item.

A project also saves some basic Bluefish settings, giving the project its own customized Bluefish setup. Currently, the word wrap preference and the state of various tool and menu bars are 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. Here is an example:

name: BluefishDoc
basedir: ~/bluefishcvs/bluefish-gtk2/doc/
webdir: http://micmacfr.homeunix.org/bluefish/doc
template: 
view_main_toolbar: 1
view_left_panel: 1
view_custom_menu: 1
view_html_toolbar: 1
word_wrap: 1

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, or even to open the document referred to by the bookmark at that line.

Bookmarks can be added to the current cursor location by using the Edit->Add Bookmark (Ctrl-D) menu item; or by right-clicking in the text, and selecting Add bookmark. You can delete a bookmark using the Delete bookmark item in the document contextual menu.

Each bookmark in a given document is marked by a blue background in the line number margin.

Figure 3.49. How bookmarks are marked

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.

Bookmarks can be found in the third tab of the side panel, sorted by document and line number.

Figure 3.50. Bookmarks in the side panel

If you right click a bookmark in the bookmark tab of the side panel, you get a pop up menu with several options.

Figure 3.51. Contextual menu on bookmark in the side panel

The Goto bookmark item allows you to go to the bookmark location in the document, opening it if needed.

The Edit item allows you to change a bookmark from temporary to permanent or the other way around, to name it, and to give it a short description.

Figure 3.52. Editing a bookmark

Note that after naming a bookmark, the default name - first characters of the bookmarked line - is displayed after the new name.

Figure 3.53. A named bookmark

Via this contextual menu, you may also delete a bookmark, delete all bookmarks in the active document, or delete all bookmarks stored in the bookmark tab of the side panel. The latter ones are also available when you right click the name of a document in this tab.

Figure 3.54. The contextual menu on a document in the bookmark tab

Generating several bookmarks at once

To add many bookmarks at once, use the Edit->Find (Ctrl-F) dialog. Check the Bookmark result option, and all search results will be added to your bookmarks.

For example, the XML files for this manual have sections, each identified by a header like <sect1 id="nameofthesection">. A way to automatically get a bookmark to every section is to search for the following posix regular expression pattern: <sect[0-9]+ id="[^"]+"> and bookmark all results.

Figure 3.55. Bookmarking with Posix regular expression

Here is the result:

Figure 3.56. Bookmarks with Posix regular expression

Here are two examples which bookmarks all functions in Objective-C and PHP files with POSIX or PERL regular expressions:

Figure 3.57. Bookmarking Objective C functions via the Find menu

Figure 3.58. Bookmarking PHP functions via the Find menu

Check the section called “Find and Replace Using Regular Expressions” for more information on finding and replacing with regular expression in Bluefish.

The Edit menu features several options for Find and Replace. The Edit->Find (Ctrl-F) and Edit->Replace... (Ctrl-H) menu items will simply start their corresponding dialogs described in the section called “Basic Find and Replace”.

Find Again

The Edit->Find again (Ctrl-G) menu 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 signaled it if the search operates on a unique file, nevertheless you can continue the search from the top of file with Ctrl-G after dismissing the Search: no match found dialog. If the search operates on multiple files, it will continue with the next file.

Here you can see how the Find again process operates on two successive searches for the word "url" in an xml file:

Figure 3.59. Nth occurrence with Find Again

Figure 3.60. Nth+1 occurrence with Find Again

Find from Selection

The Edit->Find from selection menu 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.

Here we have selected a function in a C file:

Figure 3.61. Selecting a string for subsequent search

Clicking on Edit->Find from selection gives the following result:

Figure 3.62. Finding a string from selection

Next occurrences of the string can be found with Ctrl-G as usual.

Find and Replace Using Regular Expressions

With find and replace you can do incredibly powerful searches. We have already seen some of them in the section called “Generating several bookmarks at once”, which deserve some explanation here.

Example 3.1. Retrieving all sections in an xml book

The regular POSIX expression <sect[0-9]+ id="[^"]+"> can be split into:

• <sect: a string beginning by <sect

• [0-9]+ : followed by one or more (the + part) characters in the range of 0 to 9 (the [0-9] part), i.e. digits, followed by a space

• id=": followed by the string id, followed by an equal sign, followed by a double-quote

• [^"]+: followed by one or more (the + part) not double-quote characters (the [^"] part - ^ is a not )

• ">: followed by a double-quote, and ending with a > sign

Therefore, it matches any string of type <sectn id="nameofthesection">, where n is a positive integer.

Example 3.2. Retrieving all functions in an Objective C file

In a simplified example, an objective C function may have two forms:

1. - (IBAction)nameofthefunction:(id)parameter

2. - (void) nameofthefunction

We will try to make a pattern from those forms:

• Hyphens and parentheses have special meanings in regular expressions, hence we need to escape them, i.e. to put before each of them a backslash, so that they will be interpreted as normal characters.

  Thus, - ( is matched by: \- \(

• IBAction or void are a non empty sequence of alphabetical characters. We have already seen something similar in the previous example.

  They are matched by: [a-z]+, that is one or more characters in the range of a to z.

• Another parenthesis matched by: \).

• A space or no space at all, it is matched by: *, that is a space followed by an asterisk, which means 0 or more times the preceding character.

• A non empty sequence of characters, matched by [a-z]+ as already seen.

• A colon or no colon at all, which is matched by: [:]*.

Thus the whole POSIX regular expression is: \- \([a-z]+\) *[a-z]+[:]*. In the example, we have grouped the parts with parentheses, you may prefer this simplified form, though it is not recommended.

Example 3.3. Retrieving all functions in a PHP file

A php function has the form function nameofthefunction(listofparameters), where the list of parameters can be empty. To match it with a PERL regular expression, you have to know that \s matches any white space and \w matches any alphanumerical character as well as white spaces.

Thus, the matching regular expression is: function\s+\w+.

Now, if you want to capture also the function's parameters, you have to add:

• An opening parenthesis: \(. Remember parentheses should be escaped with a backslash.

• Zero or more characters, none of them being a closing parenthesis: [^\)]*

• A closing parenthesis: \)

The PERL regular expression becomes: function\s+\w+\([^\)]*\).

Here is a new example which transforms a table into a definition list inside an html file.

Example 3.4. Transforming a table into a definition list

Say you have the following table:

Figure 3.63. The table before transformation

You want to transform it in the following definition list:

Figure 3.64. The table after transformation

For the rendering, you will use the following css style sheet:

.st2 {
    font-weight: 900;
    color: #e38922;
    margin-left: 30px;
}
dl {
    font-weight: 900;
    margin-left: 55px;
}
dt {
    margin-top: 6px;
}
.dd1 {
    font-style: normal;
    font-weight: 400;
}

The table's source code is the following:

<table border="1">
<tr>
<th>Software</th>
<th>Use</th>
<th>Requirements</th>
<th>Author</th>
<th>Date</th>
<th>Download</th>
</tr>
<tr>
<td>BackupSeek 1.8</td>
<td>To catalog your backup from all media. Prints labels too.</td>
<td>PPC</td>
<td>Ken Ng</td>
<td>17 November 1999</td>
<td>English version (452 Ko)</td>
</tr>
<tr>
<td>Biblioteca v. 1.0</td>
...
</tr>
</table>

The definition list's source code will be the following:

<p class="st2">BackupSeek 1.8</p>
<dl>
<dt>Use:</dt><dd><span class="dd1">To catalog your backup from all media. \
Prints labels too.</span></dd>
<dt>System requirements:</dt><dd><span class="dd1">PPC</span></dd>
<dt>Author:</dt><dd><span class="dd1">Ken Ng</span></dd>
<dt>Date:</dt><dd><span class="dd1">17 November 1999</span></dd>
<dt>Download:</dt><dd><span class="dd1">English version (452 Ko)</span></dd>
</dl>
<p class="st2">Biblioteca v. 1.0</p>
...
</dl>

Comparing both chunks of code, we see that the variable sequence of characters to capture is the one between one <td> tag and its closing </td> tag. That sequence can be interpreted as one or more characters which are not a <. We have already seen that. This is expressed as: [^<]+

To be able to retrieve it later, we need to embed it into parentheses. Thus, the string becomes: ([^<]+)

Next, this sequence is embedded into <td> and </td>, which is expressed simply concatenating the strings: <td>([^<]+)</td>

We should also add the end of line character, which is expressed as: \n. The regular expression now describes a whole line: <td>([^<]+)</td>\n

As we cannot use variables to retrieve the headers of the table, we will merely repeat that string five times, so that the regular expression matches exactly the six lines of importance to us.

Note

Do not type it six times in the search field. Select the string, use the shortcuts Ctrl-C to copy it, move to the end of the string with the right arrow, and use Ctrl-V five times to paste it at the end of the string.

The regular expression becomes (backslashes are inserted at end of line just for the purpose of not to have too long lines):

<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n

Those lines are at their turn embedded into <tr> and </tr> tags each of them on their own line, which can be expressed as: <tr>\n for the first one, and </tr>\n for the second one. We add those strings respectively at the beginning and at the end of our regular expression, which becomes:

<tr>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
<td>([^<]+)</td>\n \
</tr>\n

Now that we have described the search pattern, we will build the replace pattern. Each expression embedded into parentheses in the search string can be retrieved with \x, where x is an integer starting at 0 for the first expression, 1 for the second, etc. All others parts in the final string are fixed strings which we will express as they are.

The first line becomes (note the \n at the end to match the end of line character):

<p class="st2">\0</p>\n

The second line (again, note the \n to match the end of line characters):

<dl>\n<dt>Use:</dt><dd><span class="dd1">\1</dd>\n

And finally the whole replace pattern is:

<p class="st2">\0</p>\n \
<dl>\n<dt>Use:</dt><dd><span class="dd1">\1</dd>\n \
<dt>System requirements:</dt><dd><span class="dd1">\2</span></dd>\n \
<dt>Author:</dt><dd><span class="dd1">\3</span></dd>\n \
<dt>Date:</dt><dd><span class="dd1">\4</dd>\n \
<dt>Download:</dt><dd><span class="dd1">\5</span></dd>\n</dl>\n

After entering both patterns, choose PERL type in the Regular expression drop down list, check the Patterns contain backslash escape sequences (\n, \t) and click OK.

After replacement occurred, you have to remove the table headers and the last </table> tag and to insert the link to the style sheet.

Note that if some lines contain a < sign, the table row will not be translated, but others will.

In the Find and Replace dialogs it is not possible to insert the keys Enter or Tab. A simple way to do it is to copy two lines in a row from the current document into the Find or Replace dialog, this way you retrieve the end of line character. The same applies for Tab. A more elaborated way to do it is to use escaped characters to represent these characters. A new line character, produced by pressing the Enter key, is represented as \n. Use \t for a tab. To get an actual backslash, just escape the backslash, \\. There are many other escape characters used in regular expressions.

Note

To enable the escaped characters in your searches check the Patterns contain backslash sequences (\n, \t) option.

If you have any search and replace patterns you use often, you can also add them to the Custom Menu. Check the section called “Custom menu” for more information.

For more information about regular expressions you might want to read man 1 perlre, man 3 pcrepattern, man 3 regex or man 7 regex, or read any of the great Internet sites about regular expressions. As you become more familiar with regular expressions, you will realize that they make Bluefish a very powerful editor.

To indent large sections of text, simply highlight the section and choose Edit->Shift Right (Ctrl-.). To remove an indentation, choose Edit->Shift Left (Ctrl-,). There are corresponding buttons in the tool bar for these menu options (see later in this text).

By default, Bluefish will use tabs for indenting, but can be configured to use spaces if you have Use spaces to indent, not tabs selected in the Editor preferences panel. The number of spaces used is the same as the Tab width option in the same preferences panel.

Here's an extract of Dante's work indented with the Shift Right button in the main tool bar:

Figure 3.65. Indenting part of a text

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. This feature can be turned off by unchecking the Document->Auto Close HTML Tags (Ctrl-T) menu option.

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 file type of the document. In the filetype preferences panel, the default mode for each file type can be set. See the section called “Modifying file types” for more info.

Figure 3.66. 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. At the aspell web site you can also download dictionaries for many different languages.

To launch the spell checker, select Document->Check Spelling... or click on the ABC button on the main tool bar. 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, to use a personal or a session dictionary, and to choose the language depending on the installed dictionaries.

Click on Spell Check to start spell checking the current document.

You may want to set a default dictionary by first choosing the language in the Language pop up menu, then clicking on Set default.

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 contains reference information for different programming and markup languages. 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 will display an info window on the bottom by checking the Show info window check box. In this window, information about the currently selected item is shown. The type of information shown can be configured in the right-click context menu (see Info Type later in this text).

In the reference browser's contextual menu, you can simply insert the text for the selected item by choosing Insert. Or, you can get a little help using Dialog, which launches a dialog window containing fields for the currently selected item's attributes or parameters. For a summary of an item's usage, choose Info. The contextual menu is also accessible on a group of functions and at the top level of a reference.

Figure 3.67. The reference browser contextual menu

The Options menu accessible via the contextual menu offers three actions:

Figure 3.68. The reference browser options menu

HTML is obviously the most supported language in Bluefish. There is a special HTML tool bar with many dialogs, and two menus to work with tags:

The preferences have several settings on HTML style under HTML.

The HTML tool bar has two types of buttons. You can recognise each type by the tool tip if you move the mouse over the button:

If you want to add an HTML tag around some block of text, select the block of text, use the HTML tool bar or the Tags or Dialogs menu to insert the tag. The opening tag will be inserted before the selected block, the closing tag after the selected block.

An existing tag can be edited by right-clicking the tag, and select Edit tag in the context menu. You can also place the cursor in the tag and use Dialogs->Edit tag under cursor... (F3). Not all tags, however, have a dialog, so this is not always possible. Colors in the style #RRGGBB can also be edited from the right-click context menu.

In the reference browser on the left panel there is an HTML reference available. All possible attributes and valid values can be found in this reference. See the section called “Function reference” for more info.

Special find an replace features

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, as well as to change the letters case.

Figure 3.75. The Replace special menu

In all cases, when you want to replace some part of the text, you should first select the part to replace, then use the appropriated menu item.

Thumbnail generation

Bluefish can automatically generate thumbnails for images. A thumbnail is a small image, with a link to the larger image. Bluefish will create the small image based on your settings, and insert a <img> tag in the file, and a <a> tag linking the original. The thumbnails are created in the same directory as the original sources.

The formats used for thumbnails may be png or jpg format. By default, the format used for thumbnails is png. You can change it in the Images panel of Preferences. For jpg images, the thumbnail extension is jpeg.

There are actually two thumbnail dialogs in Bluefish:

• an Insert thumbnail dialog,accessible from the Dialogs->General->Insert Thumbnail... (Shift-Alt-N) or from the Standard bar of the HTML toolbar.

  Figure 3.76. The Insert thumbnail icon

  

• a Multi thumbnail dialog, only accessible from the Standard bar of the HTML toolbar.

  Figure 3.77. The Multi thumbnail icon

  

The Insert thumbnail dialog is very straightforward. You select the image file, provide some <img> tag attributes, choose the scaling, and press OK. The scaling factor is chosen by moving the slider directly under the image. The resulting image is previewed in the preview frame. Bluefish will create the thumbnail with extension _thumbnail.png or _thumbnail.jpeg (depending of the settings for images in the preferences).

Figure 3.78. The Insert thumbnail dialog

Tip

If the source image is not accessible, change webimage to image in the Select File window loaded after clicking on browse for choosing an image. This way you can choose whichever format you want for the original sources. Another way to do it is to change the definition of webimage (see the section called “Modifying file types”).

If that does not solve the problem, it is likely that the type of images you want to load is not defined yet in preferences. In this case, change the definition of image as explained in the section called “Modifying file types”.

As last resource, if you don't want to change the generic file types, you may choose All files in the pop up menu at the bottom of the Select File window.

The code generated for a png image and a png thumbnail looks like this:

<a href="/Users/michga/Desktop/343-4351_IMG_2.png">
<img src="/Users/michga/Desktop/343-4351_IMG_2_thumbnail.png" 
width="89" height="134" border="0" name="Gamboling" 
alt="Gamboling in the meadow" align="middle"></a>

and for a jpg image and jpg thumbnail:

<a href="/Users/michga/Desktop/343-4351_IMG_2.JPG">
<img src="/Users/michga/Desktop/343-4351_IMG_2_thumbnail.jpeg" 
width="89" height="134" border="0" name="Gamboling" 
alt="Gamboling in the meadow" align="middle"></a>

Note

You can perfectly mix jpg images with png thumbnails or the other way around.

If the html file exists beforehand, the paths to image and thumbnail are inserted relative to the location of the html file. On the contrary, if the html file does not exist beforehand, the full paths to the image and thumbnail are inserted in the code.

In the multi thumbnail dialog, you first choose the scaling method, then you set the corresponding width and/or height parameters. Finally, you may want to adjust the HTML code to be inserted for each image.

Scaling can be based on a fixed ratio, a fixed width, a fixed height, or a fixed width and fixed height (this last option does not keep the original aspect ratio!).

In the HTML code for each image, you can use several placeholders, such as:

• %r for the original filename

• %t for the thumbnail filename

• %w for the original width

• %h for the original height

• %x for the thumbnail width

• %y for the thumbnail height

• %b for the original file size (in bytes)

The default string is:

<a href="%r"><img src="%t" width="%x" height="%y" border="0"></a>

After you have set up the scaling method and parameters, as well as the HTML code, you can select multiple images. Bluefish will create the thumbnails and insert the code.

Here is an example of two thumbnails created with a non nul border width and middle-aligned, with a fixed height and width, disregarding the aspect ratio.

The Multi thumbnail window is the following:

Figure 3.79. The Multi thumbnail dialog

And the generated code is:

<a href="/Users/michga/Desktop/tot/343-4351_IMG_2.png">
<img src="tot/343-4351_IMG_2_thumbnail.png" width="50" 
height="50" border="5" align="middle"></a>
<a href="/Users/michga/Desktop/tot/343-4352_IMG_2.png">
<img src="tot/343-4352_IMG_2_thumbnail.png" width="50"
height="50" border="5" align="middle"></a>

Note

Full pathnames are always used to reference original image sources. The paths to thumbnails are relative to the html file path if the html file already exists, while they are inserted as full paths when the html file does not exist.

Below is a full procedure to quickly generate thumbnails from a directory of image files. This example is purposedly made with deprecated tags, so that you have an idea of what can be made with the variables. Feel free to adjust it when using CSS style sheets.

Procedure 3.4. Generating a photos album with multi thumbnails

1. Put the image files in a folder of their own

2. Open a new file in bluefish, click on the Multi thumbnail... icon in the Standard bar tab of the html tool bar.

3. Enter the scaling percentage in the Scaling (%) field

4. Change the html code as follows:

   <tr><td><a href="%r">
   <img src="%t" 
   width="%x" height="%y" border="0"></a>
   </td>
   </tr>
   <tr><td>Original: %w x %h</td></tr>

   and click OK.

5. Choose the folder containing the images from the Select files for thumbnail creation window, click Ctrl-A to select all files, then click OK. The code generated by Bluefish will look like the following:

   <tr><td><a href="/Users/michga/Desktop/photos/343-4344_IMG.JPG">
   <img src="/Users/michga/Desktop/photos/343-4344_IMG_thumbnail.png" 
   width="80" height="53" border="0"></a>
   </td>
   </tr>
   <tr><td>Original: 1600 x 1065</td></tr>
   <tr><td><a href="/Users/michga/Desktop/photos/343-4347_IMG.JPG">
   <img src="/Users/michga/Desktop/photos/343-4347_IMG_thumbnail.png" 
   width="80" height="53" border="0"></a>
   </td>
   </tr>
   <tr><td>Original: 1600 x 1065</td></tr>

6. Use Ctrl-A to select the file's contents and click on the Table icon located in the Tables tab of the HTML tool bar to embed the code into table tags.

   Figure 3.80. The Table icon in the html tool bar

   

7. Save the file wherever you want.

If you want to add the file name and the file size in bytes, use this code:

<tr><td><a href="%r">
<img src="%t" width="%x" height="%y" border="0"></a>
</td>
</tr>
<tr><td>%r:  %w x %h (%b bytes)</td></tr>

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 the button and selecting Add to quickbar.

Figure 3.81. Adding an element to the Quick bar

And automagically you will see the element in the Quick bar:

Figure 3.82. The added element in the Quick bar

Note that you cannot add a pop up menu. Thus, if the item you want to add is inside a pop up menu (as is the code tag located in the Context formatting pop up menu of the Fonts tool bar), you have to first click on the pop up menu to display its contents, then to right click on the desired element to insert it in the Quick bar.

Figure 3.83. Adding a pop up menu element to the Quick bar

If you want to remove items from the Quick bar, right-click them and select Remove from Quick bar.

Figure 3.84. Removing an element from the Quick bar

You can also change the location of an element in the Quick bar. To do so, right-click the element and select Shift left or Shift Right as desired. The element will be moved to the left or to the right of its neighborough. Notice that this is not a drag and drop action; you may have to repeat the process if you want to move the element farther.

Figure 3.85. Moving an element within the Quick bar

To customize items in the Custom menu tool bar, you will use the Custom menu element:

Figure 3.86. Accessing the custom menu

The Custom menu->Edit custom menu... leads to the Custom Menu Editor. The Load new item allows you to load a new menu in case you have directly changed the custom_menu file located in the .bluefish directory within your HOME directory, while Reset item allows you to return to the default custom menu under the same circumstances.

The custom_menu file is created upon install Bluefish and corresponds to some default entries, the ones you can see in the Custom menu tool bar. These will give you an idea what can be done with the custom menu.

The custom menu operates only on elements of the Custom menu tool bar, and allows you to:

The Custom Menu Editor is the place where you make all changes to the custom menu. The location for entries in the custom menu is defined by their menu path in the Custom Menu Editor:

Figure 3.87. The Custom Menu Editor

It has four parts:

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.

Note that the new menu is placed at the right end of the custom menu tool bar. When closing Bluefish and relaunching it, it will be placed in alphabetical order, except that the Replace menu will always be at the far right side.

In another example, you have a string you often need to set before and after some block of text, for example <div class="MyClass">YourBlockOfText</div>. To do it:

If you now select some text:

Figure 3.92. A block of selected text before activating the menu

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:

Figure 3.93. A block of text after activating the menu

Suppose you want to improve this last example. You have both MyClass1 and MyClass2 and want to be able to choose the desired class when activating the menu. Here's how to do it:

If you now activate this menu after having selected a block of text, you will be presented with a new dialog asking you for the value of MyClass number:

Figure 3.94. The new div with class dialog

After entering the desired value, the same process as before will occur, using the value you provided. Here we have entered 1 as value:

Figure 3.95. The block of text after entering the value

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.96. 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:

Note: Of course, it is also possible to add these items by editing the file named "rcfile_v2" found in the user's home directory (~/.bluefish/rcfile_v2). The fields are delimited by colons and correspond to those found in the GUI.

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, use Edit->Save Shortcut Keys. This will store the settings in the ~/.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.97. 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 ????

Bluefish has been translated into more than 15 different languages and this is only the beginning.

Translation process is not a difficult task but you will need some time because there are more than one thousand strings to be translated. The good news are you don't need to be a programmer to make Bluefish speak your language and the only tool you need is a text editor (Vim, Emacs, bluefish, etc.)

Bluefish uses po (Portable Object) files. A po file is just a plain text file that you can edit with your favorite text editor.

In a typical po file there are five major types of entries:

Hence, your task as a translator is to:

Shortcut keys, known as hotkeys or even accelerator keys, are defined as follows (look at the underscore, please):

# src/toolbars.c:482
#: ../src/filebrowser.c:1453
msgid "/_Refresh"
msgstr "/_Actualizar"

That it means that in the English locale the user have to press Alt-R to activate this particular GUI element. On the other hand if your locale is Spanish your shortcut key will be Alt-A.

It is really easy. Just drop me a line at <wecharri(at)arnet.com.ar> and I will send you your po file ready to be translated. When you have finished the translation work, just send it me back (use gzip or bzip2 if possible, please). Then I will check it and if everything is right I will add it into CVS.

About ten days before a new release I will send a new fresh po copy to each translator to repeat this process.

All po files will be named as follows:

date-foo.po.gz (date: day-month-year)

Example:

12-12-2004.es.po.gz (for Spanish po file)

Please, remember:

And at last, do not start a new translation before contacting me or contact Olivier and do not post your po file at the list, please.

If you have some doubts, do not hesitate contact me at <wecharri(at)arnet.com.ar>.