**2024/11/30


   .SyntaxHighlight.

    Syntax highlight display text with each color and font style according to the language syntax.
    xe's syntax-highlight use the function of André Simon's Highlight or GNU source-highlight.
    Configuration file is ::xesynw.cfg(Windows) / ::xesynl.cfg(Linux).

      GNU source-highlight (specified by SHCMD= in the cfg file)
      You need to install source-highlight (Linux version).
      For example, in the case of ubuntu, "sudo apt-get install source-highlight".
      --data-dir is /usr/share/source-highlight.
      On Windows, its binary is not maintained and the installation hurdle may be high.
      So the next André Simon's Highlight is easier to use.

      André Simon's Highlight (specified by SHCMDA= in the cfg file)
         Install from André Simon's homepage.
         xe use command-line binary, leave GUI version even if its "make" failed.

         For the Windows version, the necessary files for xe have been zipped and placed in the sample directory on GitHub.
         For the Windows version, the Data directory appears to be the default location of the exe.

    xe accept outlang:esc format output from highlighter through stdout pipe.
    Output of type esc contains ANSI ESC sequence codes that specify color and font style information.
    (xe fail to display color if original source contains esc code)

    (ANSI Esc sequence style code is NORMAL:0, BOLD:1, UNDERLINE:4, BLINK:5, REVERSE:7, INVISIBLE:8. About color code see later.)
    (xeacb is also used as utility to browse file contains ANSI Esc sequence code.)
    (Note.) Some anti-virus-soft watches external process i/o
            and that may be cause of syntax highlight's slow response.

    When lines are updated, syntax re-evaluation is not done immediately. Re-evaluation is done by Ctrl+s key as default.
    You can set ENTER key as trigger of re-evaluation by the cost of response delay.
    For best response.
      1.No trigger setting of ENTER key.
      2.Using Ctrl+s, do re-evaluation to the updated lines only when required.
      3.Using "SYN ALL" cmd, do re-evaluation to all lines when multiline evaluation rewuired.
    Next will be reasonable if you allow those response delay.
      1.Trigger setting of ENTER key as Update line only.
      2.Using Ctrl+s, do re-evaluation for all lines when required.
    Related cfg options.
      0. Set SyntaxHighlight:ON at file open using OPEN=/OPEN_EXT=.
      1. Set ENTER key trigger using ENTER=.
      2. Set UPDONLY_EXT= to limit or not re-evaluation to updated lines only.

    (a)Command.

       SYN [ ? | ALL | RESET | ENTER | ENTERA | ON [lang-type] | OFF]
            ?                 : Display help and brief current status.
            ALL               : Re-evaluation is done regardless update after previous evaluation and UPDONLY_EXT setting in .cfg file.
            RESET             : Use to re-read config file.
            ENTER             : Set ENTER key as trigger of re-evaluation for current file on the screen.
                                To keep good response, re-evaluation is done only for the updated lines
                                without consideration of multiline syntax.
                                To evaluate multiline syntax, execute "SYN ON"(Ctrl+s) cmd.
            ENTERA            : Set ENTER key as trigger of re-evaluation for current file on the screen.
                                Re-evaluation is done for all lines with consideration of multiline syntax
                                cost of slow response.
            ON [lang-type]    : Do re-evaluation for all lines of the file except the case
                                the extension is defined on UPDONLY_EXT of cfg file.
                                lang-type is used to change language type of the file.
            OFF               : Stop syntax highlight for the file.

       "SYN ON" is done if operand missing or function key Ctrl+s is used as default assignment.

    (b)Config file.

       Put cfg file on work-dir(c:\xe_wd or /home/userID/xe_wdnnnn, nnnn:userIDnumber as default).
       (cfg file name is xesynw.cfg(Windows version) or xesynl.cfg(Linux version)) or xesyna.cfg(Android version)
       See later, (d) for source-highlight configuration,
       (e) for André Simon's Highlighter configuration, (f) ANSI Esc sequence code.
       If you get messages indicating an error in your configuration file, you can fix it and reload it by "SYN RESET".

          SHCMD=     :source-highlight execution command.
                      When using a bat file on Windows, use $* to receive parameters from xe.
                      When using a shell on Linux, use $@ to receive parameters from xe.
                      Also, avoid outputting to standard output/standard error,
                      as this will result in an error message such as "Invalid Index file".
          SHCMDA=    :Runs André Simon's Highlight.
                      If the path contains spaces, specify as follows
                        SHCMDA= '""c:\Program Files\WinHighlight\highlight.exe"" -q --out-format=ansi'
                      When using a bat file on Windows, use $* to receive parameters from xe.
                      When using a shell on Linux, use $@ to receive parameters from xe.
                      Also, avoid outputting to standard output/standard error,
                      as this will result in an error message such as "Invalid Index file".
          ENTER =    :Specify the threshold of number of lines of the file, that will cause Enter key presses to trigger a re-evaluation of syntax.
                      When the file is opened and the number of lines is within the number specified here, Enter key will trigger a re-evaluation of updated lines.
                      It will only be triggered when OPEN=y, or after the file has been opened, when SYN is ON by SYN command (Ctrl+s).
                      "0" means that Enter key is not a triggar,
                      "-1" means that Enter key will re-evaluate regardless of the number of lines in the file.
                      The default value is -1.
          OPEN =     :Specifies that syntax highlighting is evaluated at the file is opened or not.
                      "Y": Turns ON for files with the extension specified in the next OPEN_EXT parameter.
                      "N": Turns OFF when the file is opened. Can be turned ON later with the SYN command.
                      "A": Turns ON for all files when the file is opened.
          OPEN_EXT=  :Specifies the list of file extensions to be targeted when OPEN=y is specified.
                      e.g.  OPEN_EXT=c cpp h hpp
          UPDONLY_EXT:Lists the extensions for language types that limit reevaluation by the "SYN ON" (Ctrl+s) to updated lines only.
                      For language types that do not have multi-line syntax such as the /* */ comments in C,
                      only updated lines need to be reevaluated.
                      So by specifying this here, the response of the "SYN ON" that reevaluates all lines will be faster.
                      If you mind the Enter key slow response and set "Enter=0", you will use "SYN" to reevaluate.
                      Even the language originally has a multi-line syntax but you want to speed up the "SYN ON" response, use this setting.
                      Even with this setting, you can still reevaluate the entire file with "SYN ALL".
                      If you set UPDONLY_EXT=default, pplied to all files.
                        Example: UPDONLY_EXT=cbl
          PATH_EXT_xxx=:Gives an extension in the directory path name for files that do not have a proper extension.
                        Specify the extension in xxx (up to 7 digits). One path is specified per line.
                        Files in the specified directory will be assumed to have the extension xxx,
                        regardless of their original extension.
                        e.g. PATH_EXT_cob=d:\src\cobs PATH_EXT_syslog=d:\logs\windows\actlog
          BG=        :Palette number of background color. Check the color of each palette number on the 0.0 screen.
                      Numbers are from "0" to "15" (Windows)/"7" (Linux).
          BG_BROWSE  :Background color palette number in Browse mode.
                      The default value is the same as BG.
          FG=        :Palette number of foreground color.
                      Numbers are from "0" to "15".
          BG_EOL=    :Background color palette number for the area after the end of the line.
                      The default value is the same as BG (edit mode) or BG_BROWSE (browse mode).
          BG_TAB=    :Background color palette number for TAB/non-printable characters.
                      The default value is the same as BG (edit mode) or BG_BROWSE (browse mode).
          BG_UPD=    :Background color palette number for unevaluated lines after updated.
                      The default value is 0 (black)
          BG_REVERSE_EDIT=:Background color when inverted for Find command, Cut and Paste, etc. on the Edit panel
                           The default value is 14 (yellow) for Windows, 6 (brown) for the Linux Console version.
          BG_REVERSE_BROWSE=: Background color when inverted for Find command, cut and paste, etc. on the Browse panel
                           The default value is 15 (white) for Windows, 6 (brown) for the Linux Console version.
          CMAP =     :source-highlight outputs the color number in the ANSI ESC sequence
                      according to the configuration definition.
                      Specifies this when changing the mapping without making it a xe palette number.
                      André Simon's Highlight does not seem to be able to change the mapping with its configuration definition. (See (e) below)
                      So use CMAP.
                      Specify as many as necessary, starting with color number "0".
                        e.g.  CMAP =__.04.10.__.01 # Swap red and blue, set green to high intensity. "__" means no change.
          RGBn =     :In the GUI version (wxe, gxe), the palette number color can be set continuous value.
                      n is a palette number from 0 to 15.
                        e.g. rgb2=20e030 # Set the RGB values of palette number 2 (green) to R:0x20, G:0xe0, B:0x30.
          ITALIC_ESC=:Informs xe of the ANSI ESC sequence code given to italics in esc.outlang in source-highlight.
                      Specify a value other than "0", "1":bold, or "4":underline.
                      The default value is "5":blink. Change esc.outlang to set the default value to italics.
                      Font style cannot be specified for André Simon's Highlight.
          C_BOLD =   :Font style = 1 (Bold) in the console version. Windows version only.
                      "H": High intensity (default value), "N": Ignored, "R": Inverted.
          C_UNDERLINE=:Treate Font style = 4 (Underline) in the console version.
                       "H": High intensity, "N": Ignored (default value), "R": Inverted.
          C_ITALIC = :Treate Font style = 5 in the console version (or the value specified by ITALIC_ESC if specified).
                      "H": High intensity, "N": Ignored (default value), "R": Inverted.
          G_BOLD =   :Trate Font style = 1 (Bold) in the GUI version (wxe, gxe).
                      "H": High intensity, "Y": Bold, "N": Ignored, "R": Inverted. Default value is "YH".
          G_UNDERLINE=:Treat font style = 4 (Underline) in GUI version (wxe). Not supported in gxe.
                       "H": High intensity, "Y": Underline, "N": Ignored, "R": Inverted. Default value is "Y".
          G_ITALIC = :Treat font style = 5 (or the value specified by ITALIC_ESC) in GUI version (wxe, gxe).
                      "H": High intensity, "Y": Italic, "N": Ignored, "R": Inverted. Default value is "Y".

    (c)sample cfg file.

    ######################################################################################
    # xesynw.cfg(Win)/xesynl.cfg(Linux)
    # ==syntax highlight configuration==
    #
    ### execution
    #
    #  select highight command from SHCMD or SHCMDA
    #     SHCMD=       :Specify source-highlight command
    #                   e.g.  SHCMD = "source-highlight"
    #     SHCMDA=      :Specify André Simon's Highlight command
    #                   e.g.  SHCMDA= '""w:\highlight.dir\hl64.exe"" -q --out-format=ansi'
    #     ENTER =      :File line count at open to re-evaluate updated lines by Enter key when SYN ON..
    #                   0 :Do not re-evaluate by Enter key. -1:No line count limit.(Default)
    ### file type
    #     OPEN  =      :SyntaxHighlight mode at opening file.
    #                   "Y":SyntaxHighlight mode if the extention is listed by OPEN_EXT
    #                   "N":always No SyntaxHighlight mode at open
    #                   "A":always SyntaxHighlight mode at open
    #     OPEN_EXT=    :Specify file extention list for the case of OPEN=y.
    #                   e.g. OPEN_EXT=c cpp h hpp
    #     UPDONLY_EXT  :Lists the extensions for language types that limit reevaluation by the "SYN ON" (Ctrl+s) to updated lines only.
    #                   e.g. UPDONLY_EXT=cob
    #     PATH_EXT_xxx=:Gives an extension in the directory path name for files that do not have a proper extension.
    #                   e.g. PATH_EXT_cob=d:\src\cobs
    ### color
    #     BG=          :Palette number of background color. Check the color of each palette number on the 0.0 screen.
    #                   Numbers are from "0" to "15" (Windows)/"7" (Linux).
    #     BG_BROWSE    :BackGround color palette number for browse panel
    #                   Default is same as BG
    #     FG=          :ForeGround color palette number
    #                   Valid value is "0" to "15"
    #     BG_EOL=      :Background color for the right of EndOfLine.
    #                   Default is same as BG(Edit) or BG_BROWSE(Browse)
    #     BG_TAB=      :Background color for TAB/UnPrintable Character.
    #                   Default is same as BG(Edit) or BG_BROWSE(Browse)
    #     BG_UPD=      :Background color for updated and not yet re-evaluated line.
    #                   Default:0(black)
    #     BG_REVERSE_EDIT=  :Background color for reverse on edit panel(Find cmd,Cut & Paste)
    #                        Default:14(yellow) except linux console version(6:brown)
    #     BG_REVERSE_BROWSE=:Background color for reverse on browse panel(Find cmd,Cut&Paste)
    #                        Default:15(white) except Linux console version(6:brown)
    #     CMAP  =      :Color palette re-mapping. Remap ANSI color number to xe's palette.
    #                   Specify from color palette number from 0 to max 15 each.
    #                   e.g. CMAP=__.04.10.__.01   # swap Red and Blue and use Intense Green("__" means no change.)
    #     RGBn  =      :RGB value for each palette (wxe and gxe only)
    #                   n:0-->15 (correspond to palette number of xe 0.0 panel)
    #                   e.g. rgb2=20e030   # palette No2(green)'rgb value is R:0x20, G:0xe0, B:0x30.
    ### font style
    #     ITALIC_ESC = :ANSI esc code for italic.
    #                   Notify value specified on esc.lang file of source-highlight as ANSI font style code:italic.
    #                   Valid value is one digit except reserved "0","1":bold, "4":underline.
    #                   Default is "5":blink. (If you use this default, specify it on esc.outlang).
    #     C_BOLD     = :treatment of font style:1(BOLD) for console version xe
    #                   "H":HighIntensity, "N":Ignore, "R":Reverse. Default is "H".
    #     C_UNDERLINE= :treatment of font style:4(UNDERLINE) for console version xe. Not supported for Linux version.
    #                   "H":HighIntensity, "N":Ignore, "R":Reverse.  Default is "N".
    #     C_ITALIC   = :treatment of font style:5(or value of ITALIC_ESC parameter if used) for console version xe
    #                   "H":HighIntensity, "N":Ignore, "R":Reverse.  Default is "N".
    #     G_BOLD     = :treatment of font style:1(BOLD) for GUI version xe(wxe,gxe)
    #                   "H":HighIntensity, "Y":Bold, "R":Reverse, "N":Ignore. Default is "YH".
    #     G_UNDERLINE= :treatment of font style:4(UNDERLINE) for GUI version xe(wxe). Not supported for gxe.
    #                   "H":HighIntensity, "Y":Underline, "R":Reverse, "N":Ignore. Default is "Y".
    #     G_ITALIC   = :treatment of font style:5(or value of ITALIC_ESC parameter if used) for GUI version xe(wxe,gxe)
    #                   "H":HighIntensity, "Y":Italic, "R":Reverse, "N":Ignore. Default is "Y".
    #####################################################################
    ### sample ###########################
    #####################################################################
    #Linux
    #SHCMD = "source-highlight"
    #Windows
     SHCMDA= '""w:\highlight-4.4-x64\highlight.exe"" -q --out-format=ansi'
    #ENTER =0
     BG    = 7
     FG    = 0
     BG_EOL= 6
     BG_TAB= 10
    #BG_UPD= 7
    #BG_REVERSE_EDIT=14;
    #BG_REVERSE_BROWSE=1
    #CMAP  =__.04.10.__.01.__.14  # swap Red and Blue and Intense Green("__" means no change.)
    #RGB1 = 20e030
    #RGB4 = 80f020
    #RGB14= f01080
    #ITALIC_ESC= 0
    #C_BOLD=h
    #C_ITALIC=n
    #C_UNDERLINE=n
    #G_BOLD=y
    #G_ITALIC=hy
     G_UNDERLINE=h
     OPEN  = y
     OPEN_EXT= c cpp java
    #######
    PATH_EXT_cob=g:\src\xe\cobs
    #####################################################################

    (d)source-highlight configuration.

       See source-highlight previously shown about detail information.
       This section is brief description related to xe.
       Source-highlight v3.1.8 also supports COBOL.
       Check lang.map to find the correspondence of file extension and lang.

       .lang.map

        Each lines are extension = lang-file format to map extension to input file language syntax file.
        Following lines are for the c-like language.
        ###
            cpp = cpp.lang
            c = cpp.lang
            C = cpp.lang
            cc = cpp.lang
            h = cpp.lang
            hh = cpp.lang
            H = cpp.lang
            hpp = cpp.lang

        To utilize COBOL,on assumption its extension is cob, insert following line into lang.map file.
            cob  = cobol.lang 

       .default.style
         
         How(color and font style) to display the comment, keyword etc. is coded in this file.
         You can select the other file by specifying --style-file= parameter on SHCMD of xe config file.

        ###
            keyword blue b ;    // for language keywords
            type darkgreen ;    // for basic types
            string red f ;      // for strings and chars
            comment brown i ;   // for comments
            number purple ;     // for literal numbers
            preproc darkblue b ;    // for preproc directives (e.g. #include, import)
            symbol darkred ;    // for simbols (e.g. <, >, +)
            function black b;   // for function calls and declarations
            cbracket red;       // for block brackets (e.g. {, })

       .esc.outlang

         Default outlang of source-highlight is html,
         xe use esc.outlang by specifying "-f esc" parameter.
         This file describe ESC code corresponding font style and color.
         To use italic,you have to change the following line of default esc.outlang file.
            italics "$style"
         is modified to
            italics "5$style"
         "5" is xe's default, that may any value except 0(Normal),1(Bold),4(Underline)
         if you specify it on ITALIC_ESC= line of xe config file.

         See later (f) for ANSI definition for color esc code.

    (e) André Simon's Highlight configuration.

       .tested using v2.7.
       .configuration folder is registered at installation.
       .see his homepage about customization.
        ANSI output style is hard-coded in ansigenerator.cpp as following.
        (see next (f) about meaning of "31","34",...)
        To customize color mapping,use CMAP option of xe's cfg file.
        Bold,Italic... style may not be avalable.(1st parameter:"00")

          styleTagOpen.push_back(getOpenTag("00", "31")); //str
          styleTagOpen.push_back(getOpenTag("00", "34"));//number
          styleTagOpen.push_back(getOpenTag("00", "34"));//sl comment
          styleTagOpen.push_back(getOpenTag("00", "34"));//ml comment
          styleTagOpen.push_back(getOpenTag("00", "35"));//escapeChar
          styleTagOpen.push_back(getOpenTag("00", "35"));//directive
          styleTagOpen.push_back(getOpenTag("00", "31"));//directive string
          styleTagOpen.push_back(getOpenTag("00", "30"));//linenum
          styleTagOpen.push_back(getOpenTag("00", "00"));//symbol

          getMatchingOpenTag(unsigned int styleID)
            return (styleID)?getOpenTag("00", "32", ""):getOpenTag("00", "33");
          ("32" or "33" by $KW_LIST class of .lang file in langDef dir)

    (f) ANSI definition.

       Note. Red and Blue bit is exchanged on Windows.

           style
             NORMAL     '0'
             BOLD       '1'
             UNDERLINE  '4'
             BLINK      '5'
             REVERSE    '7'
             INVISIBLE  '8'
           foreground colors
             30 black
             31 red
             32 green
             33 yellow
             34 blue
             35 magenta
             36 cyan
             37 white
           background colors
             40 black
             41 red
             42 green
             43 yellow
             44 blue
             45 magenta
             46 cyan
             47 white