syn User Manual / 5 Getting Started

5 Getting Started

This section should give you a quick overview of the features from syn, and how to use and configure them.

5.1 Profiles

Figure 1: Compiler output from FreePascal

It is possible to start programs with syn and capture the output when these programs are console programs. This makes it possible to compile a file with a compiler (for an example see Figure 1), or run one with an interpreter, or you can use it to check the syntax of a document, e.g. HTML documents with HTML Tidy¹.

But first you'll have to configure the programs at the syntax highlighting section (8.10) (page profiles) in the Options dialog (8), or at the profiles page (11.3) in the project options dialog (11). Optionally you can use the "Configure" command from the Run menu to show the Configure profiles dialog (Figure 2) for the current language or project.

Programs to run against a certain file are organized in so called profiles. One profile may contain one or more programs, which are executed one after the other, and one language or project may have none or more profiles. The capacity of profiles of a language or project, and the capacity of programs in a profile is in principle unlimited. This is particularly useful when a file is processed by more than only one program, e.g. compiling a source file with a compiler, assembler and linker, or running L^AT_EX, MakeIndex and Bibtex on a L^AT_EX file. The profiles for the languages are saved to the registry, and for the projects to the project file.

syn has no built in debugger, this would be cool, a debugger for about 40 languages ;-), but I've made this profiles stuff as general as possible, so you can run almost every program with it (btw. it's a science of its own to write a debugger, compiler, interpreter etc.).

5.1.1 Configure profiles

Figure 2: Configure profiles

It is possible to configure for each language and project a program or a collection of programs, so called "profiles", which you can start with the "Run File" or "Run project" commands. Each language and project can have as many profiles as you want.

To do so, use for a language profile the Options dialog, syntax highlighting page (8.10), and for project profiles the project Options dialog, profiles page (8.11.3). Alternatively you can use the Configure profiles dialog (Figure 2), you can show this dialog with the "Configure" command in the run file or project submenu.

Profile:: Select the profile to configure.
Programs:: This is the list of programs to call when using the Run file or profile command.The order is the same as in the list.
Program:: Enter here the filename of the program to call.
Arguments:: Optional arguments to pass to the program.
Directory:: Enter here the working directory for the called program.
Output Expression:: A regular expression string to parse the emitted line, more informations can be found in section 5.1.3.
Hidden:: If checked the window of the program is invisible.
Detach:: Uses the flag DETACHED_PROCESS instead of the CREATE_NEW_CONSOLE flag for CreateProcess.
Timeout:: After this time in seconds since the last output from the program it shows a message box to ask you whether to terminate the process or not. Enter 0 for no limit.
Delay:: Time in seconds to wait until it starts this program.
Exit:: Continue running the profile when this program exits with this exit code. Enter -1 to continue anyway. This is useful when you have e.g. a compiler and a linker in a profile and the compilation was not successful, then there is no need to run the linker.

Figure 3: Edit profiles

To add or remove a profile to the language or project use the Edit profiles dialog (Figure 3). You can show this dialog with the profiles (...) button right hand side from the profiles combobox.

5.1.2 Runprofile directive

You can specify the default profile in the file, to do so use the "Run profile" directive. Example, let assume you have a Pascal source file, and a profile for Free Pascal, and you want to make this profile always the default for this file:

{Runprofile=Free Pascal|}
program Untitled;

uses
  Windows,
  SysUtils;
[...]
end.

You see that the Runprofile directive is comment, this is to not confuse the compiler. This file would always use the Free Pascal profile as default profile. The default profile is marked bold in the menu, like in Figure 4, and is used when you use the "Run file" and "Run project" command. To run another profile than the default one use the appropriate menu item. You see this directive is in comments. As last character use | otherwise it reads the profile name to the end of the line, this wouldn't work in this case, because the last character is }, which isn't part of the profile name. It reads this directive always from the currently active document.

Note:: This syntax is case sensitive, the "Runprofile" directive as well as the profile name, in this case "Free Pascal".

Figure 4: Default profile

5.1.3 Output expression

Configuring the output expression will enable you to jump to the emitted error message from a console program (e.g. a compiler) with doubleclicking on an item in the output list. It uses regular expressions to parse the emitted line and to find the filename, line number and/or column number. You can find more informations about regular expressions in section 16. For some examples see Table 1.

Outputline

Output Expression

Examples

file.ext(100)

$[FileName]$$[line number]$

CSL, Delphi

file.ext(100, 21)

$[FileName]$$[line number], $[ColNumber]$

WSH

file.ext(100,21)

$[FileName]$$[line number],$[ColNumber]$

Free Pascal

file.ext:100:

$[FileName]:$[line number]:

JDK, NASM

file.ext 100

$[FileName] $[line number]

Table 1: Output Expressions

Note:: Each bracket and other reserved characters must be escaped with a backslash, as shown in the Table above. For a list of reserved characters see the regular expressions section (16).

The placeholder "$[FileName]" represents either a filename with or without path. The current directory is set to the path of the file to run. If there is no file opened it is set to the project path, so it will be found anyway, even if the outputline contains only the filename without the path. Don't mix up the current directory for this program and the working directory for the called program. Each process can have its own working directory.

5.1.4 Examples

For a step by step example for compiling a Pascal program with the Free Pascal compiler see the How To section in the Questions and Answers document.

Compiling a Java file using Sun's JDK:

The command line can look like this (you have to modify the paths):

javac.exe -O -deprecation -classpath "$[ActiveDocPathShort]\;
d:\programme\jdk1.1.8\lib\classes.zip" -d "$[ActiveDocPathShort]"
"$[ActiveDocLong]"

"$[ActiveDocLong]" represents the filename from the active document in LONG file format. For a description of the switches and parameters see the JDK documentation.

Output line can look like this:

D:\My Documents\HP\chess\chess.java:344: ';' expected.
      c.CurrentY = cm[i].CurrentY
                                 ^

As output expression you should use "$[FileName]:$[linenumber]:"

For the Jikes² Java compiler use as output expression "$[linenumber].", the command line is similar to the JDK Compiler.

Compiling a C(++) file with Borland free C++ Compiler

Here is a brief description how to compile a C++ or C program with syn using BCC 5.5³:

Create a new run profile for the C++ language and enter the following informations, you have to change the paths according to your installation:

program:

D:\BCC55\Bin\bcc32.exe

Arguments:

-ID:\BCC55\Include -LD:\BCC55\Lib -n$[ActiveDocPathShort]

-I: Include paths
-L: Library paths
-n: Output directory

For a more detailed description of the switches and options consult the Manual of the BCC program (bcb5tool.hlp) located in the help subdirectory.

Directory:

D:\BCC55\Bin

Output expression for BCC is a bit tricky, but regular expressions are very powerful. When BCC finds a syntax error -- the example error below is a missing semicolon at the end of a statement -- it may look like this:

Error E2379 D:\My Documents\Delphi Projekte\syn\test\test.c 97:
Statement missing ; in function WinMain

So, use the following expression:

^\w+\s\w+\s$[FileName]\s$[line number]:

^ Beginnig of the line
\w+ Any Character one or more times, e.g. Error, Warning, etc., in this case Error
\s Any Space
\w+\s Same as above, in this case E2379
$[FileName] The filename
\s Another space
$[line number] The line number

When you create now a new program based on the C Console Template, let's call it test.c, it should already compile fine, and you'll get a small console program. It should do nothing more than emitting only:

test.exe usage:

If your C(++) program consists of more than only one source file you should use a Makefile and call the make program with the Makefile, instead of calling the compiler directly.

Validating HTML documents using HTML Tidy

Make a configuration file called config.txt located in the directory from the HTML Tidy program file.

command line (you have to modify the path):

tidy.exe -config config.txt -m $[ActiveDocShort]

The -m Switch is used to get HTML Tidy to update the source file, if you don't want to update the source file, don't use this switch. Use as output expression "line $[linenumber] column $[ColNumber]".

Compiling resource scripts using (Microsoft's) RC.EXE:

command line (you have to modify the path):

RC.EXE /v /i {Some include paths} "$[ActiveDocLong]"

Output expression: "$[FileName]$$[linenumber]$"

Running a batch file which is currently the active document:

Just enter $[ActiveDocShort] as program, and

$[ActiveDocPathShort]

as Directory.

The output window (7.10) with the output list appears everytime when you use one of the run file or run project commands and it will show the output of the called program.

5.1.5 Using environment variables

you may use environment variables in the program, arguments and directory fields. Let's assume you want to compile a resource script with Microsoft RC.EXE, and this file is placed in the directory of Microsoft Visual Studio, then you may use:

%MSDEVDIR%\Bin\Rc.exe

This would translate on my computer into:

D:\programme\Microsoft Visual Studio\Common\MSDev98\Bin\Rc.exe

In the same way you can use it for arguments, e.g.:

/i "%INCLUDE%" /r /v "somefile.rc"

5.1.6 Interacting with the console

If you've launched a program in this way the output list will appear, and there is a text box while this program is running where you can enter commands which are sent -- i.e. written to StdIn -- to the console program. This text box is only visible when the program is running. This text box has also a popup menu with some useful commands; you can e.g. save the list, load a list etc.

5.2 Variables

A description of variables which can be used at some places.

5.2.1 Run

This is a list of all variables which you can use in the command line from Run/Check and the tools, but you can also use the popup menu to insert these variables, see Table 2 for some examples:

$[ProjectPathShort]:: Short path name from the currently opened project.
$[ProjectPathLong]:: Long path name from the currently opened project.
$[ProjectFileShort]:: Short filename from the currently opened project.
$[ProjectFileLong]:: Long filename from the currently opened project.
$[ActiveDocShort]:: Short filename from the active document.
$[ActiveDocLong]:: Long filename from the active document.
$[ActiveDocShortNoExt]:: Short filename from the active document without the fileextension.
$[ActiveDocLongNoExt]:: Long filename from the active document without the fileextension.
$[ActiveDocTitleShort]:: Short filename from the active document without the path.
$[ActiveDocTitleLong]:: Long filename from the active document without the path.
$[ActiveDocTitleShortNoExt]:: Short filename from the active document without the path and the file extension.
$[ActiveDocTitleLong]:: Long filename from the active document without the path and the file extension.
$[ActiveDocPathShort]:: Short path to the active document.
$[ActiveDocPathLong]:: Long path to the active document.
$[ActiveDocExt]:: Returns the extension from the active document.
$[FileNameShort:?0]:: Shows the open dialog to choose a filename.
$[FileNameLong:?0]:: Same as above, but it does not convert it into a short filename.
$[ModFiles]:: Returns all modified files separated with a space.
$[CurWord]:: Returns the word under the caret.
$[Prompt:0]:: Prompts you to enter a word.
$[ProgramPathShort]:: Short path to the program.
$[ProgramPathLong]:: Long path to the program.

System directories:

$[WinDirShort]:: Windows directory.
$[SysDirShort]:: System directory.
$[TempDirShort]:: Temporary directory.

Variable

Input

Result

$[projectPathShort]

C:\mydirectory\myproj.syp

C:\mydire~1

$[projectPathLong]

C:\mydirectory\myproj.syp

C:\mydirectory

$[projectFileShort]

C:\mydirectory\myproj.syp

C:\mydire~1\myproj.syp

$[projectFileLong]

C:\mydirectory\myproj.syp

$[ActiveDocShort]

C:\mydir\myfilename.html

C:\mydir\myfile~1.htm

$[ActiveDocLong]

C:\mydir\myfilename.html

$[ActiveDocShortNoExt]

C:\mydir\myfilename.html

C:\mydir\myfile~1

$[ActiveDocLongNoExt]

C:\mydir\myfilename.html

C:\mydir\myfilename

$[ActiveDocTitleShort]

C:\mydir\myfilename.html

myfile~1.htm

$[ActiveDocTitleLong]

C:\mydir\myfilename.html

myfilename.html

$[ActiveDocTitleShortNoExt]

C:\mydir\myfilename.html

myfile~1

$[ActiveDocTitleLongNoExt]

C:\mydir\myfilename.html

myfilename

$[ActiveDocPathShort]

C:\mydirectory\myfile.html

C:\mydire~1

$[ActiveDocPathLong]

C:\mydirectory\myfile.html

C:\mydirectory

$[ActiveDocExt]

C:\mydirectory\myfile.html

html

$[programPathShort]

C:\programdir\myprog.exe

C:\progra~1

$[programPathLong]

C:\programdir\myprog.exe

C:\programdir

$[WinDirShort]

C:\WinNT

$[SysDirShort]

C:\WinNT\system32

$[TempDirShort]

C:\Temp

Table 2: Variable Examples

All directories are returned without trailing backslash, because it's much easier to add one, than to remove one.

5.2.2 Insert string

A list of variables which can be used with the Insert String (5.5.3) tools in the text.

{$Sel}:: Variable for the current selection.
{$DateTime}:: Variable for the current date and/or time, it uses the format defined in the options dialog, page general (8.1).
{$File:<filename>}:: Inserts the contents of the file with the name <filename>.

5.3 Using syn as console window

You can syn use as a console window, and benefit from all additional features syn offers, like autocomplete, syntax highlighting etc. To start an editor window in this mode open a file with <file_name>.RUN.<file_ext> in the filename. This filename must contain informations about the program to use, the current directory of this program and the exit command. To use it instead of the command propmt the file should look like as follows, see also DosConsole.RUN.BAT:

REM CmdLine: %COMSPEC%
REM CurDir: C:\
REM ExitCommand: exit
REM PrintInput: 0
REM ToOutput: 0
REM AskSaveFile: 0
REM ShowWindow: 0
REM DetachedProc: 0

CmdLine:

The command line to execute, may have additional arguments, and may contain environment variables.

CurDir:

The working directory for this program.

ExitCommand:

The command to exit this program. If you enter this command in the Editor the Editor window will also close.

PrintInput:

Could be 1 or two, test what works best, default is 0.

ToOutput:

If 1 the Output from the console program is written to the output list, and not to the same editor window. This way you will be able to make .BAT files interactively, typing every command and seeing immediatly its result in output window. Default is 0.

AskSaveFile:

If 1 it will ask you to save the file when closing it, default is 0.

ShowWindow:

Specifies how the window should be shown. Possible values are:

0: The Window is normally shown
1: The Window is hidden
2: The Window is maximized
3: The Window is minimized

DetachedProc:

Ahem, ok here is what the helpfile says: For console processes, the new process does not have access to the console of the parent process. The new process can call the AllocConsole function at a later time to create a new console. This flag cannot be used with the CREATE_NEW_CONSOLE flag. If 1 it uses this flag DETACHED_PROCESS instead of CREATE_NEW_CONSOLE in CreateProcess. We introduced this property, because R runs only with this set to 1. We think Emacs does the same.

Send:

Any number of lines to send to the console when starting it. Each line should appear in a separate line of the template and should have the Send: prefix.

See also the file DiskPart.RUN.txt and Rterm.RUN.r in the templates\Console directory. It is useful to save such a file with the extension from the Highlighter you want to use, e.g. if I want to run R, I want to use the R Highlighter, and thus it is saved as *.r. Before you open the Rterm.RUN.r you must modify the path to the Rterm.exe program. To easily start such a new session use the "New" dialog, there is a "Console" tab with some files.

Figure 5 shows a sample session with the DosConsole.RUN.BAT template.

Figure 5: DosConsole.RUN.BAT Sample session

For each entered command it creates a marker, and adds the command to a recent list, so you can easily jump to previous commands and/or quickly reenter a command. It does not create a marker when ToOutput is 1, because this wouldn't be very useful, you would have in each line a marker. You can show this recent list with the hotkey Ctrl+Enter. If the caret is somewhere in the editor a return will bring it to the last line.

To pause this execution use the Console execution menu in the run menu. The default shortcut for this button is F2, but you can assign another one if you wish. In that mode editing of whole text is as usual, and pressing enter works like in any other editor. This could be very useful if you want to add one more console option in the beginning, change current, or edit interactively made *.bat file.

If you've created such a "RUN" template, and you think this could be useful for other users of syn you should send it to the syn resource mailing list.

Note:: If you want to start a GUI program, such as NotePad with the DosConsole.RUN.BAT file it may hung, or you must enter some more returns. We're working on it. In the meanwhile you could start the program with the start command, e.g. start notepad, which is AFAIK the usual way to start a GUI program from a console.

5.4 Delphi Form files

Delphi form files⁴ are displayed as text files, even if it's a binary file. If it is a binary file it will be automatically converted, so you can read it. When you've opened such a file, and you save it, it will be converted back into a binary file. You won't see whether it's a text file or a binary file.

5.5 Tools

It's possible to have custom tools, which you can call via the tools toolbar, the tools menu or a hotkey. You can either launch a program, execute an edit command, insert a string or execute a DOS command with a tool. You can assign a shortcut to each tool (generally to each toolbar item and menu item) with the customize dialog. There is no built-in limit how many tools you can have, but the more tools you have the slower will be the whole program (depending on your computer). The project tools (5.6) are similar to the tools, which you can configure in the options dialog, except you can't assign a shortcut, and there is no corresponding menu.

To configure these tools use the "Configure tools" dialog (Figure 33), you can show it with the "Configure" menu item in the tools menu. This dialog is described in section 12.4.

5.5.1 Launch a program

Use "Launch program" as toolkind, choose the program, and the working directory for this program. You can redirect the output from console programs to syn like for the Run and Check (5.1) commands, just activate "Capture Console". There is no possibility to enter a compiler message, so you can't jump to the line with a doubleclick in the list. The file need not be a program, you can use this method to start any file (e.g. Help files, documents etc.) with its default program, as well, but if you do so, you shouldn't check "Capture Console". For starting the active document with the associated program enter as filename the variable for the active document: "$[ActiveDocShort]". For a complete list of appropriate variables for this kind of tools and "Execute DOS Command"-tools see section 5.2.1. You should enclose the program name in quotes when the filename contains spaces, or use the short filename.

5.5.2 Execute an edit command

Use "Execute Editcommand" as toolkind, and choose from the dropdown combobox the edit command which you want to execute with this tool.

5.5.3 Insert a string

The string to insert can be a singleline or a multiline string. As variable for the currently selected text use {$Sel}. You can use the "Selection" button to insert this variable at the current caret position. Use "Insert String" as toolkind, and enter the text to insert in the text box below.

Example for inserting C/Java brackets:

{
  {$Sel}
}

Example for inserting HTML comments:

<!-- {$Sel} -->

Use {$DateTime} for the current date and/or time. It is formatted according to your settings for date/time format in the options dialog, page "General" (8.1).

You can use the {$File:filename} variable to insert the contents of a file, you must replace "filename" with the name of the file to insert. It is only useful to insert text files of course, but you know this. For a complete list of these variables see section 5.2.2.

5.5.4 Execute a DOS command

Use "DOS Command" as toolkind, and enter the command to execute in the text box below. You can pass the usual variables like for launching a program, but the variable "programpath" will return either the program path from "cmd.exe" (WinNT) or the path to "Command.com" (Win9x), depending on what the environment variable "COMSPEC" returns. Maybe this is useful for some file operations like backup files etc. If you have more than one command, you should use a batch file and start it with a tool.
Example for making a backup from the active document with the extension BAK:

copy $[ActiveDocShort] $[ActiveDocShortNoExt].bak

$[ActiveDocShort]:: Returns the filename from the active document.
$[ActiveDocShortNoExt]:: Returns the filename from the active document without the file extension.

Optionally you can enter a working directory, which is not necessary in this case, because the variables returns absolute paths.

If you use "Hidden" no DOS box is shown. If you start a program in this way the DOS box remains open until the called program is closed. You can hide it with the Hidden checkbox but it is still there.

It uses the program which returns the environment variable "COMSPEC" e.g. command.com (Win9x) or cmd.exe (WinNT) as batch interpreter. If you're using an other batch interpreter, e.g. 4NT, then you'll need to update this environment variable to the filename of the interpreter, or replace cmd.exe or command.com with the other interpreter.

5.6 Projects

Projects are saved as ordinary ini files, but with the extension "syp". You can read and modify them with any text editor. You should know what you're doing when you modify such a file manually, of course. If you have used the installer, *.syp files are associated with syn, so you can open such files with a doubleclick in the explorer. You can also drag a project file from the explorer and drop it into the program to open it. As any INI file it shouldn't exceed the 64 KB limit as well; everything exceeding this limit is truncated. Anyway, it will have to be a very large project to exceed this limit.
The filenames are saved with relative paths, i.e. when you move a project file without all its members to another folder the program will not find the files. You have to remove all files and add it again to the project.

For information about project tools, see section 11.4

5.7 Monitor for external changes

This program is able to monitor opened files for changes made by an external program (default is disabled). The program compares the last write date to detect whether the file has changed or not, not the string inside or the filesize. This means, you can save a file with another program without changes, and syn will do the requested action. This should be the way to notice the most changes, because you can have different files with exactly the same size, and comparing the content will take too much time and resources (the program must open the file, read the content, and compare it). The program uses the "FindFirstChangeNotification" et al. API functions in an external thread to detect changes in the directory of an opened document, and compares then the file dates. This thread isn't created when you've deactivated this feature. You have three options for what this program should do in such a case:

Notify only: the program shows only a message.
Prompt to reload: the program asks you if the file should be reloaded, to get the newest version.
Note: all unsaved changes will be lost if you reload the file. On the other hand, if you save it before reloading, the modifications from the external program will be lost.
Reload without prompting: the program reloads the file without asking you anything, be careful with this, you might be scared in such a case ;-).

The status is displayed in the status bar (7.12).

5.8 Limit to one instance

If this option is activated, and you want to launch a second instance of syn, the parameters passed to this second instance will be processed by the first instance, and the second one terminates itself. This means you're not able to run syn more than only once. This can be useful in some cases, especially when you're using the SynTray (18) program. This option is activated by default, because some features rely on it, but there will be no trouble if you deactivate it. This is possible at the General page (8.1) in the Options dialog.

5.9 Generating PDF Files

There are no plans to add an exporter for PDF (Portable Document Format) files in the near future, but you can do it with a small workaround: There is a freewaretool which converts HTML files into PDF files called HTMLDOC⁵. So you can export the file to a HTML file (which is supported by syn) and convert it with HTMLDOC into a PDF file, looks pretty cool. HTMLDOC supports most, or even all (?), of the HTML 3.2 tags, some of the HTML4.0 ones and no CSS.

We know there is a Unit for Delphi and Pascal, which can write PDF files natively, but the file size of syn would increase dramatically, and the Acrobat Reader says for all files Stefan had generated with this unit, that it is corrupt.

If you have Acrobat installed, you can use the Acrobat Distiller printer driver directly from syn ("File" ® "Print...") as you would do with each other program. You can also print to a Post Script Printer⁶, and then convert it with GhostScript⁷ to PDF, which is completely free, and looks also quite good.

Another mean (easier and cheaper, IMO) is to use OpenOffice.org 1.1⁸, which does that almost well and at the price of a Lighter GNU license...

5.10 The custom highlighter

There is one highlighter you can use for a custom syntax highlighting, and it's called "custom highlighter". You can use it as an usual highlighter, but the definitions comes from a file, which must be called "synhigh.ini" and be located in the application path. You can read and write such files with any text editor like notepad, or even syn.
Beside a list of keywords you can also define a list of constants and objects that can have their own highlighting attributes.

5.10.1 File format

[General]
; The Name of the language
LangName=SomeName

; Use this section to define the style for Comments, use "true" or
; "false" for matching items, default is false.
[CommentStyle]
; ANSI styled comment: (*comment*)
ansi=false
; ASM styled comment: ;comment
asm=false
; Bas styled comment
bas=false
; C(++) styled comment: /*comment*/
c=false
; Pascal styled comment: {comment}
pas=false
; Visual Basic styled comment: 'comment
vb=false
; Perl styled comment: #comment
perl=false

; Delimiter in which strings are enclosed, this can either be a single
; quotemark ('), a double quotemark (") or both. Use true for matching
; items.
[String Delimiter]
Double Quotes=true
Single Quotes=false

[Switches]
markup=false
; When markup is true, words between < and > will be highlighted.
; You can use this for markup languages like HTML, XML and XSLT
entity=false
; When Entity is true entity symbols like &amp; will be highlighted.
; You can use this for e.g. HTML and XML highlighting.
dollarvariables=false
; When DollarVariables is true symbols preceeded by the sign will be
; highlighted using the VariableAttri settings. You can use this for
; variable highlighting in languages like php and perl
ActiveDot=false
; When ActiveDot is true properties and methods of objects after the dot
; are highlighted, e.g. myobject.method

; List all Objects here
[Objects]
object1
object2
...

; All Constants goes here
[Constants]
constant1
constant2
...

; Enter here all Keywords
[Keywords]
key1
key2
...

That's all. Settings for this highlighter are saved to the registry as usual, and not to this file. You can setup the colors, styles and associated filetypes in the options dialog.

The program loads this file at startup. If you've changed it, you'll need to restart the program to see the changes.

5.11 Autocomplete

This program offers a feature to complete code fragments by using a hotkey. The information about how to complete the code comes from a file, which you have to configure in the options dialog " syntax highlighting " autocomplete (8.11.2). You can edit these templates in the options dialog, or you can use a text editor.

You can define the hotkey to activate autocomplete in the shortcuts page of the options dialog (8.16).The entry is named ecAutoCompletion (default is Ctrl+J, but we prefer Ctrl+Space in this case⁹).

The file format is the same as Delphi uses for this feature, it's an ordinary text file. If you have Delphi, and you've your own file made for Delphi, you can just assign this file instead of the shipped file. You can also use the "bsb.dci" file from C++ Builder for the C++ language, it's the same file format. This file can be found in Borland\CBuilder4\bin, delphi32.dci can be found at Borland\Delphi5\bin, depending on the version you're using.

5.11.1 Example for Object Pascal

// will insert an Array declaration when
[arrayd | array declaration (var)]
// you enter "arrayd" and then hit the Hotkey
array[0..|] of ;

// will insert a case Statement when you
[cases | case statement]
// enter "cases" and hit the hotkey.
case | of
  : ;
  : ;
end;

The first line enclosed in brackets is not inserted, this line is used to identify the code. The first part is the short form and will appear in the "Name" column in the list from the Options dialog. The second part behind the "|" character is a short description of this code shown in the "Description" column in the list. You can make or edit such a file with any text editor (e.g. Notepad) but it is probably easier for you to use the options dialog (8). It's possible to edit this file "visually" at the syntax highlight page (8.11.2), see Figure 22.

Note:: You can't use the combination "[|]" in the code section, because the program will think this is a header line from a code section. It will tell you that this is an invalid fileformat, and maybe some more errors.

The Caret will be placed where the "|" character is in the code.

Example: If you have a Pascal document and you have assigned "pascal.dci" as autocomplete file in the Options dialog then enter e.g.:

cases

into the editor, hit the hotkey, and you'll get:

case | of
  : ;
  : ;
end;

The "cases" will be replaced with the case statement.

Changes will only affect newly opened files, not already loaded files. You have to use a highlighter in order to use this feature, it's not possible to use it, when no highlighter is assigned. The autocomplete files shipped with the setup program will be assigned during install to the highlighter. This can be done for each syntax scheme available, it's not limited to ObjectPascal and HTML. The program will load this file when the highlighter is assigned to the document, e.g. due to loading or saving a document, or switching between the highlighters. If you've created such a file, or more of them for a language, and you want to make them available for all users, send it by mail to the syn resource mailing list. We recommend you to make the autocomplete list not too large because this may slow some processes. Our opinion is to only add the most frequently used code snippets, but this is completely up to you and your computer, there is no built-in limit.

5.11.2 Popup list

If the insertion from a code template fails for some reason, e.g. you haven't entered a token, or it doesn't find a matching token, it will show a popup list with all the code templates for the current language. You can choose from this list a template and insert it with a double click on the item in the list, or with hitting the Enter key. To hide the list use the Escape (Esc) key. The autocomplete list shows the short form right aligned and bold, the description is left aligned, it is very similar to Delphi. This list is not sorted, you can make an order of your choice in the file.

This list has also a quicksearch, like any usual list box and other similar Controls (listview, treeview etc.), but it doesn't search for the description, but for the label (the right aligned part from a list item). For example, you hit the key "C" on the list, the next item with the label starting with a "C" will be selected. If it can't find any more labels beginning with a "C", it will start searching from the begin.

Figure 6: Autocomplete List

5.12 Edit commands

Some commands to edit the selected text or the entire document.

5.12.1 Uncategorized commands

Undo:: The Undo command reverses whatever you just did concerning the editor. When Undo is disabled, it is an indication that nothing needs to be undone or you cannot undo the last action.
Redo:: If you undo a little too much, choose Redo to un-undo!
Cut:: This command cuts the currently selected text to the clipboard.
Append Cut:: Cuts the selection and appends it to the clipboard.
Copy:: Copies the selected text to the clipboard.
Append Copy:: Copies the selected text and appends it to the clipboard.
Paste:: Choosing this command copies the clipboard contents at the cursor, or replaces the selected text with the clipboard contents.
Delete:: The delete command clears the selected text from the active document or it removes the selected item of the File View.
Select All:: This command selects everything in the active document.
Check Spelling:: Checks the active document for spelling errors.
Insert Date/Time:: Inserts the current date and/or time at the caret position, to setup the format use the Options dialog, General page (8.1).
Insert File:: Inserts the contents of a file into the active document, at the current caret position.
Modified:: Toggles the modified status of the active document.
Read only:: Toggles the read only status of the active document on and off (Read Only is displayed in the status bar). A read only document cannot be modified.

5.12.2 Format commands

Commands to format the entire document.

Tabs to Space:: Replaces the tabs in the entire document with the specified count of spaces.
Space to Tabs:: Replaces the specified count of spaces in the entire document with tabs.
Leading Tabs to Space:: Replaces all tabs at the begin of a line with spaces in the entire document.
Leading Space to Tabs:: Replaces all spaces at the begin of a line with tabs in the entire document.
OEM to Ansi:: Translates the entire document from the OEM character set into the ANSI character set. It's not possible to undo this command, use the Ansi to OEM command instead.
Ansi to OEM:: Translates the entire document from the ANSI character set into the OEM (original equipment manufacturer) character set. It's not possible to undo this command, use the OEM to Ansi command instead.
Encoding:: Allows to convert the active document to different codepages.
Trim trailing Spaces:: Removes all spaces at the end of a line in the entire document.

5.12.3 Change case

Commands for changing the case from the Selection.

Upper Case:: Changes the letters from the selection into upper case.
Lower Case:: Changes the letters from the selection into lower case.
Invert Case:: Inverts the case from the selection.
Capitalize:: The first letter from each word is upper case, all other letters are lower case.
Sentensize:: The first letter from each sentence is upper case, all other letters are lower case. it looks for a punctuation mark (.?!;: etc.) and then for a whitespace (e.g. tab, space), i.e. there must be a whitespace after the punctuation mark.

5.12.4 Block commands

Commands for editing the selected Block.

Increase Indent:: Increases the indentation from the selected line(s).
Decrease Indent:: Decreases the Indentation from the selected line(s).
Comment:: Comments the selected block according the Syntaxsheme. Select the Comment Character and Style in the Options dialog, Page syntax highlighting (8.11.1). Use for the selected text the "|" Character. If there is such a character the program handles it as multiline comment, if it's not a multiline comment (like in VB, "'") use not this Character.
Uncomment:: Uncomments the selected block according the Syntaxsheme. It uses the same settings as for the "Comment" command described above.
Sort:: Sorts the selected lined lines alphabetically.
Save:: Saves the selected Block to a file.

5.12.5 Advanced

Some advanced edit commands, sometimes useful but not often used.

Delete lines:: Deletes the whole lines beginning where the selection block begins, and ending where the selection block ends.
Delete to BOL:: Deletes the text from the text caret to the beginnig of the line (BOL).
Delete to EOL:: Deletes the text from the text caret to the end of the line without the line break (EOL).
Delete word:: Deletes the whole word under the text caret.
Select line:: Selects the whole line (with the line break) where the text caret is.
Select to BOL:: Selects the text from the text caret to the beginning of the line (BOL).
Select to EOL:: Select the text from the text caret to the end of the line without the Linebreak(EOL).
Select word:: Selects the whole word under the text caret.
Join lines:: Writes the selected lines into one line (it removes the line breaks).
Split line:: Breaks the line at the caret position without indenting.
Duplicate lines:: Duplicates the line where the text caret is, and inserts it as the next line.
Format lines:: Breaks the line at right edge.

5.13 Search commands

As already mentioned offers syn some powerful search commands, like Find in Files (5.13.4), incremental search (5.13.3), find next/previous word (could be many) (5.13.2) etc. Here is a more or less detailed explanation of this commands.

5.13.1 Find

The find command shows the search text dialog (Figure 7), in which you can enter a text you want to search for. Press Enter to search the active document for the specified string.
If there is a selected text before you open the Search dialog, the selection becomes the search field. When there are more lines selected, nothing is in the find text field, but the checkbox "Selected text only" is selected.

If you activate "Mark all matches" it sets a marker for each match, and doesn't highlight the match. You can then jump to the match with a double click in the marker list or with the marker context menu.

Figure 7: Search text dialog

5.13.2 Find next/previous word

Searches for a next or previous match from the currently selected text, without the need to open the Search text dialog and entering some text.

5.13.3 Incremental search

The incremental search functions search for a text while you are typing it into the editor. You can see the current search string in the editor status bar panel, see section 7.12 for more information about the status bar. A matching string is selected in the editor. To exit the incremental search mode hit Escape (Esc) or Enter.

To switch to the search mode use either the "Incremental Search forward" or the "Incremental Search backward" menu item in the search menu, depending in which direction you want to search.

5.13.4 Find in Files

It is possible to search for a string in multiple files. To do so, use the "Find in Files" menu item in the "Search" menu. A dialog (Figure 8) will appears where you should enter the search criteria. After clicking "Find" the output window (Figure 9) will show up, and all matches are written to the list. To jump to the match just double click on the item in the list. This will open or activate the file and place the caret in the line where the match was found.

It is also possible to replace occurrences of the search string with another string. If you replace text binary files are automatically skipped, because it can't correctly replace text in binary files. Before you replace text in files you should make a backup copy of these files. If you want to list only all files in a certain directory, which matches the file mask, then leave the "Find what" field empty. See also section 19.

Figure 8: Find in Files dialog

This tool also supports regular expressions. To learn more about regular expressions see 16. To use regular expressions check the checkbox "Regular Expression".

If you check "Output in Pane 2", matches are written to the second list ("Find in Files 2") rather than in "Find in Files 1".

In the "Scope" block you can choose where and which files should be searched.
Check "Search in Folder" to search the folder in the "In Folder" field.
Check "Look in Subfolders" to search all subfolders.
"All open Files" searches all files which are currently opened, and "All projectfiles" searches all files in the opened project. The file filter is also used for this files, e.g. if the file filter is "*.htm", only HTM files from your project or open files will be searched. To search in all files use "*.*" as a filter.

Figure 9: Find in Files Search Results

5.13.5 Replace

This command shows the replace text dialog (Figure 10) where you can enter the text to be replaced, and the text to replace with. If you use "OK" you'll see the Confirm Replace dialog (Figure 35), which asks you whether you're sure every time it finds a match. If you use "Replace all" every found match will be replaced without asking you anything. If you have activated "Report Count" it tells you how many occurrences have been replaced.

You may also use escape sequences (17) for replace text, such as \n, \t, \f, \r, to replace some text with such a non printable character.

Figure 10: Replace text dialog

5.13.6 Go to

Shows the Go to dialog (Figure 11). You can jump with it easily to a line or column number or a bookmark, if any set. The cursor is displayed at the specified line, column number or bookmark. It is also able to parse the output of a program started with the Run command, based on the output expression, or a Find in Files search result. If you choose such an item, you can open this file and jump to the line and column position.

Figure 11: Goto dialog

5.13.7 Goto previous/next Output Item

Goes to the next or previous item in the output or Find in Files list. This is useful if the output is a mess, and it's not easy to identify a line which matches the output expression, e.g. like LaTeX output. It uses the currently selected item in the list and iterated through the rest to find such a match. If it finds a matching item it selects it in the output or Find in Files list.

5.13.8 Go to last change

The cursor is moved to the line were you made the last change to the text. This may be useful when you have a large document, and you scrolled to anywhere just for looking, and want to jump now back.

5.13.9 Show caret

Scrolls the editor to bring the caret into view.

5.14 Using ctags

syn directly supports the ctags program to obtain a list of functions, procedures and other declarations from the active document. This program is not included in the distribution of syn, you may need to download it from http://ctags.sourceforge.net/ . Once downloaded, put the ctags.exe into the directory of syn, or make an environment variable named CTAGSBIN which points to the location of the ctags executeable. Now it should call this program automatically, and fill a combobox with all found contents in a toolbar.

ctags runs in a separate thread with idle (lowest) priority, this makes it possible that you don't need to wait until the file is parsed, but it will also be slower, and may take some time on large files. You shouldn't even notice the program is running in the background, because this way it does not consume much system resources. Ctags is called everytime an editor gets activated or a file saved.

You may pass for each language individual options to the ctags program, e.g. --sort=no would be useful for certain languages, see how in section 8.11.5 . What options this could be see the ctags documentation.

5.15 Calling a help file depending on the syntax scheme

You can call different help files depending on the selected syntax scheme. To do so assign any help file in the Options dialog (Highlighters page, 8.11.4) and hit the F1 key in the editor. To change the hotkey to another one, use the Options dialog, Shortcuts (8.16), and modify the command "ecContextHelp".

This will launch the help file, and if it is a *.hlp or a *.chm File it will search the word under the caret in the index and shows the topic when it's found. If there is no word under the caret it will show the contents page from the help file.

If you don't want to search the token under the caret in the index, but call a specific topic for a specific word, you can make a table on which token which topic should appear. Open the Options dialog, go to the Highlighters page (8.11.4), choose help, and enter in the "Map Table" list the associations. In the first column goes the word, in the second the topic ID.
Sure, this makes only sense, when you know the topic IDs for the different topics. This works for *.hlp and *.chm files only.

If it's not a *.hlp or a *.chm file it will just use the ShellExecute API function to show the file with the default program, e.g. the browser for HTML files.

5.16 FTP

You can open and save files directly from a FTP server, if you wish to do so use the commands "Open from FTP" and "Save to FTP" in the "File" menu. After using one of this commands a dialog (Figure 12) will appear where you'll have to enter your login data and some other stuff.

Figure 12: Save to FTP dialog

If you open or save a file this way the settings are saved to the registry, and you can use them the next time without entering them again. To edit this settings use the Options dialog, page FTP Server (8.8). The program will show a window during the upload or download process to indicate that it is currently discussing with the server. The downloading process is not asynchronous, this means the program is blocked this time, and you can't use it.

Warning:: The passwords are saved to the registry using a simple encryption algorithm. To prevent saving the password to the registry, uncheck "Save password" (default).

To open a file from a subdirectory on the server, enter in the File field the filename with the subdirectory, e.g. "subdir/file.txt". If you want to open a file in the root directory, it is possible that you will have to enter a leading slash before the filename, e.g. "/index.htm".

When you upload a file, the file in the editor will be saved as a temporary file in the Temp directory ({temp}\synupload.tmp), and the program will upload this file, this means, you need not save the file before locally. This file will be deleted after the uploading process.

If you're transferring text files between Unix and Windows using FTP be sure to transfer them in ASCII mode so the ends of lines are appropriately converted.

To browse on the FTP server for a file use the "Browse" button (...) from this dialog. This button shows a Browse dialog (Figure 13) similar to the Open/Save dialogs from Windows. You can create directories, delete and rename files, or just select a file. It is not possible to delete or rename a directory; for advanced FTP commands use a FTP Client, or, if you're familiar with the FTP Commands, use Send command. You can send any command to the FTP server. If you add or remove a file/directory, you'll have to refresh the list, to see the changes (context menu from the list, "Refresh", or F5).

Figure 13: FTP Browse dialog

The program stays connected to the FTP server during browsing, but it logs out after uploading or downloading a file. This should make browsing much faster, and it's not desirable to stay connected after uploading or downloading a file. Staying connected would cause some other problems too, e.g. the FTP server logs you automatically out after a specific time of inactivity, the program has to send a command (NOOP) to prevent this, not every server accepts this command and this don't works for an unlimited time, etc. When you're connected with the Browse dialog, and you're not using it for a long time, you may also be disconnected, which will give you an error message, when you try to access the server again. You can use the "Reconnect" Command (F3 or popup menu) in such a case to connect to the server again.

5.17 File Explorer

The File Explorer is similar to the folder tree in the Windows Explorer, with the difference that this one shows not only the folders but the files as well. This has the advantage that there is no need for an additional list for the files.

The File Explorer is initially invisible, this means when you start syn the first time you can't see it. To show it use the "File Explorer" menu item in the View menu (6.4) (submenu Toolbars).

Note:: Showing the File Explorer will slowdown the startup process from the program, because there are some file operations involved.

The File Explorer is set initially the current directory from syn; if you want to have another directory, change the working directory at startup. To change the working directory you'll need to launch syn from a link.

The File Explorer does not notice changes, e.g. deletion or creation of files. You can update the Explorer with the F5 key, or with the "Refresh" menu item in the popup menu. You can change this shortcut in the Customize dialog ("Keyboard","View","Refresh").

To open a file from the File Explorer just double click with the mouse on it, or use the popup menu, it appears when you rightclick on a file or directory. You can also select a file and hit then Enter. It is not possible to select many files, and open them at once.

5.18 Bookmark Files

syn saves by default caret position, marker and selection of a document before you close this document, and restores it when you load this document again. These datas are stored in a file, which have the extension .sbm and are hidden by default. You can disable this behaviour in the Options dialog (8),General (8.1). If you don't want to save such a file when closing a document, then hold the keys CTRL and SHIFT down.

This file is not created, or it is deleted when one exists when there are no bookmark set and the caret is in the first line and the first column, i.e. the default values.

1: HTML Tidy is a program to validate HTML Documents, you can download it at: http://www.w3.org/People/Raggett/tidy/.
2: Jikes is a Java Compiler from IBM, it's free and you can download it from http://www10.software.ibm.com/developerworks/project/showfiles.php?group_id=10.
3: Borland has released their excellent C++ compiler C++Builder 5.5 for free, you can download it from http://www.borland.com/products/downloads/download_cbuilder.html.
4: Delphi Form files are either saved as Binary- or textfiles, and they have the file extension DFM.
5: HTMLDOC is a free Tool, covered under the GPL, for converting HTML files into Acrobats Portable Document Format (PDF) or to PostScript Files (PS), you can download it at: http://www.easysw.com/htmldoc/.
6: You can use from HP a PostScript Printertdriver, take for Windows NT and 2000 http://www.hp.com/cposupport/printers/software/lj485en.exe.html, and for Windows 95 and 98 http://www.hp.com/cposupport/printers/software/lj477en.exe.html. These are drivers for HP color laserjet 4500, which seems to work well with GhostScript.
7: You can download it from ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/AFPL.
8: You can see here to get information and download : http://www.openoffice.org/
9: Ctrl+Space is usually the hotkey for code completion, hence syn doesn't support any intelligent kind of code completion, syn uses this hotkey for the autocompletionfeature (Space is easier to find than J).