SciTE Documentation

This file contains documentation for the SciTE text editor. Because Lnz Scite is just a modified version of SciTE, much of this document is relevant, although there are slight differences. One difference is that Lnz Scite looks for .properties file in the properties directory. Nearly all of the configuration settings can still be used, although sometimes default settings are different.

Standard Editing

Text editing in SciTE works similarly to most Macintosh or Windows editors with the added feature of automatic syntax styling. Rectangular regions of text can be selected in SciTE by holding down the Alt key on Windows or the Ctrl key on GTK+ while dragging the mouse over the text.

There are two panes in SciTE, the editing pane and the output pane. The output pane is located either to the right of the editing pane or below it. Initially it is of zero size, but it can be made larger by dragging the divider between it and the editing pane. The Options | Vertical Split command can be used to move the output pane beneath the editing pane.

SciTE can perform commands to compile or run source files with the output from these commands directed into the output pane.

For example, if Python is installed on the machine, open a new document, type:

print "Hi"

as that document's text.

print "hi"

>python -u printhi.py
hi
>Exit code: 0

SciTE partially understands the error messages produced by Python, GCC, Visual C++, Borland C++, PHP and other tools which use the same format as one of these. To see this, add a mistake to the Python file by adding a second line to make the file:

print "hi"
mistake

Perform the Tools | Go command. The results should look like:

>python -u printhi.py
hi
Traceback (innermost last):
  File "printhi.py", line 2, in ?
    mistake
NameError: mistake
>Exit code: 1

While it is easy to see where the problem is in this simple case, when a file is larger the Tools | Next Message command can be used to view each of the reported errors. Upon performing Tools | Next Message, the first error message in the output pane is highlighted with a yellow background, and an error indicator is displayed for the appropriate line in the editing pane. The caret is moved to this line and the pane is scrolled if needed to show the line.

SciTE understands both the file name and line number parts of error messages in most cases so can open another file (such as a header file) if errors were caused by that file. This feature may not work where the file name is complicated by containing spaces or ".."

If command execution has failed and is taking too long to complete then the Tools | Stop Executing command can be used.

Command subsystem

Tools can be executed in various modes by SciTE which are called "subsystems". Different subsystems are supported on Windows and GTK+. The default subsystem is 0.

Command line arguments

Command line arguments to SciTE include file names, commands and properties. Commands and properties are preceded by "-" and are differentiated by the use in commands of ':' as the first character that is not '.' or alphabetic. Properties use the syntax used in property set files and override any properties set in property files. If there is no value given for a property, it is set to 1. Double quotes may be placed around arguments that contain spaces but they must be placed around the whole argument, not just around a file name, so "-open:x y.txt" works but -open:"x y.txt" doesn't. On Linux, the standard shell quoting is available. The "-p" argument causes SciTE to print the file and then exit.

For Windows:
The command line arguments "-" and "--" (without the quotes) are special in that they read the stdin stream into the last buffer ("-"), or the output pane ("--"))
The command line argument "-@" (without the quotes) is special in that file names are read from stdin and opened.
Note: when reading stdin into the output pane, when the property split.vertical is 0, the output pane is increased to its maximum height. When the property split.vertical is 1, the output pane is increased to approximately half of the screen width.
Note: If stdin is not redirected, these arguments are effectively ignored.

For example,

Command line arguments are evaluated left to right in two phases because opening files requires the user interface to be available and there is also a need to set some user interface properties before the user interface is displayed. The first phase process arguments until just before the first file name would be opened. The second phase processes the remaining arguments.

So, if you need to perform e.g. a find: or a goto: command on a file, you must put the command after the filename, to allow SciTE to open the file before performing the command.

For Windows:
If any simple file name on the command line matches a directory name, the file open dialog appears - this is dependant upon the property "open.dialog.in.file.directory"

If the property "buffers" is greater than one and the file name matches either a existing file or by means of a wildcard search, one or more files, the matching files are loaded up to the property "buffers" count. Directories are not considered a match in this case

If the file name is an extension, optionally preceded by a path, and no such simple file name exists, the file open dialog appears, with the given extension as the filter.

If the file name contains no extension, the property "source.default.extensions" is used to provide default extensions to attempt to match the file name to an existing file.

Buffers

SciTE may be configured to use between 1 and 100 buffers each containing a file. The default is 1 and this effectively turns off buffers. With more than one buffer, the Buffers menu can be used to switch between buffers, either by selecting the file name or using the Previous (F6) and Next (Shift+F6) commands. Setting more than 10 buffers may cause problems as some menus are fixed in length and thus files beyond that length may not be accessible.

When all the buffers contain files, then opening a new file causes a buffer to be reused which may require a file to be saved. In this case an alert is displayed to ensure the user wants the file saved.

Sessions

A session is a list of file names. You can save a complete set of your currently opened buffers as a session for fast batch-loading in the future. Sessions are stored as properties files with the extension ".session".

Use File | Load Session and File | Save Session to load/save sessions. You can turn on/off "last session autoloading" using SciTE properties variable "save.session".

If "buffers" variable is set to "0" session management is turned off.

Loading previously saved session will close your currently opened buffers. However you will not lose your edits, because you will be asked to save unsaved buffers first.

Opening a specific file from command line overrides "save.session" variable state. When you start SciTE loading a specific file from command line last session will not restore even if "save.session" variable is set to "1". This makes "save.session" safe to use - you will never open a couple of files when you are trying to open just one, specific file.

Languages understood by SciTE

SciTE currently is able to syntax style these languages (* denotes support for folding):

• Abaqus*
• Ada
• ANS.1 MIB definition files*
• APDL
• Assembler (NASM, MASM)
• Asymptote*
• AutoIt*
• Avenue*
• Batch files (MS-DOS)
• Baan*
• Bash*
• BlitzBasic*
• Bullant*
• C/C++/C#*
• Clarion*
• cmake*
• conf (Apache)*
• CSound*
• CSS*
• diff files*
• E-Script*
• Eiffel*
• Erlang*
• Flagship (Clipper / XBase)*
• Flash (ActionScript)*
• Fortran*
• Forth*
• GAP*
• Haskell
• HTML*
• HTML with embedded JavaScript, VBScript, PHP and ASP*
• Gui4Cli*
• IDL - both MSIDL and XPIDL*
• INI, properties* and similar
• InnoSetup*
• Java*
• JavaScript*
• LISP*
• LOT*
• Lout*
• Lua*
• Make
• Matlab*
• Metapost*
• MMIXAL
• MSSQL
• nnCron
• NSIS*
• Objective Caml*
• Opal
• Octave*
• Pascal/Delphi*
• Perl, most of it except for some ambiguous cases*
• PL/M*
• Progress*
• PostScript*
• POV-Ray*
• PowerBasic*
• PureBasic*
• Python*
• R*
• Rebol*
• Ruby*
• Scheme*
• scriptol*
• Specman E*
• Spice
• Smalltalk
• SQL and PLSQL
• TADS3*
• TeX and LaTeX
• Tcl/Tk*
• VB and VBScript*
• Verilog*
• VHDL*
• XML*
• YAML*

Running and building commands for some of these languages have been set up but should be checked as they will have to be modified to work for many people.

To keep menus to a reasonable length some languages are included but have been commented out in global options. These should be enabled by removing the comment character '#'.

Language settings are determined from the file extension but this can be changed by selecting another language from the Language menu. The language menu can be changed with the menu.language property.

Find and Replace

SciTE has options to allow searching for words, regular expressions, matching case, in the reverse direction, wrapping around the end of the document. C style backslash escapes which are listed in the command line arguments section, may be used to search and replace control characters. Replacements can be made individually, over the current selection or over the whole file. When regular expressions are used tagged subexpressions can be used in the replacement text. Regular expressions will not match across a line end.

SciTE supports basic regular expressions with tagging.

Keyboard commands

SciTE uses the default key bindings defined in Scintilla, so keyboard commands in SciTE mostly follow common Windows and GTK+ conventions. All move keys (arrows, page up/down, home and end) allows to extend or reduce the stream selection when holding the Shift key, and the rectangular selection when holding the Shift and Alt keys. Some keys may not be available with some national keyboards or because they are taken by the system such as by a window manager on GTK+. The user.shortcuts setting may be used to assign a key to a function. Note that Home key behaviour is changed by the vc.home.key option. Keyboard equivalents of menu commands are listed in the menus. Some less common commands with no menu equivalent are:

Abbreviations

To use an abbreviation, type it and use the Expand Abbreviation command or the Ctrl+B key. The abbreviation is replaced by an expansion defined in the Abbreviations file. You can open the Abbreviations file with a command in the Options menu and add abbreviations. There is a default abbreviations file but a different abbreviations file can be set for particular file extensions.

Each line in the files looks like "abbreviation=expansion".
The abbreviations names can have any character (except perhaps control chars, surely for CR and LF), including high Ascii chars (accented chars).
Names have properties files limits: they cannot start with sharp (#) or space or tab (but can have spaces inside); and they cannot have '=' character inside.
Abbreviations names are limited to 32 characters. It is probably enough for abbreviations...

An expansion may contain new line characters indicated by '\n' and a caret position indicated by the '|' character. To include a literal '|' character, use '||'.
Some simple examples are included in the distributed Abbreviations file.
When expanding, the names don't need to be separated from the previous text. Ie. if you define 'É' as 'é', you can expand it inside a word.
If a name is the ending of another one, only the shorter will ever be expanded. Ie. if you define 'ring' and 'gathering', the later will see only the 'ring' part expanded.

Folding

SciTE supports folding for many languages (see the list of languages understood by SciTE for more information.) Fold points are based upon indentation for Python and on counting braces for the other languages. The fold point markers can be clicked to expand and contract folds. Ctrl+Shift+Click in the fold margin will expand or contract all the top level folds. Ctrl+Click on a fold point to toggle it and perform the same operation on all children. Shift+Click on a fold point to show all children.

Properties file

Much of SciTE's behaviour can be changed by editing the properties files.

There are four properties files used:

• Local properties file called "SciTE.properties" which may be present in the same directory as the file being edited.
• Directory properties file called "SciTEDirectory.properties" which may be present in the same or in a parent directory as the file being edited.
• User properties file called "SciTEUser.properties" on Windows and ".SciTEUser.properties" on GTK+
• Global properties file called "SciTEGlobal.properties"

Settings in the local properties file override those in the directory properties file which overrides those in the user properties file which override those in the global properties files. Environment variables are also available as properties and these are overridden by an explicit setting in one of the properties files.

The directory properties file can be used as project options file where user commands and compile, build commands should work in the same manner in subdirectories of a project. The benefit is that local properties files in subdirectories can be replaced by one properties file which is located at the root of the project. The evalution of the directory properties file is disabled by default and must be enabled by setting the variable properties.directory.enable to 1 in the user or global properties file.

The user properties file is intended for customisation by the user, leaving the global properties file to contain the default options distributed with SciTE. The main use of the local properties files is to change the effects of the Compile, Build and Go commands for the files in a directory. For example, I use the javac compiler from the Java Development Kit for most work, so SciTEGlobal.properties sets the command for compiling .java files to "javac". If I want to use the jvc compiler for the files in one directory, then the SciTE.properties file in that directory contains an entry setting the command to "jvc".

On Windows, the global properties file is located in the directory of the executable. The user properties file is looked for in the user profile directory as set in the USERPROFILE environment variable, or in the directory of the executable if USERPROFILE is not set. For GTK+ the user properties file is found in the user's home directory and the global properties in a directory set at build time - normally /usr/share/scite. If the "SciTE_HOME" environment variable is set on either Windows or GTK+ then it is where both the global and user properties files are found.

There are commands in the Options menu for opening each of the properties files.

The files are in approximately the same format as Java properties files which have a simple text format. Lines that start with '#' or that are completely blank are comments. Other lines are of the form

variable=value

For long values, a '\' character at the end of the line continues that value on the next line. Space characters are significant so x =1 defines a variable called "x ". Values may include the values of other variables by using $(variablename). There are some variables set by the environment to access the name of the current file as well:

Some features use file name patterns to see which variable to use. For example, the lexer variable can be specialised for a particular file, or a group of files based upon wildcard matching so:
lexer.makefile=makefile indicates that the lexer called "makefile" should be used on files called "makefile".
lexer.*.cxx=cpp indicates that the lexer called "cpp" should be used on files with a "cxx" extension.
Variable substitution is available on the left hand side of file pattern assignments and look like this:
file.patterns.html=*.html;*.htm;*.asp;*.shtml
command.go.$(file.patterns.html)=file://$(FilePath)

Wildcard matching only works where the wildcard is at the start of a file specification, so "*.mak" will match "proj.mak" but "Makefile*" will not match "Makefile.in".

Importing properties files and conditional logic

The 'import' statement includes a properties file as if the text were inline at that point. The imported properties file must be in the same directory as the current file and a properties extension is assumed. Therefore a "import Lua" statement in c:\os\scite\bin\SciTEGlobal.properties will import c:\os\scite\bin\Lua.properties.

The 'if' statement takes one argument which is a symbol that may be defined earlier in this property set file or in a base property set. If the symbol evaluates to '0' then the test fails. An empty string or not present symbol evaluates to 0. Into the very top property set is inserted one of 'PLAT_GTK' with value '1' or 'PLAT_WIN' with value '1'. If the test succeeds then following indented statements are executed. When a non-indented statement is found the if clause is finished. Only simple set statements are allowed in if clauses. The evaluation of if statements occurs at read time, not at evaluation time.

Command parameters and prompting

SciTE has 4 properties $(1) .. $(4) which can be used to run commands with changeable parameters. To set the parameter values, use the View | Parameters command to view the modeless Parameters dialog which shows the current values of these parameters and allows setting new values. The accelerator keys for the main window remain active while this dialog is displayed, so it can be used to rapidly run a command several times with different parameters. Alternatively, a command can be made to display the modal Parameters dialog when executed by starting the command with a '*' which is otherwise ignored. If the modeless Parameters dialog is already visible, then the '*' is ignored.

Encodings

SciTE will automatically detect the encoding scheme used for Unicode files that start with a Byte Order Mark (BOM). The UTF-8 and UCS-2 encodings are recognized including both Little Endian and Big Endian variants of UCS-2.

UTF-8 files will also be recognised when they contain a coding cookie on one of the first two lines. A coding cookie looks similar to "coding: utf-8" ("coding" followed by ':' or '=', optional whitespace, optional quote, "utf-8") and is normally contained in a comment:

For other encodings set the code.page and character.set properties.

Defined variables in properties files

Some properties are only available on Windows or GTK+.

caret.policy.{x|y}<param> interaction:

Supporting a new language

For languages very similar to existing supported languages, which may only differ in a minor feature such as the keywords used, the existing lexers can often be reused. The set of keywords can then be changed to suit the new language. Java and JavaScript could have reasonably reused the C++ lexer. The Java lexer was added only to support doc comments.

For languages that can not be lexed with the existing lexers, a new lexer can be coded in C++.  These can either be built into Scintilla, or put into an external module and loaded when SciTE runs (See lexerpath).

The open.filter should be modified to include the file extensions used for the new language and entries added for command.compile, command.build, command.go and command.go.needs for the language.

Creating API files

The .api files can be generated by hand or by using a program. There are also downloadable ready-to-use .api files.

For C/C++ headers, an API file can be generated using ctags and then the tags2api Python script (which assumes C/C++ source) on the tags file to grab complete multiple line function prototypes. Some common headers surround parameter lists with a __P macro and may have comments. The cleanapi utility may be used on these files.

To generate an API file for Python modules, there is a gen_python script.

To generate an API file for Java classes, there is a ApiBuilder.java program.

Open Selected Filename

This command opens the file for the file name selected in either the edit or output pane. It uses the current selection or searches around the caret to try to find a file name based on which characters are normally used in a path. If there is no extension then an extension may be inferred from the current file using the open.suffix property which defaults to .properties in a .properties file. If the file name is followed by a number (in a format similar to ctags, grep output, or Visual Studio messages) then that line is displayed in the opened file. If the file name is an absolute path then it is opened directly otherwise it is looked for in the current directory and then in the directory specified by the openpath property. On Windows, web, ftp, mail and news URLs are handled by opening their associated application.

SciTE in other languages

SciTE can be and has been translated into other languages.

Building SciTE

The procedure for building and installing SciTE is described in the README file in the scite directory.

Extending SciTE

There are two formal extension interfaces for SciTE, the SciTE Extension Interface is for extending SciTE with code compiled into the SciTE executable and the SciTE Director Interface is for manipulating SciTE on Windows from another application.