syntax:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
syntax:start [2014/02/09 01:50] – external edit 127.0.0.1syntax:start [2018/03/23 12:46] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== Syntax schema definition ====== ====== Syntax schema definition ======
  
-Here you can find basic description of HippoEDIT [[terms:syntax-schema|syntax schema]] structure and navigate to more detailed topics.+Here you can find a basic description of HippoEDIT [[terms:syntax-schema|syntax schema]] structure and navigate to more detailed topics.
  
 +===== How long it takes to create new syntax schema =====
 +The time you need to create a new syntax schema depends on the programming language syntax complexity and on the language syntax "uniqueness". 
 +
 +Normally if the language has C-like syntax, you will need less than 1 hour to create the basic skeleton of the new syntax schema. For more complex languages it could take up to 3 hours. Of course, the time also depends on how familiar you are with HippoEDIT syntax definition rules. Looking at a similar existing syntax as an example can help. 
 +
 +If you have an existing syntax schema for UltraEdit, TextPad or PSPad you can greatly speed up creation by converting the existing schema into HippoEDIT syntax definition schema using [[plugins:syntax-tools|Syntax Tools Plugin]].
 +
 +More advanced syntax configuration as: labels (to get [[view:pane:navigation|function list]] working), [[options:syntax:code-templates|code templates]] and [[tools:start|tools definition]] will take some more time but will give you a chance to work more effectively with source code for which you build the schema. 
 +
 +If you have questions about creating or need assistance you can always ask on forum or supportbox. Creating a new syntax schema gets you a [[http://www.hippoedit.com/free_licensed_copy.php|free HippoEDIT license]].
 ===== Files ===== ===== Files =====
-The definition of the programming language (syntax) in HippoEDIT is based on two files: {lang_name}_spec.xml and  {lang_name}_user.xml. Names of the file is not important – definition recognized by XML header. {lang_name}_spec.xml contains general definition of the syntax and is obligatory. {lang_name}_user.xml contains definition of the user specific settings for language (such as code templates, programming language specific tools, language help urls etc.) and is optional. Definition files should be placed in directory defined in Tools -> Options -> General -> Settings Path. By default this is {[[options:installation-directory|]]}\data\syntax.+The definition of the programming language (syntax) in HippoEDIT is based on two files: {lang_name}_spec.xml and  {lang_name}_user.xml. Names of the file are not important – definition recognized by XML header. {lang_name}_spec.xml contains general definition of the syntax and is obligatory. {lang_name}_user.xml contains definition of the user specific settings for language (such as code templates, programming language specific tools, language help urls etc.) and is optional. Definition files should be placed in directory defined in //Tools→Options→General→Settings Path//. By default this is {[[options:installation-directory|]]}\data\syntax.
  
 ===== First steps ===== ===== First steps =====
-To create your own syntax I would suggest to search some existing schema for language similar to one you want to have and copy + rename files.+To create your own syntax I would suggest searching the existing schemas for a language similar to the one you want to have and copy + rename files.
 Then open new files and search for something similar to this: Then open new files and search for something similar to this:
 <code xml><SYNTAX id="asm" name="ASM" inherit="def_source" inherit_url="defsource_spec.xml"></code> <code xml><SYNTAX id="asm" name="ASM" inherit="def_source" inherit_url="defsource_spec.xml"></code>
  
 ==== Syntax attributes ==== ==== Syntax attributes ====
-  * **id** (any string, preferable low case, without spaces and symbol : ) – unique id of the language (obligatory)+  * **id** (any string, preferably low case, without spaces and symbol : ) – unique id of the language (obligatory)
   * **name** (any string) – description of the language that would be used in UI   * **name** (any string) – description of the language that would be used in UI
-  * **inherit** (any id) – name of base (parent) schema. New schema would inherit all settings, styles of   parent. Normally you need to inherit from def or def_text or def_source. These schemes contain base definition for styles, without them a lot of functionality would not be available. +  * **inherit** (any id) – name of base (parent) schema. The new scheme would inherit all settings, styles of the parent. Normally you need to inherit from def or def_text or def_source. These schemes contain a base definition for styles, without them a lot of functionality would not be available. 
-  * **inhertit_url** (file path, relative or absolute) – name of parent schema file. Used only fir navigation between schemes when opened in browser (optional).+  * **inhertit_url** (file path, relative or absolute) – name of parent schema file. Used only for navigation between schemas when opened in the browser (optional). 
 +  * **abstract** (boolean, true/false, the default is false) - if set to true, the syntax will not be used for direct document syntax, but only as a base for some other syntax  
 +  * **version** (string, in form of N.N) - version of the syntax schema 
 +  * **required** (string, in form of N.N) - minimum version of the HippoEDIT to ensure proper syntax highlighting 
 +  * **preferred** (string, in form of N.N) - minimum optimum version of the HippoEDIT to ensure the best level of syntax highlighting 
 +  * **author** (any string) - author of the schema. If not set, //author// from //FileInfo// node is used 
 +  * **email** (any string) - email of the author
  
-After creating of the definition files and copying them into {Data} folder, HippoEDIT should load definitions and display them in Available Languages list (//Tools->Options->Available Languages//).+After creating the definition files and copying them into {Data} folder, HippoEDIT should load definitions and display them in Available Languages list (//Tools->Options->Available Languages//).
  
 ===== Structure ===== ===== Structure =====
Line 28: Line 44:
 ===== General rules ===== ===== General rules =====
  
-  * There is no specific order in XML tags necessary. But for keywords it is better to keep alphabetic order - this way internal loading faster.+  * There is no specific order of XML tags necessary. But for keywords, it's better to keep alphabetic order - this way internal loading is faster.
   * All tags and attribute name are CASE SENSITIVE.   * All tags and attribute name are CASE SENSITIVE.
-  * All not English text should be correctly encoded in UTF-8+  * Whole not English text should be correctly encoded in UTF-8
   * You can use comments, comment some parts etc.   * You can use comments, comment some parts etc.
  
 +===== How to Modify an existing syntax schema =====
 +Direct modifications of default syntax schemes are NOT recommended. The reason is, that your modifications may be overwritten by HippoEDIT update (installation on top) and you will need to repeat them once more. 
 +<note tip>HippoEDIT installer creates backups, before overwriting existing version of syntax schema file, copying the old version in file //<name_of_original_file>.old//. So, if you have a luck, you can copy your modifications from it in installed file.</note>
 +
 +The recommended way for modification is creating new syntax schema, inheriting from the original one, and adding new styles or overwriting inherited ones, for example. To not have conflicts with the detecting of proper syntax on document open (you have two syntax schema definitions reacting on same file mask, due to inheriting) you can disable original syntax in [[options:syntax:start|Tools->Options->Syntax Settings]] (uncheck it in the list).
 +
 +Example of syntax schema for HTML, adding new style:
 +<file xml my_html_spec.xml>
 +<?xml version="1.0" encoding="utf-8"?>
 +<?xml-stylesheet type="text/xsl" href="syntax.xslt"?>
 +<XMLConfigSettings>
 +  <FILEINFO author="HippoEDIT Happy User" type="LangSpec"/>
 +  <SYNTAX id="my_html" name="My HTML" inherit="html" inherit_url="html_spec.xml" version="1.0">
 +    <STYLES>
 +      <Style id="src_attribute" name="Source Attribute" bold="0" italic="0" underline="0" clr="Strings" bkclr="#856363A0">
 +        <Containers>
 +          <Open id="xml_open_tag"/>
 +        </Containers>
 +        <Blocks>
 +          <Regexp open="&quot;" open_lead="=crs" close="&quot;"/>
 +          <Regexp open="&apos;" open_lead="=crs" close="&apos;"/>
 +        </Blocks>
 +      </Style>
 +    </STYLES>
 +  </SYNTAX>
 +</XMLConfigSettings>
 +</file>
 ===== Advanced ===== ===== Advanced =====
   * [[syntax:escaping|Symbol Escaping]]   * [[syntax:escaping|Symbol Escaping]]
   * [[syntax:tooltip|Tooltip text formatting]]   * [[syntax:tooltip|Tooltip text formatting]]
  
-<note tip>The easiest way to start with creating of new syntax schema, is to import one of of the existing syntax definitions from other editors with help of [[plugins:syntax-tools|Syntax Tools plugin]].</note>+<note tip>The easiest way to start with creating a new syntax scheme is to import one of the existing syntax definitions from other editors with help of [[plugins:syntax-tools|Syntax Tools plugin]].</note>