4. Navigation and Managing documents

4.1. Navigating through a document
4.2. Navigating through many documents
4.3. Projects
4.4. Bookmarks
4.4.1. Generating several bookmarks at once
4.5. Find and Replace
4.5.1. Find Again
4.5.2. Find from Selection
4.5.3. Find and Replace Using Regular Expressions

4.1. Navigating through a document

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

  • Ctrl-Right-Arrow will jump to the next word boundary

  • Ctrl-Left-Arrow will jump to the previous word boundary

  • End will jump to the end of line

  • Home will jump to the beginning of the line

  • Page-Up will jump one page up

  • Page-Down will jump one page down

  • Ctrl-Home will jump to the top of the document

  • Ctrl-End will jump to the end of the document

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

  • To select the current line, press Home, hold Shift and press End.

  • To select the current word, press Ctrl-Left-Arrow, hold Shift and press Ctrl-Right-Arrow.

4.2. Navigating through many documents

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

A screen shot of the Bluefish 1.0 go menu

The shortcuts are the following:

  • Ctrl-Page-Up will change to the previous document

  • Ctrl-Page-Down will change to the next document

  • Shift-Ctrl-Page-Up will change to the first document

  • Shift-Ctrl-Page-Down will change to the last document

The GoGoto 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 GoGoto Selection.

Figure III.44. Using the Goto Line dialog

A screen shot showing the Goto Line dialog
[Tip]

Check the Keep dialog box to keep the dialog open, when you plan to access several parts of the document by line numbers.

4.3. Projects

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 III.45. The Bluefish Project Menu

A screen shot of the Bluefish 1.0 project menu

Procedure III.3. Creating a New Project

  1. Click on the ProjectNew Project

    If some documents are already opened, check the appropriated box in the Create project dialog.

    Figure III.46. The Create Project dialog

    A screen shot of the create project dialog
  2. Fill in the fields in the Create New Project dialog

    Figure III.47. Creating a New Project

    A screen shot of the new project dialog

    With a Basedir the file browser in the side panel shows only the files within its hierarchy. With gnome-vfs support, the Basedir can be remote, as smb://user:pass@server/someshare/ or sftp://someserver/somedir.

    The Preview URL allows Bluefish to launch the browser to the appropriate URL, for example http://localhost/ Bluefish. This can be very convenient for testing server side scripting languages like PHP, JSP, etc.

    If the Template field is used, Bluefish will use the template file's contents for new files, which can be requested either via the New button on the main tool bar or FileNew (CtrlN). Otherwise an empty document will be created.

  3. Once the project is created, you need to tell Bluefish where you want to save it. An Enter Bluefish project filename dialog will be displayed. Notice that you can save the project in a location different from the files to which the project points.

    Figure III.48. Entering Bluefish Project Filename

    A screen shot of the enter bluefish project dialog

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

Figure III.49. Selecting a Bluefish Project

A screen shot of the select Bluefish project filename dialog

To save the project under its current name/location, use ProjectSave or ProjectSave & close; to save it under a new name/location, use ProjectSave 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 III.50. Opening a Bluefish Project

A screen shot of 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 FileOpen 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

4.4. Bookmarks

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 EditAdd 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 III.51. How bookmarks are marked

A screen shot showing 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 III.52. Bookmarks in the side panel

A screen shot showing 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 III.53. Contextual menu on bookmark in the side panel

A screen shot showing the 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 III.54. Editing a bookmark

A screen shot showing the edition of a bookmark

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

Figure III.55. A named bookmark

A screen shot showing 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 III.56. The contextual menu on a document in the bookmark tab

A screen shot showing the contextual menu on a document in the bookmark tab

4.4.1. Generating several bookmarks at once

To add many bookmarks at once, use the EditFind (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 III.57. Bookmarking with Posix regular expression

A screen shot showing how to bookmark with Posix regular expression

Here is the result:

Figure III.58. Bookmarks with Posix regular expression

A screen shot showing the 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 III.59. Bookmarking Objective C functions via the Find menu

A screen shot showing how to bookmark Objective C functions via the Find menu

Figure III.60. Bookmarking PHP functions via the Find menu

A screen shot showing another use of regular expressions in the find dialog

Check Section 4.5.3, “Find and Replace Using Regular Expressions” for more information on finding and replacing with regular expression in Bluefish.

4.5. Find and Replace

The Edit menu features several options for Find and Replace. The EditFind (Ctrl-F) and EditReplace... (Ctrl-H) menu items will simply start their corresponding dialogs described in Section 3.10, “Basic Find and Replace”.

4.5.1. Find Again

The EditFind 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 III.61. Nth occurrence with Find Again

A screen shot showing the nth occurrence of a search with Find again

Figure III.62. Nth+1 occurrence with Find Again

A screen shot showing the nth + 1 occurrence of a search with Find again

4.5.2. Find from Selection

The EditFind 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 III.63. Selecting a string for subsequent search

A screen shot showing the selection of a string for subsequent search

Clicking on EditFind from selection gives the following result:

Figure III.64. Finding a string from selection

A screen shot showing the result of a find from selection search

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

4.5.3. Find and Replace Using Regular Expressions

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

Example III.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 III.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 III.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 III.4. Transforming a table into a definition list

Say you have the following table:

Figure III.65. The table before transformation

A screen shot of the table before transformation

You want to transform it in the following definition list:

Figure III.66. The table after transformation

A screen shot of 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 Section 5.7, “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.