Using annotate
Of course it's perfectly valid to use any editor you wish to edit your source-code. Maybe you have your favorite editor, or simply dislike fp-ide (which comes with syntax highlighting, compiles out of the box after proper configuration and that supports for help files, help can be found on keywords under cursor and keywords can be auto-completed).
But alas, there are not many syntax highlighting editors available for AROS (that also supports or has the ability to support pascal syntax highlighting). The only other editor i am aware of that could pull that off is vim. And although this editor originates from classic amiga OS, i actually never learned to work with that editor.
Another alternative that can be used is the Annotate editor that is developed by OnyxSoft. Icaros installation has this editor installed by default, and in case your installation contains an older version then please make sure to update your installed version with the one available on OnyxSoft's website (as there are some incompatibilities between different versions of Annotate due to some new features/bugfixes).
Annotate's syntax file
here is the syntax file that i imported in Annotate to get pascal syntax highlighting working:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE Ann-SyntaxHighlighting>
<!-- There are 5 special characters that need to be codes: -->
<!-- & - & < - < > - > " - " ' - ' -->
<Ann-SyntaxHighlighting>
<Syntax>
<Name>Pascal</Name>
<Qualifying>
<OrTokens caseinsensitive="1">program unit </OrTokens>
<FilePattern>#?.(dpr|pas|lpr|pp)</FilePattern>
</Qualifying>
<!-- Actually, the nr of tokens should be slightly less -->
<Tokens>260</Tokens>
<!-- Keywords -->
<Token pen="210" style="bold" caseinsensitive="1">absolute</Token>
<Token pen="210" style="bold" caseinsensitive="1">abstract</Token>
<Token pen="210" style="bold" caseinsensitive="1">and</Token>
<Token pen="210" style="bold" caseinsensitive="1">array</Token>
<Token pen="210" style="bold" caseinsensitive="1">as</Token>
<Token pen="210" style="bold" caseinsensitive="1">begin</Token>
<Token pen="210" style="bold" caseinsensitive="1">break</Token>
<Token pen="210" style="bold" caseinsensitive="1">case</Token>
<Token pen="210" style="bold" caseinsensitive="1">class</Token>
<Token pen="210" style="bold" caseinsensitive="1">const</Token>
<Token pen="210" style="bold" caseinsensitive="1">constructor</Token>
<Token pen="210" style="bold" caseinsensitive="1">continue</Token>
<Token pen="210" style="bold" caseinsensitive="1">destructor</Token>
<Token pen="210" style="bold" caseinsensitive="1">dispose</Token>
<Token pen="210" style="bold" caseinsensitive="1">div</Token>
<Token pen="210" style="bold" caseinsensitive="1">do</Token>
<Token pen="210" style="bold" caseinsensitive="1">downto</Token>
<Token pen="210" style="bold" caseinsensitive="1">else</Token>
<Token pen="210" style="bold" caseinsensitive="1">end</Token>
<Token pen="210" style="bold" caseinsensitive="1">except</Token>
<Token pen="210" style="bold" caseinsensitive="1">exit</Token>
<Token pen="210" style="bold" caseinsensitive="1">export</Token>
<Token pen="210" style="bold" caseinsensitive="1">file</Token>
<Token pen="210" style="bold" caseinsensitive="1">finalization</Token>
<Token pen="210" style="bold" caseinsensitive="1">finally</Token>
<Token pen="210" style="bold" caseinsensitive="1">for</Token>
<Token pen="210" style="bold" caseinsensitive="1">function</Token>
<Token pen="210" style="bold" caseinsensitive="1">goto</Token>
<Token pen="210" style="bold" caseinsensitive="1">if</Token>
<Token pen="210" style="bold" caseinsensitive="1">implementation</Token>
<Token pen="210" style="bold" caseinsensitive="1">in</Token>
<Token pen="210" style="bold" caseinsensitive="1">inherited</Token>
<Token pen="210" style="bold" caseinsensitive="1">initialization</Token>
<Token pen="210" style="bold" caseinsensitive="1">inline</Token>
<Token pen="210" style="bold" caseinsensitive="1">interface</Token>
<Token pen="210" style="bold" caseinsensitive="1">is</Token>
<Token pen="210" style="bold" caseinsensitive="1">label</Token>
<Token pen="210" style="bold" caseinsensitive="1">library</Token>
<Token pen="210" style="bold" caseinsensitive="1">mod</Token>
<Token pen="210" style="bold" caseinsensitive="1">new</Token>
<Token pen="210" style="bold" caseinsensitive="1">not</Token>
<Token pen="210" style="bold" caseinsensitive="1">object</Token>
<Token pen="210" style="bold" caseinsensitive="1">of</Token>
<Token pen="210" style="bold" caseinsensitive="1">on</Token>
<Token pen="210" style="bold" caseinsensitive="1">operator</Token>
<Token pen="210" style="bold" caseinsensitive="1">or</Token>
<Token pen="210" style="bold" caseinsensitive="1">out</Token>
<Token pen="210" style="bold" caseinsensitive="1">packed</Token>
<Token pen="210" style="bold" caseinsensitive="1">procedure</Token>
<Token pen="210" style="bold" caseinsensitive="1">program</Token>
<Token pen="210" style="bold" caseinsensitive="1">property</Token>
<Token pen="210" style="bold" caseinsensitive="1">raise</Token>
<Token pen="210" style="bold" caseinsensitive="1">record</Token>
<Token pen="210" style="bold" caseinsensitive="1">repeat</Token>
<Token pen="210" style="bold" caseinsensitive="1">self</Token>
<Token pen="210" style="bold" caseinsensitive="1">set</Token>
<Token pen="210" style="bold" caseinsensitive="1">shl</Token>
<Token pen="210" style="bold" caseinsensitive="1">shr</Token>
<Token pen="210" style="bold" caseinsensitive="1">string</Token>
<Token pen="210" style="bold" caseinsensitive="1">then</Token>
<Token pen="210" style="bold" caseinsensitive="1">threadvar</Token>
<Token pen="210" style="bold" caseinsensitive="1">to</Token>
<Token pen="210" style="bold" caseinsensitive="1">try</Token>
<Token pen="210" style="bold" caseinsensitive="1">type</Token>
<Token pen="210" style="bold" caseinsensitive="1">unit</Token>
<Token pen="210" style="bold" caseinsensitive="1">until</Token>
<Token pen="210" style="bold" caseinsensitive="1">uses</Token>
<Token pen="210" style="bold" caseinsensitive="1">var</Token>
<Token pen="210" style="bold" caseinsensitive="1">virtual</Token>
<Token pen="210" style="bold" caseinsensitive="1">while</Token>
<Token pen="210" style="bold" caseinsensitive="1">with</Token>
<Token pen="210" style="bold" caseinsensitive="1">xor</Token>
<!--Consts-->
<Token pen="215" caseinsensitive="1">true</Token>
<Token pen="215" caseinsensitive="1">false</Token>
<Token pen="215" caseinsensitive="1">nil</Token>
<!--Single line comment first as it otherwise conflicts with the single / operator-->
<ComplexToken>
<!-- line comment-->
<Token pen="240" style="italic">//</Token>
<MatchToEOL/>
</ComplexToken>
<!-- operators Set -->
<Token pen="222">include</Token>
<Token pen="222">exclude</Token>
<Token pen="220"><![CDATA[><]]></Token>
<!-- operators Logical -->
<Token pen="223"><![CDATA[<<]]></Token>
<Token pen="223"><![CDATA[>>]]></Token>
<!-- operators Relational -->
<Token pen="220"><![CDATA[<>]]></Token>
<Token pen="220"><![CDATA[<=]]></Token>
<Token pen="220"><![CDATA[>=]]></Token>
<Token pen="220"><![CDATA[<]]></Token>
<Token pen="220"><![CDATA[>]]></Token>
<Token pen="220"><![CDATA[=]]></Token>
<!-- operators Arithmatic -->
<Token pen="221">+</Token>
<Token pen="221">-</Token>
<Token pen="221">*</Token>
<Token pen="221">/</Token>
<!-- operators NOT REALLY -->
<Token>()</Token>
<Token pen="2">:=</Token>
<Token style="bold">:</Token>
<Token style="bold">,</Token>
<Token pen="2" bgpen="4">==</Token>
<Token pen="2" bgpen="4">!=</Token>
<!-- Preprocessor tokens first to avoid conflict -->
<ComplexToken>
<!-- preprocessor "{$"-->
<Token pen="211" style="italic">{$</Token>
<MatchToToken>$}</MatchToToken>
<MatchToEOL/>
</ComplexToken>
<!-- String and char-const tokens: -->
<ComplexToken>
<!--- Apostrophe -->
<Token pen="230" style="italic">'</Token>
<MatchToToken>'</MatchToToken>
<MatchToEOL/>
</ComplexToken>
<!-- Comments... -->
<ComplexToken>
<!-- block comment ( {} delimited ) -->
<Token pen="241" style="italic">{</Token>
<MatchToToken>}</MatchToToken>
<MultiLine/>
</ComplexToken>
<ComplexToken>
<!-- block comment delimited by asterisk -->
<Token pen="242" style="italic">(*</Token>
<MatchToToken>*)</MatchToToken>
<MultiLine/>
</ComplexToken>
<!-- Preprocessing directives... -->
</Syntax>
</Ann-SyntaxHighlighting>
Please note that the following pens are being used:
- pen 2, for assignment operator ( ":=" )
- pen 210, for pascal language keywords
- pen 211, for preprocessor statements ( "{$}" )
- pen 215, for some constants
- pen 220, for relation operators ( "<", ">", "<>", "<=", ">=" and "=")
- pen 221, for arithmetic operators ( "+", "-", "*" and "/" )
- pen 222, for set operators ( "include", "exclude" and "><" )
- pen 223, for logical operators ( "<<" and ">>" )
- pen 230, for single quote strings ( "'" )
- pen 240, for a line comment ( "//" )
- pen 241, for a block comment ( enclosed between "{" and "}" )
- pen 242, for a block comment ( enclosed between "(*" and "*)" )
And that the actual colors being used in Annotate, originates from the screen in AROS on which you have opened the Annotate editor (therefore the colors could be customized differently for each individual screen).
Because AROS lacks support for configuring a user-defined palette (for the workbench at least), it's up to yourself to change the pen-colors manually (which can be done by the setpencolor utility that's present in at least the latest Icaros distribution).
Please note that by setting the pens to your desired colors that you can mess up your desktop's view because you changed a color that is in use by the AROS operating system. If that's the case, simply restart your Icaros installation and make sure next time you use the a pen number that is not in use by AROS (hence why the currently (absurd) used pen-numbers in annotates configuration were chosen). The only pen-numbers whose color you definitely do not want to change are pen numbers 0-3, as they are default used Workbench colors (and they actually _are_ being defined and always matches the original classic Workbench colors).
Adding a syntax highlighting scheme to Annotate
In the drawer where Annotate is located, a hidden drawer can be found which is named "syntax contribution". In that folder is a file named "How to add a contrib syntax.readme".
The following is a literal copy from that text:
How to use one of the contribution synxta files. ------------------------------------------------ Open the Config from Annotate and select the Syntax page. Click Add file and select the contribution syntax file. The new syntax will be added to your AnnotateSyntax.xml file and loaded everytime you start Annotate in the future. Alternatively, you can do it manually by simply adding a similar line to the <Ann-SyntaxHighlighting> block in the AnnotateSyntax.xml file: <SyntaxFile filename="Syntax Contribution/Annotate_new_syntax.xml"/>
Changing the colors
This is an example of how the colors of the pens can be changed. The color-scheme itself tries to mimic the colors used in old DOS editor (a little).
Please be aware that, in order to change the background, you would need to configure Annotate to use the color of pen-number 200 for the background. The presented scheme also uses the color of pen-number 201 for 'normal' text without formatting (on which some of the other syntax highlghting entries are based), so that this pen would need to be configured in Annotate as well.
The presented changes themselves are formatted according to shell-script rules, and the commands need to be performed each time (before) you start the Annotate editor. You can accomplish that either by starting Annotate using a icon that calls IconX (and this script accordingly) or put the command into a script and call that from f.e. the startup-sequence or user-startup scripts.
; Background color
SetPenColor PEN=200 COLOR=$00C00000 >NIL:
; Plain Text Color
SetPenColor PEN=201 COLOR=$0000FFFF >NIL:
; Programming language KeyWords
SetPenColor PEN=210 COLOR=$00FFFFFF >NIL:
; Preprocessor
SetPenColor PEN=211 COLOR=$000000FF >NIL:
; Contant values that need distinction
SetPenColor PEN=215 COLOR=$00FF22EE >NIL:
; Set Operators
SetPenColor PEN=222 COLOR=$0088FF88 >NIL:
; Logical Operators
SetPenColor PEN=223 COLOR=$0088FF88 >NIL:
; Relational Operators
SetPenColor PEN=220 COLOR=$0088FF88 >NIL:
; Arithmatic Operators
SetPenColor PEN=221 COLOR=$0088FF88 >NIL:
; Literal string
SetPenColor PEN=230 COLOR=$000f0fff >NIL:
; Single Line Comment "//"
SetPenColor PEN=240 COLOR=$00C6C3C6 >NIL:
; Multi Comment "{" "}"
SetPenColor PEN=241 COLOR=$00FF00FF >NIL:
; Multi Comment "(*" "*)"
SetPenColor PEN=242 COLOR=$0000FF00 >NIL:
; Possible comment color but not actually supported
SetPenColor PEN=243 COLOR=$00FFFF00 >NIL:
Configuring Annotate
TODO: - describe how to setup tools menu to compile with command-line compiler. - describe shortcomings/work-around of using tools-menu for compiler - describe how to change shortcuts to more familiar Windows shortcuts.
OTHER TODO's: - add pictures. - explain the use of colors. - probably some other stuff i forgot.
The Annotate editor offers the possibility to add customized items to the Tool-menu.
In order to do so, open up the Annotate configuration window by selecting the settings/config item from the main menu. Once the Config Window is opened, the item Tools at the left pasrt of the window (in the listbox) needs to be selected. Once done, the righ tside of the config window will show you a list of the tool configuration settings.
First, let's take a look at the procedure that needs to be followed in order to add a new (customized) tool-item (that will be added to Annotate's tool menu):
- press the add button to add a new entry to the list of tools.
- a new tool entry with the 'title' "unnamed" and an empty 'command line' is created.
- make sure you select the newly created 'title' "unnamed" by clicking on it with the left mouse button. If the item is correctly selected it will be highlighted.
- the 'title' and 'Command line' gadgets are automatically set according to the selected 'title' from the list.
- change the 'title' of the tool (that will eventually appear in the tool-menu) by clicking on its text gadget (with the left mousebutton).
- type the desired 'title' for your tool entry.
- once done typing the 'title', make sure to press the enter key to reflect your changes.
- change the 'command line' of the tool, by clicking on its text gadget (with the left mousebutton).
- type the desired 'command line' you want to use for your tool entry.
- once done typing the 'command line', make sure to press the enter key to reflect your changes.
- repeat this sequence for every tool you like to add to the tool menu.
Finally, when things are done, the save-button at the bottom right of the Annotate configuration window can be pressed om porder to save your changes permantly to disk.
Now, let's apply this seuqence, in order to add FPC related tools to the menu.
adding an FPC compilation command
NOTE: The used 'title' and 'command line' (used in this example) does not necessarily matches reader's personal preferenceor nor location of the used commands. Reader should at least make sure the used locations matches to personal setup/configuration.
- press the add button
- make sure you select the newly created item from the list
- change the 'title' into "Compile with FPC" (without quotes), make sure to press enter
- change the 'command line' into "Extras:Development/languages/fpc/bin/fpc "%f"" (without the most left and most right quote. Make sure to press enter when done.
adding a verbose fpc compilation command
NOTE: The used 'title' and 'command line' (used in this example) does not necessarily matches reader's personal preferenceor nor location of the used commands. Reader should at least make sure the used locations matches to personal setup/configuration.
- press the add button
- make sure you select the newly created item from the list
- change the 'title' into "Compile verbose with FPC" (without quotes), make sure to press enter
- change the 'command line' into "Extras:Development/languages/fpc/bin/fpc -va "%f"" (without the most left and most right quote. Make sure to press enter when done.
adding a fpc build command
NOTE: The used 'title' and 'command line' (used in this example) does not necessarily matches reader's personal preferenceor nor location of the used commands. Reader should at least make sure the used locations matches to personal setup/configuration.
- press the add button
- make sure you select the newly created item from the list
- change the 'title' into "Compile verbose with FPC" (without quotes), make sure to press enter
- change the 'command line' into "Extras:Development/languages/fpc/bin/fpc -B "%f"" (without the most left and most right quote. Make sure to press enter when done.