<b>Contents:</b>

 1. About

 2. Getting Started
   2.1 Editing an Existing File
   2.2 Creating a New File
   2.3 Backup and Autosave
   2.4 Spelling

 3. Basic Operation
   3.1 File Format
   3.2 Selecting Text
   3.3 Cut &amp; Paste
   3.4 Find &amp; Replace
   3.5 Buffers and Navigation

 4. Keyboard Shortcuts
   4.1 Romanian UTF-8 Characters
   4.2 Menus
   4.3 Line Cut &amp; Paste
   4.4 Macros and aliases

 5. Programming with rospell
   5.1 Syntax Highlighting
   5.2 Ctags
   5.3 Context Help
   5.4 User Scripts
   5.5 Code Beautifier
   5.6 Diff &amp; Merge
   5.7 Lines of Code
   5.8 Function List

==1. About==
rospell, Copyright (C) 2005-2007 Rospell Team, http://rospell.sourcefoge.net .

This program is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later version.

<b>Authors:</b>
<ul>
<li>Lucian Constantin - software.</li>
<li>Ion-Mihai Tetcu -  FreeBSD porting.</li>
<li>Ionut Artarisi -  Arch Linux packaging.</li>
<li>Cristi Magherusan -  LaTeX testing.</li>
<li>Alin Dobre and Gentoo Romanian Translation Team (http://www.gentoo.ro) -  speller testing.</li>
</ul>

==2. Getting Started==
<b>Welcome to <i>rospell</i>!</b>

<i>rospell</i> is a standard GUI (Graphical User Interface) text editor for programs
and plain-text files. It provides all the standard
menu, dialog, editing, and mouse support, as well as all the standard shortcuts to
which the users of modern GUI based environments are accustomed.

To start the program simply enter the command:
 rospell filename

==2.1 Editing an Existing File==
To open an existing file, choose <i>Open</i> from <i>File</i> menu. You may open any number
of files at the same time. Your files will appear as buffers in the same editor window.

Two editor windows are available. By default, one of them is minimized. In order to bring
the second window into focus, grab the splitter bar located at the bottom of the first
window and drag it with the mouse. Then click in the second window.

You can also get access to files by clicking with the mouse on a filename in directory
window located left to the editing windows. Over there, you can also browse the existing directories
by clicking on directory names and .. entry.

Regardless how many times you click on the same filename, <i>rospell</i> will ensure you
don't accidentally open the same file twice.

==2.2 Creating a New File==
If you already have an empty window displayed, just begin typing.
To create a new document, choose <i>New Window</i> or <i>New Buffer</i> from <i>File</i> menu.
To give the file a name and save its contents to the disk, choose <i>Save</i> or <i>Save As</i> from
<i>File</i> menu.

==2.3 Backup and Autosave==
Every time a file is opened for editing, <i>rospell</i> saves a copy in <i>~/.rospell/backup</i>
directory. The user can revert to this version at any time using a simple cp (copy) command.

A file opened and modified in rospell without being saved, will be automatically saved every 10 minutes
in <i>~/.rospell/autosave</i> directory. The user can revert to this version at any time using a simple
cp (copy) command.

Both backup and autosave features can be turned off in <i>Preferences / File Option</i> dialog.

==2.4 Spelling==
Several languages are supported by the speller.
You can set the language from <i>Language</i> dialog in <i>Preference</i> menu. To start the
spelling from the current cursor position simply press <i>Start</i>. If a word
is suspected of having problems, it will be highlighted. You can fix the text problem
or press <i>Ignore</i> to continue with the spelling.

Functionality is also implemented to allow the user to add a new word to a local user dictionary
by pressing <i>Add</i>. This dictionary is located in <i>~/.rospell/dictionary.user</i>.

==3. Basic Operation==
As mentioned in <i>Getting Started</i>, all the basic editing operations are supported by <i>rospell</i>.
In this chapter we will take an in-depth look at some of them.

==3.1 File Format==
While plain-text is probably the simplest and most interchangeable file format in the computer world,
there is still variation in what plain-text means from system to system.  Plain-text files can differ in
character set, line termination, and wrapping.

While character set differences are the most obvious and pose the most challenge to portability,
they affect <i>rospell</i> only indirectly via the same font and localization mechanisms common
to all X11 applications.  If your system is set up properly, you will probably never see character-set
related problems in <i>rospell</i>.

Default, <i>rospell</i> uses UTF-8 character set for editing. It is the default character set implemented
in X11. If you have a UTF-8 file and characters are not displayed correctly, it is because
the current font the editor is using does not have full UTF-8 support. You can change it by clicking on <i>Select Font</i> in
<i>Preferences</i> menu.

You can force the editor to use a different character set using the command line options when you
start the editor:
 USAGE: rospell [OPTION] filename
    --iso8859-2: using ISO8859-2 character set
    --iso8859-16: using ISO8859-16 character set
    --cp1250: using CP1250 (Windows) character set
The primary difference between an MS DOS format file and a Unix format file, is how the lines are terminated.
Unix uses a single <i>newline</i> character.  MS DOS uses a <i>carriage-return</i> and a <i>newline</i>. <i>rospell</i> can read
and write both file formats. To change a document from MS DOS format in standard UNIX format click
<i>UNIX CR/LF cleanup</i> in <i>Tools / Cleaners</i> menu and <i>File Options</i> dialog in <i>Preferences</i> menu

At present, <i>rospell</i> does not implement wrapping.

The last and most minute of format differences is the terminating newline. Some Unix compilers and
utilities require a final terminating newline on all files they read and fail in various ways on files which
do not have it.  Vi and approximately half of Unix editors enforce the terminating newline on all files
they write; like Emacs, <i>rospell</i> does not enforce this rule.

==3.2 Selecting Text==
To select text for copying, deleting, or replacing, press the left mouse button with the pointer
at one end of the text you want to select, and drag it to the other end. The text will be
highlighted. To select a whole word, double click (click twice quickly in succession).
Double clicking and then dragging the mouse will select a number of words. Similarly,
you can select a whole line or a number of lines by triple clicking or triple clicking and dragging.
To delete the selected text, press <i>delete</i> or <i>backspace</i>.
To replace it, begin typing.

The middle mouse button can be used to make an additional selection (called the secondary selection).
As soon as the button is released, the contents of this selection will be copied to the insert position of the
window where the mouse was last clicked (the destination window).

==3.3 Cut &amp; Paste==
The easiest way to copy and move text around in your file or between windows, is to use the clipboard,
an imaginary area that temporarily stores text and data.  <i>Cut</i> command removes the selected text
from your file and places it in the clipboard.  Once text is in the clipboard,
<i>Paste</i> command will copy it to the current position in the current window.  For example, to move some
text from one place to another, select it by dragging the mouse over it, choose <i>Cut</i> to remove it, click the
pointer to move the position where you want the text inserted, then choose <i>Paste</i> to insert it.
<i>Copy</i> copies text to the clipboard without deleting it from your file. You can also use the clipboard to
transfer text to and from other X11 programs which make proper use of the clipboard.

There are many other methods for copying and moving text within <i>rospell</i> windows and between <i>rospell</i> and
other programs.  The most common such method is clicking the middle mouse button to copy the secondary
selection (see <i>Selecting Text</i>).  Copying the selection by clicking the middle mouse button in many
cases is the only way to transfer data to and from many X11 programs.

<i>rospell</i> also supports line selection associated to <i>+</i> and <i>-</i> keys on the numpad, and
the regular <i>Insert</i> and <i>Delete</i> keys. For more on this functionality see <i>Keyboard Shortcuts</i>.

==3.4 Find &amp; Replace==
Find &amp; Replace dialogs can be accessed using <i>Edit</i> menu. The dialog will let you specify a search
string, and in the case of <i>Replace</i> you can also specify the replacement. Several options are present
in the dialogs such as <i>Ignore case</i> and <i>Replace All</i>.

The window labeled with the <i>search</i> tab is associated to the search operation. Following a search
command, this window will provide information regarding all the occurrences of the search string in the
file starting from the current cursor position. The line number is supplied, and also the context in which the search string appeared. A click
with the mouse on this information will jump you to the correct position in the file in the edit window.

Another search feature is called <i>Quick Search</i>. Put the cursor in the edit window under a word you want to search
forward in the file and do a left-click with the mouse. A menu will pop-up, chose <i>Quick Search</i>.

File <i>Grep</i> functionality is also provided under <i>Edit</i> menu. The grep operation will
go trough all the files in the current directory and it will also visit any subdirectory it might find in your current
directory. In other words, grep is <i>recursive</i>. The result is displayed in <i>search</i> window, a click
with the mouse will take you to the specific place in the specific file where the search string was found.

==3.5 Buffers and Navigation==
As previously mentioned, several files can be edited in an edit window as buffers. <i>Buffers</i> menu
is used to switch between the various files opened in the editing window.

Also for navigation purposes, one might use the bookmark feature of <i>rospell</i>. A bookmark
is a place your editor remembers, and if requested will allow you to quickly go to that particular
spot in the file. Bookmarks are set using <i>Set Bookmark</i> in <i>Edit</i> menu. To go to a particular
bookmark use <i>Goto Bookmark</i> also in <i>Edit</i> menu.

Quick access to bookmarks is also available by clicking on a bookmark entry in <i>bookmark</i>
window.

To go to a specific line number choose <i>Goto Line</i> in <i>Edit</i> menu. You can also jump to the
beginning of the file - <i>Start of File</i> - or to the end of the file - <i>End of File</i> - from the same menu.

What about navigating back in time? <i>Undo</i> lets you do just that. You can also <i>Record</i>
and <i>Playback</i> key sequences using the options in <i>Tools</i> menu.

==4. Keyboard Shortcuts==
Most of the keyboard shortcuts in <i>rospell</i> are shown on the right hand sides of the pull-down
menus.  However, there are more which are not as obvious.  These include: dialog button shortcuts,
menu and dialog mnemonics, labeled keyboard keys, such as the arrows, page-up, page-down, and home,
and optional <i>Shift</i> modifiers on accelerator keys.

==4.1 Romanian UTF-8 Characters==
<i>rospell</i> has embedded support for the Romanian keyboard mapping called <i>Programmer's Keyboard</i>.
This mapping works on regular US keyboards by pressing the corresponding key concomitant with <i>Alt</i>
or <i>Alt+Shift</i> as follows:
 ă - Alt+a; Ă - Alt+Shift+a;
 â - Alt+q; Â - Alt+Shift+q;
 î - Alt+i; Î - Alt+Shift+i;
 ş - Alt+s; Ş - Alt+Shift+s;
 ţ - Alt+t; Ţ - Alt+Shift+t;
<i>Note: the embedded mapping described above works in parallel with any other mapping you might have
set in X11.</i>

==4.2 Menus==
<b>File handling:</b>
 Alt+o - open file
 Alt+w - save file
 Alt+x - exit<br />
<b>Buffer Handling:</b>
 Alt+b - show buffer list
 Alt+n - goto next buffer
 Alt+d - delete/close buffer<br />
<b>Clipboard Handling:</b>
 Ctrl+x - cut
 Ctrl+c - copy
 Ctrl+v - paste<br />
<b>Navigation:</b>
 Alt+g - goto line number
 Ctrl+PgUp - goto beginning of file
 Ctrl+PgDown - goto end of file
 Alt+1...0 - set bookmark
 Alt+j followed by 1...0 - goto bookmark<br />
<b>Search &amp; Replace:</b>
 F5 - search
 Shift+F5 - search again
 F6 - replace
 F7 - grep
 F8 - table of contents<br />
<b>LaTeX Shortcuts:</b>
 Ctrl+b - selected text will be marked as <b>bold</b>
 Ctrl+i - selected text will be marked as <i>italic</i>
 Ctrl+t - selected text will be marked as typewriter<br />

==4.3 Line Selection and Line Cut &amp; Paste==
Different functionality is implemented if a selection is present or not:

<b>If nothing is selected:</b>
 Numpad+ - copy current line into clipboard
 Numpad- - cut current line
 Insert - paste<br />
<b>If something is selected:</b>
 Numpad+ - regular copy, equivalent to Ctrl+c
 Numpad- - regular cut, equivalent to Ctrl+x
 Insert - regular paste, equivalent to Ctrl+v<br />

==4.4 Macros and aliases==
<b>Record and playback:</b>
 Alt+r - start macro recording; the next Alt+r will stop
            macro recording
 Alt+p - playback the last recorded macro; if recording
            is in progress, the recording will be ended
Additionally <i>rospell</i> allows you to define your own <b>aliases</b>. Go to <i>Alias</i> dialog in
<i>Preferences</i> menu, you will be prompted for an <i>alias</i> and a <i>replacement</i>. From
this dialog you can manage any number of aliases. The aliases are saved in the configuration
file in <i>~/.rospell/alias</i> and will be reloaded automatically every time <i>rospell</i> is started.

<b>Alias example:</b>
Suppose you want to define an alias for <i>(const char *)</i>. In the dialog box set <i>alias</i>
as <i>cc</i> and the <i>replacement</i> as <i>(const char *)</i>. Save it and exit the dialog box. Every
time you press <i>cc</i> followed by a white space, the editor will insert <i>(const char *)</i> in your text.

==5. Programming with rospell==
Although general in appearance, <i>rospell</i> has many features intended specifically for programmers.
Some of them are detailed here.

==5.1 Syntax Highlighting==
Syntax Highlighting means using colors and fonts to help distinguish language elements
in code and other types of structured files. Programmers use syntax highlighting
to understand code faster and to spot many kinds of syntax errors quickly.

Syntax Highlighting is enabled by default in <i>rospell</i>. When a file is opened, <i>rospell</i> will
try to guess the computer language used in the file based on the file extension. If no such determination
can be done, xml type is assumed.

Languages supported by the syntax highlighter include: C, C++, JavaScript, Java, C#, XML, HTML, PHP,
assembler, qmake, PERL, Python, shell, and LaTeX.

You can change the default color scheme from <i>Colors</i> in <i>Preferences</i> menu.

==5.2 Ctags==
This is probably one of the most spectacular programming feature an editor can have. You use
a special program to create a tag file that contains information regarding
various functions, structures, and data definitions in your code. When the editor is started, the tag file
is loaded and it is used to navigate trough the program. For example, you would put the cursor under
a function name, and in <i>ctags</i> window the function code is loaded.

<i>rospell</i> is using exuberant-ctags for creating the tag file. The program is run with -e option (emacs
mode) from <i>Ctags</i> in <i>Preferences</i> menu. Additional parameters can be supplied to
ctags in this dialog box.

Once the tag file was crated and loaded, the tag engine kicks in and displays tagging information
in <i>ctag</i> window. A click in this window will take you to the palace in the file where that specific
program element was defined. 34 different programming languages are supported.

Ctags feature is somehow hard on CPU resources. It might be necessary to shut it down on some
old computers. You can do this form <i>Ctags</i> in <i>Preferences</i> menu or you can temporarily
disable it using <i>Lock Ctags</i> in the same menu.


==5.3 Context Help==
Context help is similar with the tagging feature, and it is in fact using the same ctags engine.
It consist of a number of help files, tagged with exuberant-ctags and loaded in the engine at startup.
Currently, help tags are generated for <i>C Standard Library</i>, <i>Standard Posix Header Files</i>,
and <i>LaTeX</i>. To choose what help items are loaded, use <i>Ctags</i> in <i>Preferences</i> menu.

==5.4 User Scripts==
<i>rospell</i> can be extended using user defined scripts. Four such scripts can be defined.
The scripts are associated with keys <i>F1</i> to <i>F4</i>. An example script is as follows:
 make 2>&amp;1
 echo done
The scripts are edited using <i>User Scripts</i>  under <i>Preferences</i> menu. Pressing <i>F1</i> key,
the script is run - in this case build the software in the current directory - and the results are displayed
in <i>user</i> window. A click with the mouse in this window, will take you directly to the place where
the compilation has failed as reported by your compiler.

==5.5 Code Beautifier==
This feature allows you to format your source code in a particular manner, according to your preferred
style of formating white spaces, brackets and indentation. To access it, press <i>Beautify</i>
in <i>Tools</i> menu. Before formating, the current file is saved. If you are not satisfied with the result
reload the previous version from the disk.

Related functionality is implemented in <i>rospell</i> in the pop-up menu activated by a mouse right-click
in the edit window. It includes <i>Shift Left</i>, <i>Shift Right</i>, <i>Space to Tab</i>, and
<i>Tab to Space</i>. It only works on selected text. Full lines need to be selected.

==5.6 Diff &amp; Merge==
Diff &amp; Merge are two activities that are part of any programmer's life. You have support for them in
<i>Tools</i> menu. They basically consist of comparing two files and analyzing the differences.
In the case of merge, a third file is created. Merging is the process of reconciling multiple changes
made to different copies of the same file. Most often, it is necessary when two programmers modify
the same file in the same time on two different computers. Later, the changes have to be merged,
resulting into a single file that contains both sets of changes.

<i>Session Diff</i> under <i>Tools</i> menu allows the user to analise the differences between the
current file and the same file when it was first opened in the editor. It comes in handy if you want to
see what you modified before closing the file. The original version is kept in <i>~/.rospell/backup</i> directory.

==5.7 Lines of Code==
This feature allows you to count the number of lines of code in your project (KLOC).

==5.8 Function List==
The meaning of Function List differs from file type to file type. In C for example it is a list of functions
in the current file and the lines these functions have been defined. In C++ it will also show the class
members. In LaTeX, it includes the position of chapter, section, and subsection tags in the current file.

It works as a table of content for the current file. A default implementation for C language and LaTex
is provided. However, if exuberant-ctags is present in the system, ctags will be used. The advantage
is ctags supports 34 different programming languages. Since ctags comes either as <i>ctags</i> or
<i>exuberant-ctags</i> on different systems, a menu for setting it can be found in <i>Preferences / Ctags</i>
dialog.

The function list for the current file can be generated using <i>Function List</i> in <i>Edit</i> menu
or by pressing F8 key. The result is displayed in <i>search</i> window. Easy mouse-based navigation
is provided.

