Using annotate

From Freepascal Amiga wiki
Revision as of 12:49, 4 July 2014 by Molly (talk | contribs) (added initial sub-chapter "Adding the syntax highlighting scheme to Annotate")
Jump to navigation Jump to search

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:    -->
<!-- & - &amp;   < - &lt;   > - &gt;   " - &quot;   ' - &apos; -->
<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">&apos;</Token>
      <MatchToToken>&apos;</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 where chosen). The only pencolor you definitely do not want to change is pen number 0-3 as they are the first default used workbench colors (and they actually _are_ being defined and always matches the original classic workbench colors).

Adding the syntax highlighting scheme to Annotate

TODO: describe how to add the xml scheme to annotate


Chancing the colors

This is an example of how the colors of the pens can be changed. The color-sceme itself tries to mimic the old DOS editor a little.

Please be aware that in order to change the background, you would need to configure Annotate to use pencolor 200 as pen for the background. The scheme also uses pen 201 for 'normal' text without formatting, so that would need to be configured in Annotate as well.

The scheme itself 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 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:


TODO: - add pictures - explain the use of colors - probably some other stuff i forgot.