Configuring Scriptum

As we mentioned before, almost everything in Scriptum can be configured. From key and mouse bindings to menus and toolbars, the Scriptum environment can be easily changed to fit everyone's needs.

The Scriptum configuration files are simple text files stored in a directory structure like the following:

The installation procedure will suggest /usr/local as the position for the root directory of the structure, inter-soft. As it is shown, the directory structure appears once under the inter-soft directory (to which the $INTER_SOFT variable refers) and again under the Scriptum-vesionnum directory. This is because Scriptum shares some resources (such as error messages or toolbar icons) with other InterSoft graphical applications, such as IQL(InterSoft SQL Interpreter).

When Scriptum starts, it searchs for the Scriptum.scrp file, which is the main configuration file. Scriptum searches some default directories for this file in the following order:

The Scriptum.scrp file can contain all the necessary configurations (i.e., menu, toolbars, colors, mouse and key-binding configurations) in it. However, for readability it is recommended the use of one of the Configuration file keywords: include. include lets the user group the configuration files by classes. The default directory structure that appeared in the previous figure is just an example. Each file includes the other SCRPs it needs with a path relative to the Scriptum resource file root directory (i.e., $INTER_SOFT/Scriptum), where the Scriptum.scrp file is found.

Every included file is searched using the previously mentioned sequence of directories, along with search paths that can be specified in the main file, Scriptum.scrp. This means that the user can copy a certain file or directory structure to the .Scriptum directory under his/her home directory and modify it without changing the global/default configuration and thus affecting other users. In fact, this is what the color-scheme configuration script exploits this feature; running

setScriptumColor simple-dark
will create a link of the default colors configuration file, colors.scrp in $HOME/.Scriptum to $INTER_SOFT/Scriptum-1.1/resources/color-schemes/simple-dark.scrp.

Next, we'll explain the default configuration directory structure layout, along with the syntax of the Scriptum resource files (SCRP for short).

Scriptum Resource Root Directory

At this point it is important to repeat one more time an important concept: the SCRP root directory is more an abstraction than an actual, single directory. Because a given file can be taken from the user's home directory (e.g., /home/john/.Scriptum) and another from the default directory (e.g., /usr/local/inter-soft/Scriptum-1.1/resources). So, the SCRP root is in fact composed of all the root directories in the default (built-in) search path and plus all the search directories specified in the main SCRP file.

Another important thing: Each view can potentially have its own set of menus, toolbars or key-bindings. To speed up the Main View loading process and save memory, Scriptum delays the processing of a given view template until an object corresponding to that view template is actually loaded. So a separate SCRP file for each view naturally fits this loading scheme.

The default SCRP root directory contains the following files:

Scriptum.scrp
colors.scrp 
file-types.scrp
def-browser-info.scrp
res-path.scrp
hosts.scrp

and the following directories

basic
views
color-schemes

The Scriptum.scrp file

The default Scriptum.scrp file has the following contents:

// ---------------------------------------
//   Default Scriptum main resource configuration file
// ---------------------------------------
include ``def-browser-info.scrp'';
include ``resources.scrp'';
include ``file-types.scrp'';
include ``hosts.scrp'';

include ``menus.scrp'';
include ``key-bindings.scrp'';
include ``mouse-bindings.scrp'';
include ``toolbars.scrp'';
include ``features.scrp'';

// Main view and global definitions
view main ``$INTER_SOFT/resources/bitmaps/scriptum.bmp'';

The two keywords that appear here are include and view main. The syntax of the first is simple:

include ``file.ext''
The file name can be referred as relative (without leading /) and the file will be searched using the previously mentioned search path, or absolute (from the system's root directory), in which case no search will be performed. To edit the configuration files, it is recommended to use Scriptum own SCRP View. When the user wants to go to a certain file included in a SCRP, he/she just has to press Alt+g, and Scriptum will find the file using the search path and open it automatically. In any case, if the file isn't found or has no read permissions for the user, Scriptum will send an appropiate error message to the console it was launched from.

The second keyword, view main, defined which type of object will user Scriptum when it starts for the first time. In this case, Scriptum will use a bitmap with the Scriptum logo as the main view, but it could be any type of view Scriptum recognizes. (For the availables types of view, see ``file-types.scrp'' on page 38.)

A comment inside a SCRP file is marked with the double slash (//). From the double slash to the end of the line, everything will be discarded by the configuration file parser.

Other Files in the Root SCRP Directory

colors.scrp

This file is just a simbolic link to the preferred color scheme under the color-schemes directory. It contains definitions on the default color attributes for various standard features. For more on attribbute definition, see ``Documentation'' on page 46.

file-types.scrp

This file could have the following contents:

use ``Standard Text file'' from ``views/text/text.scrp'' for 
regexp ``.*\.txt'', ``.*\.doc'' file type ``ascii text'';

use ``C++ source'' from ``views/c-c++/c++-source.scrp'' for 
regexp ``.*\.icc'', ``.*\.cc'', ``.*\.cpp'';
use ``C/C++ header'' from ``views/c-c++/c-c++-header.scrp'' 
for regexp ``.*\.h'', ``.*\.hh'', ``.*\.hpp'', ``.*\.hxx'';
use ``C source'' from ``views/c-c++/c-source.scrp'' for 
regexp ``.*\.c'';

use ``Scriptum resource file'' from ``views/config-file/
Scrp.scrp'' for regexp ``.*\.scrp'';
use ``Standard configuration file (PanelView)'' from 
``views/config-file/cfg.scrp'' for regexp ``.*\.rc'', 
``.*\.sv'';
use ``Shell script'' from ``views/shell-script/shell.scrp'' 
for regexp ``.*\.sh'';
use ``Profile file'' from ``views/shell-script/shell.scrp'' 
for regexp ``.*\.profile'', ``.*\.*wmrc'';

use ``Main View-like'' from ``views/pixmap/bmp.scrp'' for 
regexp ``.*/Scriptum\.bmp'', ``.*/Scriptum-bw\.gif'' ;
use ``Bitmap'' from ``views/pixmap/bmp.scrp'' for regexp 
``.*\.gif'', ``.*\.bmp'', ``.*\.xpm'';
This file is used to define which views are available, and what file types (defined by the regular expressions) are matched with what views. The generic definition for a view is the following:

use ``View description'' from ``file.scrp'' for regexp ``regularexpression'';
An important thing here is that the View description entered must be exactly like the one that appears in the referred template definition (for more on template definition, see ``Case Study: the C++ Source view'' on page 49); i.e., if the View description says ``C++ Source'' and the template file says ``C++ source'' (see the difference?) Scriptum won't be able to find a match and will return an error when trying to open that view.

def-browser-info.scrp

The contents of this file are the following:

definition path
{
				``$SOURCES/defs'',
				``$WXWIN/defs''
};
Using the definition path keywords, it is possible to define a search path for the definition browser to look for the definitions databases.

res-path.scrp

This file contains the search path that will be used to load configuration files and resources (like bitmaps) before using the default, built-in path.

The contents of this file could be like this:

resource path
{
				``$INTER_SOFT/resources/bitmaps/rusticset/32x32-32'',
				``$INTER_SOFT/resources/bitmaps/default/26x24''
};                                              
As in the previous case, using the resource path keywords it is possible to define a search path for the definition browser to look for the definitions databases.

hosts.scrp

This file contains the hosts that will, by default, appear in the sites listbox of the Open, Open as, Save, Save as and Change Directory/Site dialog boxes. Its format is as follows:

sites
		{
				``[user[:password]@]host.domain''
}
As you can see, it is possible to specify not only the login user for that host, but also the password. In this way, you will be able to connect and switch between connections without any interaction. However, the password is not encrypted inside this file, so care is recommended on this matter.

An example hosts.scrp could look like this:

//
// Place here the system-wide remote sites your team normally works with
//
// You can place your local copy in $HOME/.Scriptum/
hosts.scrp.
// To avoid having to type in the password each time you 
first
// connect to each site, you can add the user and password 
also
// (beware of security though).
//

sites
{
				``careless:hello1@anya.cloc.com''
				``careful@wow.blob.com''
				``anonymous@ftp.w3.org''
};

The basic Directory

This directory contains the basic configuration files needed to run Scriptum. Those files are:

key-bindings.scrp
mouse-bindings.scrp
menus.scrp
toolbars.scrp
features.scrp
documentation.scrp

Key Bindings

The key-bindings.scrp file contains sections like the following:

//
// Scriptum Default KeyBindings
//

keybinding kbFile
{
				FileSave			Ctrl+S    //soft save
				FileHardSave			Ctrl+F2 //hard save
	FileOpen			Ctrl+O  //open file
	 
	ViewCmdHistBrowser			Alt+H      //Undo/Redo browser
	ViewUndoCmd			Ctrl+Z  //undo
	ViewRedoCmd			Ctrl+Y  //redo

	ViewClose			Ctrl+W  //close view

	AppHelp			F1
	FileSave			F2
	FileOpen			F3
	AppRunShellCmd			F4
	FileProcess			F5
	ViewClose			F6  
	ViewCmdHistBrowser			F7
	
	SelSetAttribute			Ctrl++ //set attribute
	SelResetAttribute			Ctrl+- //reset attribute
	FileRefresh			Ctrl+R //screen redraw
		
		
	AppExit			Alt+X  //exit Scriptum
};

With this example, we can now present the generic syntax for a key binding group:

keybinding keybindgroupname
{
				ScriptumCommand			key-sequence
				ScriptumCommand			key-sequence
				...
};
The key-sequence can be an alphanumeric keyboard character or a special (non-printable) character. In the latter case, a code must be supplied. Also, the key sequence may contain control, alt or shift keys. for example

				NavSearchText			Alt+Ctrl+F
Means that the command NavSearchText will be invoked when the Alt+Ctrl+f (lowercase) keys are pressed together.

The shift key, however, is a special case: it is only possible to bind it to Selection commands. When, for example, a Movement command is bound with a sequence that contains the shift key, the Movement command will automatically turn into a Selection command, i.e., it will extend the selection from the cursor position using the Movement that was used.

A reference for all available Scriptum commands appears in Appendix B, and a complete listing of all the Scriptum configuration files appears in Appendix C.

Mouse Bindings

A section of the mouse-bindings.scrp file is as follows:

// Mouse Bindings                     

mousebinding mbGeneral          
{
				SelectionSelect(char)				left	1-click
				SelectionSelect(word)				left	2-click
				SelectionSelect(line)				left	3-click
				SelectionSelect(section)				left	4-click
				SelectionSelect(document)				left	5-click

				NavMouseClick				Shift+left 	1-click
				SurroundingScope				Alt+left	 1-click

				NavSectionBrowser				right	1-click
				NavExpressionBrowser				right	2-click
};
And the generic definition for a mouse binding group is:

mousebinding mousbindgroupname
{
				ScriptumCommand 		key+click sequence
				ScriptumCommand 		key+click sequence
				...
};
The key+click sequence can be any one of the alt, control or shift keys combined with a click sequence (again, the shift key works only in selection mode). The click sequence is formed in the following way:

button no_of_clicks
where

Menus

Menus in Scriptum are as configurable as key bindings or toolbars. A common menu definition could be:

// -----------------------------------
//   Default menu configuration file
// -----------------------------------

// Menus

menu mTextFile ``&File''
{
				FileNew			``&New file \t Ctrl+N''			
				FileOpen		  	``&Open \t Ctrl+O''			
				FileSave		  	``&Save \t Ctrl+S''			
				ViewClose			``&Close \t Ctrl+W''
				---
				FileOpenAs			``O&pen as''			
				FileSaveAs			``Save &as''			
				---
				FileInsert			``&Insert file''			
				FileReload			``&Revert to saved''	 		
				---
				AppCwdOrSite			``&Change directory/site''			
				---
				AppExit			``E&xit \t Alt+X''
};
As in previous cases, the menu definitions have a simple, generic syntax:

menu menuname
{
				ScriptumCommand			MenuEntry
				ScriptumCommand			MenuEntry
				...
};
As previously, Command is any valid Scriptum command. MenuEntry is what will actually appear in the menu. Currently (as of version 1.1 beta) the key that is binded to the menu option must be inserted manually. The final release will include the corresponding binding automatically, thus eliminating the possibility of errors in the menus/keybinding definitions.

The three dashes (``---'') indicate a menu separator.

Toolbars

Currently (version 1.1 beta), toolbars may appear only on the Toolbar Area of a View (The release version will include floating toolbars). A toolbar definition could be as follows:

// Tools
tool tOpenFile  			``open.bmp''	 	FileOpen 	``Open file'';
tool tSaveFile			``save.bmp''	 	FileSave 	``Save file'';
tool tFindText			``find.bmp'' 		NavSearchText ``Find'';
tool tUndo			``undo.bmp''	 	ViewUndoCmd 	``Undo'';
tool tRedo			``redo.bmp''	 	ViewRedoCmd 	``Redo'';
tool tSelCopy			``copy.bmp''		SelectionCopy ``Copy'';
tool tSelDelete 			``clear.bmp''		SelectionDelete			
					``Delete'';
tool tSelCut 			``cut.bmp''		SelectionCut 	''Cut'';
tool tSelPaste			``paste.bmp''		SelectionPaste 	``Paste'';
tool tSelIndent 			``indent.bmp''	 	EditIndent 	``Indent'';
tool tSelOutdent			``outdent.bmp'' 		EditOutdent 	``Outdent'';

toolbar tbStandard
{
	tOpenFile
	tSaveFile
	---
	tSelCut
	tSelCopy
	tSelPaste
	tSelDelete
	---
	tUndo
	tRedo
	---
	tFindText
	---
	tSelIndent
	tSelOutdent
};
The toolbar definition process has two steps: defining the tools, and then creating toolbars with that tools.

A tool can be defined as follows:

tool toolname					 	``bitmap.bmp'' 	ScriptumCommand			Tooltip
Where:

Documentation

Scriptum allows to use marks to defines attributes in the text. For programming, this can be used to make documentations and comments more readable and helps with the task of creating automatic on-line documentation directly from the source code.

The documentation.scrp file defines a subset of the standard HTML language style table and the decorations for that styles.

The contents of that file could be as follows:

// fg, bg, font, pt-size (num, +num, -num, num%), 
// style, weight

attribute htmlBoldAttr
{
	default, default, default, default, 
	default, bold
};

attribute htmlItalicAttr
{
	default, default, default, default,
	italic, default
};

attribute htmlCommentAttr
{
 	blue4, default, default, default, 
 	default, default	  
};

attribute htmlCodeAttr
{
	default, default, Modern, default, 
	default, default
};



attribute htmlHeading1Attr
{
  	default,default,default,+6,default,default
};

attribute htmlHeading2Attr
{
  	default,default,default,+4,default,default
};                           

StyleTable feature htmlStyleTable
{
	``Html Style Table,<,<``

	//- Logical styles.
	``<DFN>,</DFN>,Definition,htmlItalicAttr''
	``<EM>,</EM>,Emphasis,htmlItalicAttr''
	``<CITE>,</CITE>,Cite,htmlItalicAttr''
	``<CODE>,</CODE>,Code,htmlCodeAttr''
	``<H1>,</H1>,Heading1,htmlHeading1Attr''
	``<H2>,</H2>,Heading2,htmlHeading1Attr''
	
	//- Physical styles.
	``<B>,</B>,Bold,htmlBoldAttr''
	``<I>,</I>,Italic,htmlItalicAttr''
	``<TT>,</TT>,Typewriter,htmlCodeAttr''
};
The attributes are used as follows:

attribute attrname
{
				foreground, background, font, pt size, style, weight
};
where:

The StyleTable definition has the following syntax:

StyleTable feature styletablename
{
				``nametable, startchar, endchar''
				``startstr,endstr,nameseq,attribute''
				``startstr,endstr,nameseq,attribute''
				...
}
where:

The views Directory

The views directory includes a different directory for each group of view type. For example: C/C++ source and C/C++ header template configuration files all go under the views/c-c++ directory; then, it is possible to find out what file types Scriptum supports just by looking in the views directory. As an example of a view template definition, will look at how the C++ source is defined by default.

Case Study: the C++ Source view

The C++ Source view template definition file has the following contents:

include ``colors.scrp'';
include ``views/c-c++/c-features.scrp'';
include ``views/c-c++/c++-features.scrp'';

view text ``C++ source''
{
	menus		
				mTextFile, mTextEdit, mTextSearch,
				mTextOptions, mTextTools,
				mTextWindow, mHelp

	bindings	
				kbFile, kbSelection, kbEdition, 
				kbMovement, mbGeneral

	features	
				CKeywords   			: keywordAttribute,
				CPPKeywords 			: keywordAttribute,
				CPreprocessor			: preprocessorAttribute,
				CPPComments   			: commentAttribute,
				CTrace			: attentionAttribute,
				CAttention			: attentionAttribute,
				CPPCasts 			: warningAttribute,
				Cdocumentation 			: commentAttribute,
				Ccomment : warningAttribute,

				Cautoindent,

				mtGeneric,

				CPPSection,

				Geometry(``600x400''),
				viewFontType,
				viewBackgroundColor,
				viewForegroundColor,
				viewSelectionColor,
				viewCursorColor,
				viewBuffer,
				viewRevealedCodesColor

				toolbars		tbStandard, 
						tbDevelopment
};
Before analyzing this file, we must first understand the files that are included at its beggining: c++-features.scrp and c-features.scrp.

The contents of these files is the following:

c-features.scrp

Documentation feature Cdocumentation
{
				``/**'', ``*/''
};

Comment feature Ccomment
{
				``/*'', ``*/''
};

Autoindent feature Cautoindent
{
				`` \t*|''
};

Decoration feature CTrace
{
				``^TRACE.*''
};

Decoration feature CPreprocessor
{
				``^#[ \t]*[a-z]*''
};

// Keyword sets
KeyWordSet feature CKeywords
{
				``asm,volatile,enum,const,struct,union,auto''
				``extern,register,typedef''
				``static,goto,return,sizeof,break''
				``continue,else,for,do,while,switch''
				``case,default,if''
				``forever''
};

KeyWordSet feature CAttention
{
				``ToDo,toDo,toDO,Note,Attention''
};

SectionInfo feature CSection
{
				``C Source Browser''
				``^\([_a-zA-Z].*\)([^;]*$''
				``\1''
				``^$''
				``^\}''
};
c++-features.scrp

//
// Decorations
// Format: ``[fgcolor] [bgcolor] [point, family, style, 
weight]''
//
// FAMILIES : Default, Decorative, Roman, Script, Swiss, 
Modern, Symbol
// STYLES   : Normal, Italic, Slant
// WEIGHTS  : Normal, Light, Bold
//

Decoration feature CPPCasts
{
				``const_cast<[^>]*>''
				``reinterpret_cast<[^>]*>''
				``static_cast<[^>]*>''
				``dynamic_cast<[^>]*>''
};

Decoration feature CPPComments
{
				``//\(.*\)''
};

KeyWordSet feature CPPKeywords
{
				``this,throw,try,virtual,catch,class,''
				``delete,friend,inline,new''
				``operator,private,protected,public,template''
};

SectionInfo feature CPPSection
{
				``C++ Source Browser''
				``^\([_a-zA-Z].*\)([^;]*$''
				``\1''
				``^$''
				``^\}''
};

SectionInfo feature CPPHeaderSection
{
				``C++ Source Browser''
				``^[cs][lt][ar][su][sc][ \t]*\([_a-zA-Z][^ \t;]*\)$''
				``\1''
				``^$''
				``^\}''
};
These two files define the features that will be used in the template. Some features must be related to a color; those relationships are also given in the template. The C and C++ features are divided in two files to optimize configuration file usage (of course, that's possible because C is a subset of C++).

SectionInfo

The section information definition is composed of one identification string and four regular expressions. The regular expressions have the following meaning, and must be inserted in order:

Section header regular expression: pattern that is unique enough to find the line that identifies a section.

Section header expansion pattern: value that will appear in the Section Browser window. Generally is ``\1'' meaning that the first argument (part of the expression between ``\(`` and `` \)'') of the Section header regular expression will be used.

Section beggining pattern: regular expression that identifies the section's beggining, which is the place where the section-separator line (one of Scriptum literate programming features) appears. It will be searched for upwards from the Section header regular expression.It will usually be a null line (regexp = ``^$'')

Section ending pattern: regular expression that defines where the section ends.

Decoration

Specifies a regular expression that will be related to an identifier. Later, the identifier will be bound to a color to highlight properly the desired expression.

KeyWordSet

A set of comma-separated words sorrounded by double quotes that will be identified through the text as ``keywords''. It is possible to include multiple lines of keyword definitions, with an optional comma after each line, except for the last one.

Comment

One or two regular expressions that define a paragraph-wide (i.e., of more than one line) comment (like the /* */ combination in C). Their meaning is as follows:

Comment beginning: defines the regexp that identifies a comment's beginning.

Comment ending: defines the regexp that identifies a comment's ending.

Documentation

Two regular expressions that define a paragraph-wide (i.e., of more than one line) documentation (like the /** */ combination in Java). Their meaning is as follows:

Documentation beginning: defines the regexp that identifies a comment's beginning.

Documentation ending: defines the regexp that identifies a comment's ending.

Inside this markers, Scriptum will recognize a subset of HTML and render it.

Autoindent

This is just a list of characters that defines what will be considered as ``margin characters'' when Scriptum autoindent feature is active. This feature will repeat the previous line characters as new lines are created.

ExplicitAutoindent

This feature still defines an indent character, but depends on an explicit command rather than automatic recognition of the position where the indentation must take place.

Now we can go back to the view template definition. A generic view templeted is as follows:

view text ``identifier''
{
	menus				menu-id, menu-id, ..., menu-id

	bindings				binding-id, ..., binding-id

toolbars toolbar-id, ..., toolbar-id

	features				feature : attribute,
					...
					feature : attribute

					feature,
					...
					feature
};
The features' attributes are defined in the colors.scrp file. Also, a given attribute or feature can be defined inline, i.e., directly inside the template, using the form

attr-feature-name(``value'');
For example,

Geometry(``600x400'');
or

Decoration(``^TRACE.*'') : Attribute(``red,default,default,default,default'');
5


Last Modified: 01:16am , January 20, 1996