=rospell HANDBOOK= Contents: 1. About 2. Getting Started 2.1 Editing an Existing File 2.2 Creating a New File 2.3 Backup Files 2.4 Spelling 3. Basic Operation 3.1 File Format 3.2 Selecting Text 3.3 Cut & Paste 3.4 Find & Replace 3.5 Buffers and Navigation 4. Keyboard Shortcuts 4.1 Romanian UTF-8 Characters 4.2 Menus 4.3 Line Cut & 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 & Merge 5.7 Lines of Code 5.8 TOC ==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. A full list of authors and contributors to this project can be found in authors.html. ==2. Getting Started== Welcome to rospell! rospell is a standard GUI (Graphical User Interface) style text editor for programs and plain-text files. It provides all the standard menu, dialog, editing, and mouse support, as well as all of 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 Open from File 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, rospell 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 in that window. To create a new document, choose New Window or New Buffer from File menu. To give the file a name and save its contents to the disk, choose Save or Save As from File menu. ==2.3 Backup Files== Every time a file is opened for editing, rospell saves a copy of the file in ~/.rospell/backup directory. The user can revert to this version at any time by a simple cp (copy) command. At present, no functionality for periodic backups is implemented. ==2.4 Spelling== Several languages are supported by the speller. You can set the language from Language in Preference menu. To start the spelling from the current cursor position simply press Start Spelling. If a word is suspected of having problems, it will be highlighted. The user can fix the problem or press Ignore 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 Add. This dictionary is located in ~/.rospell/dictionary.user. ==3. Basic Operation== As mentioned in Getting Started, all the basic editing operations are supported by rospell. 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 rospell only indirectly via the same font and localization mechanisms common to all X applications. If your system is set up properly, you will probably never see character-set related problems in rospell. Default, rospell uses UTF-8 character set for editing. It is the default character set implemented in X. 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 Select Font in Preferences 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 newline character. MS DOS uses a carriage-return and a newline. rospell can read and write both file formats. To change a document from MS DOS format in standard UNIX format click UNIX CR/LF Cleanup in Tools menu. At present, rospell 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, rospell 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 delete or backspace. 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 & 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. Cut command removes the selected text from your file and places it in the clipboard. Once text is in the clipboard, Paste 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 Cut to remove it, click the pointer to move the position where you want the text inserted, then choose Paste to insert it. Copy copies text to the clipboard without deleting it from your file. You can also use the clipboard to transfer text to and from other X programs which make proper use of the clipboard. There are many other methods for copying and moving text within rospell windows and between rospell and other programs. The most common such method is clicking the middle mouse button to copy the secondary selection (see Selecting Text). Copying the selection by clicking the middle mouse button in many cases is the only way to transfer data to and from many X programs. rospell also supports line selection associated to + and - keys on the numpad, and the regular Insert and Delete keys. For more on this functionality see Keyboard Shortcuts. ==3.4 Find & Replace== Find & Replace dialogs can be accessed using Edit menu. The dialog will let you specify a search string, and in the case of Replace you can also specify the replacement. Several options are present in the dialogs such as Ignore case and Replace All. The window labeled with the search 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 Quick Search. 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 Quick Search. File Grep functionality is also provided under Edit 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 recursive. The result is displayed in search 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. Buffers 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 rospell. 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 Set Bookmark in Edit menu. To go to a particular bookmark use Goto Bookmark also in Edit menu. Quick access to bookmarks is also available by clicking on a bookmark entry in bookmark window. To go to a specific line number choose Goto Line in Edit menu. You can also jump to the beginning of the file - Start of File - or to the end of the file - End of File - from the same menu. What about navigating back in time? Undo lets you do just that. You can also Record and Playback key sequences using the options in Tools menu. ==4. Keyboard Shortcuts== Most of the keyboard shortcuts in rospell 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 Shift modifiers on accelerator keys. ==4.1 Romanian UTF-8 Characters== rospell has embedded support for the Romanian keyboard mapping called Programmer's Keyboard. This mapping works on regular US keyboards by pressing the corresponding key concomitant with Alt or Alt+Shift 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; Note: the embedded mapping described above works in parallel with any other mapping you might have set in X. ==4.2 Menus== File handling: Alt+e - open file Alt+w - save file Alt+x - exit Alt+p - print file
Buffer Handling: Alt+b - show buffer list Alt+n - goto next buffer Alt+d - delete/close buffer
Clipboard Handling: Ctrl+x - cut Ctrl+c - copy Ctrl+v - paste
Navigation: 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
Search & Replace: F5 - search Shift+F5 - search again F6 - replace F7 - grep F8 - table of contents
LaTeX Shortcuts: Ctrl+b - selected text will be marked as bold Ctrl+i - selected text will be marked as italic Ctrl+t - selected text will be marked as typewriter
==4.3 Line Selection and Line Cut & Paste== Different functionality is implemented if a selection is present or not: If nothing is selected: Numpad+ - copy current line into clipboard Numpad- - cut current line Insert - paste
If something is selected: Numpad+ - regular copy, equivalent to Ctrl+c Numpad- - regular cut, equivalent to Ctrl+x Insert - regular paste, equivalent to Ctrl+v
==4.4 Macros and aliases== Record and playback: 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 rospell allows you to define your own aliases. Go to Alias dialog in Preferences menu, you will be prompted for an alias and a replacement. From this dialog you can manage any number of aliases. The aliases are saved in the configuration file in ~/.rospell/alias and will be reloaded automatically every time rospell is started. Alias example: Suppose you want to define an alias for (const char *). In the dialog box set alias as cc and the replacement as (const char *). Save it and exit the dialog box. Every time you press cc followed by a white space, the editor will insert (const char *) in your text. =5. Programming with rospell= Although general in appearance, rospell 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 rospell. When a file is opened, rospell 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 Colors in Preferences 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 ctags window the function code is loaded. rospell is using exuberant-ctags for creating the tag file. The program is run with -e option (emacs mode) from Ctags in Preferences 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 ctag window. A click in this window will take you to the palace in the file where that specific program element was defined. 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 Ctags in Preferences menu or you can temporarily disable it using Lock Ctags 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 C Standard Library, Standard Posix Header Files, and LaTeX. To choose what help items are loaded, use Ctags in Preferences menu. ==5.4 User Scripts== rospell can be extended using user defined scripts. Four such scripts can be defined. The scripts are associated with keys F1 to F4. An example script is as follows: make 2>&1 echo done The scripts are edited using User Scripts under Preferences menu. Pressing F1 key, the script is run - in this case build the software in the current directory - and the results are displayed in user 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 Beautify in Tools 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 rospell in the pop-up menu activated by a mouse right-click in the edit window. It includes Shift Left, Shift Right, Space to Tab, and Tab to Space. It only works on selected text. Full lines need to be selected. ==5.6 Diff & Merge== Diff & Merge are two activities that are part of any programmer's life. You have support for them in Tools 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. Session Diff under Tools 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 ~/.rospell/backup directory. ==5.7 Lines of Code== This feature allows you to count the number of lines of code in your project. ==5.8 TOC== The meaning of TOC (Table of Contents 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 LaTeX, TOC includes the position of chapter, section, and subsection tags in the current file. TOC for the current file can be generated using TOC in Tools menu. The result is displayed in search window. Easy mouse-based navigation is provided. Currently TOC functionality is only implemented for C/C++ and LaTeX.