# Bluefish manual chapter 1: Getting started
Author: Jim Batis

prev | contents | next

# Chapter 1: Getting started

The purpose of this chapter is to give you a short introduction to the basic functions, in order for you being able to start creating and designing your web sites through Bluefish right away. Our purpose for the time being is that you become acquainted with the enviroment and user interface of Bluefish.

This chapter doesn't cover all aspects of Bluefish, but is a mere introduction to the whole enviroment. Later chapters will cover everything in detail.

## Running the program

After the installation, if you haven't changed the installation directory, the executable file should have been placed in `/usr/local/bin/`. So all you have to do in order to run the program is to type: `blashyrkh:~# bluefish`.

If you get an error message "bluefish: file not found", then you might need to make adjustments to your PATH environment variable, which is beyond the scope of this text. Refer to your local Users Group for assistance in adding /usr/local/bin to your PATH. As a temporary measure, you can run it by specifying the path, such as:
`[todd@todd ~]$ /usr/local/bin/bluefish`.

NOTICE: For security reasons, the root account cannot run Bluefish. So, if you're root and type `bluefish` an error message will appear. In order to overwrite this security check and run the program as root, type `bluefish -s`.

The logo of Bluefish will appear for a few seconds and then the main screen (as seen below) will appear. Of course, you can minimize, maximize, etc. this screen, according to the features your window manager gives you (all screenshots below were taken while using KDE).

Commandline options can be found using -h:

    blashyrkh:~# bluefish -h
    bluefish 0.5 HTML editor
    Usage: src/bluefish [options] [filename]

    Currently accepted options are:
    -s           skip root check
    -v           current version
    -h           this help screen
    -p filename  load project on startup

TIP: If you want to open all PHP documents in a directory and it's subdirectories, you could start bluefish like this: `bluefish `find -name '*.php'`` . Or you want to open all html files on your machine? (beware! about 1100 on a standard Debian machine!) Use `bluefish `find / -name '*.html'`` .Check man find and man bash for more info.

## Interface

Let us start explaining some basic stuff about the interface of Bluefish, and in order to do that, we'll take the screen we saw above as a guide.

### The menu

On the top of the screen is the menu, where all functions of Bluefish are listed. Functions are categorized according to their usage, so menu File contains functions that concern files, Edit concern the main editing functions (Cut, Copy, Pase, etc.), and so on. If you press on a menu, its sub-menus will appear. Each sub-menu has its name on the left, and on the right its short-cut which will be explained later on.

NOTICE:In this manual, when we refer to a sub-menu command, we give its full path in the following way: File-->New means that from menu File you must select New.

A very useful function that GTK+ provides is tearoffs. In order to see what this is, select `File` and press on the small dotted line. As you will see, a new window will appear that contains all sub-menus of File. In this way, you can access the functions of a menu quicker, since you could simply place this window next to the main window. If you press on the dotted line again or close the window, the window will disappear. Note that the menu is still accessible not only from the window that appeared, but also from the menu of the main window.

So, what it actually does is to allow the menu to float on screen. The misfortune is that there is no way to save their state and position, so when you re-start Bluefish, no menu will be floating.

#### Shortcuts

While looking at the menus, you may have noticed that in some functions there is a combination of keys in the right. These are called shortcuts and are a combination of keys, usually beginning with Control or Alt. if that combination of keys is pressed, then the function is executed. So, for example, if you want to open a new file, instead of selecting `File-->New` (which has the text Ctrl-N on its right) you could press Control with 'N' together.

A very useful feature is that apart from the default short-cuts, you can add your own or re-define the default ones. Simply move the mouse over the sub-menu you want to add a short-cut and press the combination of keys (e.g. Control with 'G'). As you will see, the combination will appear next to it and the function will be executed next time you press that combination. If the short-cut pre-existed in another sub-menu, it will be deleted from its old position and will go to where you placed it.

In case you want to delete a short-cut, place the mouse over the sub-menu that has the short-cut and press `Backspace`.

TIP:A shortcut can also be the combination of any of Control, Alt, Shift with another key, as well as two of them together, e.g. `Ctrl-Alt-G`. However, note that Shift+key, though accepted will not be accessible, as Shift has already the usage of shifting the case. Alt+Shift+key or Ctrl+Shift+Key will work.

Since short-cuts are used very frequently, you might want to save the changes you've made. Select `Options-->Save Shortcut key settings` to do that. This will also save any shortcuts you have set for the Custom menu (Bluefish 0.5 and later). Note that the short-cuts are NOT saved automaticly, so you need to select that sub-menu each time you want to save them.

Also, note that some short-cuts are reserved by the textbox and cannot be used. A listing of them can be found later on.

### The toolbars

Below the menu are 3 toolbars (in the screen above, only the two of them appear); the main toolbar, the HTML toolbar and the custom menu.

- The main toolbar has shortcuts to the basic functions of Bluefish, like New, Open, Save, Cut, Copy, Paste, Search text, Undo, etc.. In order for this toolbar to be visible, you must have `Options-->View main toolbar` checked.
- The HTML toolbar will come very handy to you, as it holds very important HTML tags that you will be using all the time. The buttons of HTML toolbar are categorized into tabs, according to their usage, so that they are easier to find. In order for this toolbar to be visible, you must have `Options-->View HTML Toolbar` checked.
- The custom menu is a place where you can store functions that you use often, so that you can reach them by a simple button click, rather than the menu. In order for the toolbar to be visible, you must have `Options->View custom menu` checked. Starting from Bluefish 0.5 the custom menu editor is extended, for a good example use `Custom menu->reset custom menu` option. The entry for a custom menu option consists of a menu path which is slash delimited, so the path `Options-->View custom menu` will be /Options/View custom menu in the editor. The entry also consists of a before and an after string. When you select a bit of text and choose the menu option the before string will be inserted before the selection, and the after string after the selection. If there is no selection the entries are inserted after each other and the cursor is placed between them. Often you have a certain piece of code which is mainly similar in most situations, but one or two things change each time. To allow these kind of entries you can use variables in the custom menu, the variables are asked in a dialog before inserting the actual text. First increase the number of variables, you directly see entries appearing named %0, %1, etc. The values in these entries are the names of the values asked in the dialog. If you now use %0 in your before or after string these are replaced by the values entered in the dialog.

| A great thing about toolbars is the fact that they can float as well. Note the left corner of each toolbar, which looks similar to the image at the left. Place the mouse over it, hold the left mouse button down and drag the toolbar to wherever you like and then release the mouse button. In this way, you can make a toolbar float as well.

When a toolbar floats, it doesn't appear in the main window, thus giving more space for the textbox.

If you drag the toolbar back to its original place, it will become part of the main window again. Note that the toolbars will be placed in the following order (from top to bottom): main toolbar, html toolbar, custom menu. So far, there's no way to place a toolbar above another.

A short description of what each button of the toolbar does can appear if you leave the mouse pointer for a few seconds over the button (these are called tool-tips).

As with the menus, you cannot store their position, so when Bluefish is re-started, they will appear in their normal position, as part of the main window.

### The file editing area

The greatest part of the window is taken over the editing area. This is where the text of the files appears. Bluefish allows you to have as many documents opened simultaneously as you like.

The tab menu shows the files that have been opened. In the image above, we have two files: `preface.html`, a file that we opened from disk and `Untitled` which is a new unsaved file. New files are always named "Untitled". The currently selected is "Untitled". This tab allows you to switch through files. If you press on another tab, it switches to the file with the selected filename. Go ahead and try it, by clicking on `File-->New` twice and then switch the tabs. Another way to change the documents (if you haven't changed the short-cuts) is with `F1` to select the next document and `F2` to select the previous document (these shortcuts are in `View` menu).

The appearance of the editing area can be changed in `Options-->Preferences` as we will see later on.

### Statusbar

Finally, at the bottom corner of the screen is the status bar, which is used in order to show messages about actions that have been taken. To understand its usage, observe whatever appears there while you're pressing different buttons, etc.

## Moving to more important stuff

Now that we've explained the basic stuff about the interface, let's continue with using Bluefish.

I believe that the first basic things we need to explain is how you could create new documents, as well as open and save files. Not only will we explain these functions but also help you realize a few features of Bluefish that will make things easier and quicker for you (like Quickstart...).

### Creating a new file

In order to create a new untitled empty file, there are 3 ways:

- Select `File-->New` or press `Ctrl-N`.

- | Press the first button of the main toolbar.

As you will see, a new tab will appear in the editing area and the text will be totally empty.

But it doesn't look good being empty. Wouldn't it be wonderful if you had the basic HTML tags written for you (e.g. the DTD, the title, etc.). Bluefish has a good way to help you write the basic stuff with ease.

- Select `Dialogs-->General-->Quickstart` or press `ALt-Q`.

- | From the "Quick bar" tab in the HTML toolbar, press the first button on the left.

This will pop up a number of windows, in which you can select the DTD, page title and META tags, as well as set the Body variables.

### Editing text

Apparently, you can edit the file using the editing area. In writing tags, the HTML toolbar can appear very useful, since it contains all the basic tags. Some buttons (as well as the functions under the `Dialogs` menu) show windows in which you can easily set the tag parameters, making things faster. In case you want a description of what each button the HTML toolbar does, move the mouse over it and wait until its tool-tip appears.

By default, word-wrap is used (you can disable it at `Options-->Preferences`). In case a line is wrapped, a small icon appears at the right of the line, indication which lines are wrapped. If there are many such icons in a row, this means that a line has been wrapped to many other lines.

I believe this is a good time to pay attention to the `Edit` menu, as it contains some very interesting functions.

- | In case you've done a typing mistake or want to erase the last thing you've written, you can undo the change by selection `Edit-->Undo`, press `Ctrl-Z` or select the Undo button from the main toolbar. In case you've changed your mind, you can Redo the change, by selecting `Edit-->Redo`, pressing `Ctrl-R` or selecting it from the main toolbar.

- The well-known 'Cut, copy, paste' functions couldn't be missing, of course. They are also in the `Edit` menu, as usual and their short-cuts are `Ctrl-X, Ctrl-C, Ctrl-V` for cut, copy, paste accordingly. A text that is cut or copied can be pasted either in the same document or in any other opened file. Furthermore, if you undo a cut, the text re-appears but the text that was cut is still in memory and will be pasted when you press 'Paste'.

  TIP: Not only can you copy/paste text among the documents opened in Bluefish, but also this text can be pasted to any other application. Try to cut/copy text from Gnome-edit for example, and you'll see that you can paste it to Bluefish (and the opposite of course). Or even better, just select some text and use your middle mouse button, you can paste right away!

- The search and replace functionality is quite extended. In the first entry you insert the string to look for. Bluefish can look at 4 places for you:
  - The current document, starting at the beginning
  - The current document, starting at the cursor position
  - The current document, only in the selection (only if there is a selextion)
  - The current document, in all open files
  A couple of options are important. Case sensitive is quite clear, if your search pattern should make difference between case. Regular expression matching is also clear but mnot trivial. We'll give some examples of regular expression matching later on, but also check `man 7 regex` in your shell for a full explanation. Overlapping searches is only relevant when you replace multiple times or you use `Edit-->find again`. Basically if you search for aa and your text contains aaa, you can have two results depending on this option:
  - no overlap: aaa is a match, and there is no second match
  - with overlap: aaa is a match, and aaa is a match

- Replace adds a couple of extra options. First of all, you can replace three things:
  - text, inserted in the `replace with` entry
  - Uppercase, so the match is replaced by its uppercase equivalent
  - Lowercase, so the match is replaced by its lowercase equivalent
  These last two are not very usual, but can come in very handy when using regular expressions. Two options are important for replacing. `Prompt before replacing` allows you to manually check each item Bluefish wants to replace. `replace once` will stop the replacing after finding the first match. You can use `Edit->replace again` to replace the next one.

TIP: Regular expressions are a powerful tool. Suppose you want to lowercase all HTML tags in a document. Without regular expressions you can't do one search and replace. The pattern `<[^>]*>` will find anything between a `<` and a `>` , which does not have a `>` in between. Now select `Replace uppercase` and your done! The drawback: this simple pattern will of course also lowercase the alt description of an image etc. so it's not perfect.
TIP: You've ever seen a HTML document created using Frontpage? These sometimes include hundreds of empty lines and spaces. It is possible to search and replace newlines in Bluefish. But you have to copy and paste them into the entry in the search dialog. So now select two lines, paste the selection into the `find:` entry in the search dialog, replace with a single line, and select `overlapping searches`. All the multiple empty lines will be reduced to a single empty line.

Another interesting feature is the pop-up menu that appears if you press the right mouse button. This is a quick way to use some basic functions, like 'Cut' and 'Copy'. The functions here work exactly as their correspodant functions in the menu and toolbars. As far as the latest item of this pop-up menu is concerned, the 'Edit tag', we will talk about it later on.

### Opening a file (from a disk or the web)

To open a file from a disk:

- Select `File-->Open` or press `Ctrl-O`.

- | Press the second button from the main toolbar.

A 'select file' dialog will appear, from which you can choose the file you want to open. A very useful feature is that in that menu you can select to open more than one file at the same time (only that all files opened must be in the same directory). In fact, we have successfully tried to open 1000 documents at the same time!

- In order to select a series of files, listed one after the other, select the first (or last) file from the 'Files' list, and while `Shift` is pressed, select the last (or first) file. Then, all files between the first and last file selected will be marked blue. If you press 'OK' they will be opened.
- In order to select each single file, select the first and then for every other selected file, press the mouse button on it while you have `Ctrl` pressed.

In Bluefish 0.7 it is possible to open multiple files using File-->Open advanced. Open advanced uses find and grep to select the files to open. This opens a dialog where you have to enter several values:

- Basedir - the directory where to start searching
- File Pattern - the pattern for find, for example *.php
- Recursive - search for pattern recursive
- Contains Pattern - the pattern for grep
- Is regex, if set - use egrep

Another very useful feature is that you can open a file directly taken from the web. In order to do that, select `File-->Open from the web`. In the window that appears, write the full adress of the document (e.g. 'http://jmk.simplenet.com/prod/download.htm'). Of course, adresses like 'http://jmk.simplenet.com/' are accepted and the file opened will be the one just like if you had selected that URL from a web browser.

Finally, a thing you should note is that if you have just opened the program and there's just one untitled file, it will disappear when a file is opened and will be replaced with the file you opened. If however you've changed it even a bit, it will stay.

### Saving files

If you want to save a file, you must first select its name from the tab of files in the editing area (i.e. it must be the one that appears in the main window), and then:

- Select `File-->Save` or press `Ctrl-S` to save it with the name it already has, or select `File-->Save As` to save it with a different name.

- | Press the 'Save' or 'Save As' button from the main toolbar.

By pressing 'Save', the file that is currently viewed is saved. In case the file is unssaved to disk (i.e. if it had been opened from the web or is an untitled file), 'Save' acts like 'Save As'. By pressing 'Save as' you can save it with a different name than the one it already has.

In case you want to save all opened files, select `File-->Save All`. This saves all files, examining each time if the file is untitled or opened from the web. Then the 'Save as' dialog appears for that specific file.

### Closing a file

In order to close a file, you must first select it so that it is viewed in the editing area, then:

- Select `File-->Close` or press `Ctrl-W`.

- | Press the fifth button from the main toolbar.

In case the file has been changed since the last time it was saved, then you will be prompted whether to save it before you close it. In that dialog, by selecting 'Close', the file closes without saving it. If you select 'Save', the file is first saved, and if you press 'Cancel' the file isn't closed at all.

If you want to close all files that have been opened, select `File-->Close All`. In case they are not saved, the former dialog will appear.

## Quiting Bluefish

In order to close Bluefish, you can either close the main window or select `File-->Quit`, which has the short-cut `Ctrl-Q`.

In case there are unsaved files, before the application closes, a similar dialog to the one explained above will appear.

## Working with HTML

So far, we've seen how you can create, open, edit and save a file. Though this is enough to start working, don't forget this is an HTML editor, not simple a text editor. This means that special attention is given to using HTML, thus a few special tools (that you won't find on a simple text editor) have been implemented, to help you in using tags and organising your documents.

### Tags and Dialogs

You may have noticed two menus, `Tags` and `Dialogs`. Most functions on these menus can be also found in the HTML toolbar together.

The `Tags` menu contains a few HTML tags, most of which don't have parameters. These tags include text-formatting tags (Bold, Italic, Strikethrough, etc.), headings, lists, etc. Also, pay attention at the `Tags-->Special` menu which contains a list of special characters.

Let's try to press a sub-menu (make sure that no text is selected). The tag described appears and the cursor is placed between the start (<>) and end (</>) tag, so that you can write the text that belongs in that tag.

Another interesting way that these menus function is you have text selected. For example, write 'Hello World' and then select it. Press `Tags-->Headings-->H1` and the text will be covered with a H1 tag. This is very useful since you can change the formatting (e.g. make it look bold or itallic) of an already-written text quickly.

The `Edit-->Replace special-->replace ascii chars` will replace all occurences of HTML special chars like <>&" with their HTML entities &lt;&gt;&amp;&quot; within the current selection.

The `Dialogs` menu almost has the same usage, but instead of simply writing text, a window is popped up, in which you can place the parameters of the tags. If you leave a field blank, then that parameter won't appear in the text.

### Editing tags

Remember when we mentioned about the pop-up menu that appears when we press the right mouse button on the text area? The last item was Edit Tag. Time to explain what it does.

As you've seen, with `Dialogs` menu you can easily insert parameterized tags. Once they are inserted, you can always edit them manually, by simply editing the text. But, as you've seen, it is easier to adjust the parameters of a tag through the dialogs, rather than writing text. This is where 'Edit Tag' comes in.

From the `Dialogs` menu, select a tag (e.g. `Dialogs-->Table-->Table`, adjust its parameters and insert the tag. Then, place the cursor over the tag, press the right mouse button and select 'Edit Tag'. As you will see, the same window in which you created the tag appears (this time, not all fields are blank, but instead they are set to fit the tag's parameters). Now, you can edit the tags through this menu easier and more automaticly.

Note that this works only with tags that have been inserted from `Dialogs` or the correspodant buttons in the HTML toolbar.

### Syntax highlighting

This feature will be explained in detail at the second chapter, but here is a synopsis of its usage.

In order to easily identify the tags and distinguish them from the normal text, tags can be highlighted (actually, the text is colored differently from the normal text in order to be distinguishable, whereas a normal-life highlighter changes the color of the background).

To set this feature on, check `View-->Highlight syntax`. Each time you want the tags to be colored, select `View-->Refresh highlighting`, default shortcut F5, or this can be done continuously if you adjust the Preferences menu, as you will see later on.

## Projects

Projects in Bluefish will remember some history for you. If you have a couple of files open that are related, choose `Project->add all open documents`. Now save the project (usually located in ~/.bluefish/projects/). Any color you use, or any font, any targets, url's etc. are recorded in the project, and if you save the project they are saved as well. The values can be edited using `Project->edit`, the menu contains `files` and `lists`, where you can access the contents of a project.

When you open a project, all files in that project are opened. If you preview a file which is in a project, the basedir is removed from the filename and replaced by the webdir. So /home/olivier/public_html/index.html can be replaced into http://localhost/~olivier/index.html if you want to. This is very useful when programming dynamic (PHP, SSI, RXML) websites on a local server.

prev | contents | next