.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Syntax::Highlight::Engine::Kate 3pm"
.TH Syntax::Highlight::Engine::Kate 3pm "2022-11-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Syntax::Highlight::Engine::Kate \- a port to Perl of the syntax highlight engine of the Kate text editor.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& #if you want to create a compiled executable, you may want to do this:
\& use Syntax::Highlight::Engine::Kate::All;
\&
\& use Syntax::Highlight::Engine::Kate;
\& my $hl = Syntax::Highlight::Engine::Kate\->new(
\&     language      => \*(AqPerl\*(Aq,
\&     substitutions => {
\&         "<"  => "&lt;",
\&         ">"  => "&gt;",
\&         "&"  => "&amp;",
\&         " "  => "&nbsp;",
\&         "\et" => "&nbsp;&nbsp;&nbsp;",
\&         "\en" => "<BR>\en",
\&     },
\&     format_table => {
\&         Alert        => [ "<font color=\e"#0000ff\e">",       "</font>" ],
\&         BaseN        => [ "<font color=\e"#007f00\e">",       "</font>" ],
\&         BString      => [ "<font color=\e"#c9a7ff\e">",       "</font>" ],
\&         Char         => [ "<font color=\e"#ff00ff\e">",       "</font>" ],
\&         Comment      => [ "<font color=\e"#7f7f7f\e"><i>",    "</i></font>" ],
\&         DataType     => [ "<font color=\e"#0000ff\e">",       "</font>" ],
\&         DecVal       => [ "<font color=\e"#00007f\e">",       "</font>" ],
\&         Error        => [ "<font color=\e"#ff0000\e"><b><i>", "</i></b></font>" ],
\&         Float        => [ "<font color=\e"#00007f\e">",       "</font>" ],
\&         Function     => [ "<font color=\e"#007f00\e">",       "</font>" ],
\&         IString      => [ "<font color=\e"#ff0000\e">",       "" ],
\&         Keyword      => [ "<b>",                            "</b>" ],
\&         Normal       => [ "",                               "" ],
\&         Operator     => [ "<font color=\e"#ffa500\e">",       "</font>" ],
\&         Others       => [ "<font color=\e"#b03060\e">",       "</font>" ],
\&         RegionMarker => [ "<font color=\e"#96b9ff\e"><i>",    "</i></font>" ],
\&         Reserved     => [ "<font color=\e"#9b30ff\e"><b>",    "</b></font>" ],
\&         String       => [ "<font color=\e"#ff0000\e">",       "</font>" ],
\&         Variable     => [ "<font color=\e"#0000ff\e"><b>",    "</b></font>" ],
\&         Warning      => [ "<font color=\e"#0000ff\e"><b><i>", "</b></i></font>" ],
\&     },
\& );
\&
\& #or
\&
\& my $hl = Syntax::Highlight::Engine::Kate::Perl\->new(
\&     substitutions => {
\&         # ...
\&     },
\&     format_table => {
\&         # ...
\&     },
\& );
\&
\& print "<html>\en<head>\en</head>\en<body>\en";
\& while ( my $in = <> ) {
\&     print $hl\->highlightText($in);
\& }
\& print "</body>\en</html>\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBThis module is now deprecated\fR.
.PP
It is superseded and replaced by \fBSyntax::Kamelon\fR.
Best use \fBSyntax::Kamelon\fR for new projects.
.PP
Syntax::Highlight::Engine::Kate is a port to Perl of the syntax highlight engine of the
Kate text editor.
.PP
The language \s-1XML\s0 files of Kate have been rewritten to Perl modules using a script. These modules
function as plugins to this module.
.PP
Syntax::Highlight::Engine::Kate inherits Syntax::Highlight::Engine::Kate::Template.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fBlanguage\fR" 4
.IX Item "language"
Specify the language you want highlighted. Look in the \fB\s-1PLUGINS\s0\fR section for supported languages.
.IP "\fBplugins\fR" 4
.IX Item "plugins"
If you created your own language plugins you may specify a list of them with this option.
.Sp
.Vb 4
\& plugins => [
\&   ["MyModuleName", "MyLanguageName", "*,ext1;*.ext2", "Section"],
\&   ....
\& ]
.Ve
.IP "\fBformat_table\fR" 4
.IX Item "format_table"
This option must be specified if the \fBhighlightText\fR method needs to do anything useful for you.
All mentioned keys in the synopsis must be specified.
.IP "\fBsubstitutions\fR" 4
.IX Item "substitutions"
With this option you can specify additional formatting options.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBextensions\fR" 4
.IX Item "extensions"
Returns a reference to the extensions hash.
.IP "\fBlanguage\fR(\fI?$language?\fR)" 4
.IX Item "language(?$language?)"
Sets and returns the current language that is highlighted. When setting the language a reset is also done.
.IP "\fBlanguageAutoSet\fR(\fI\f(CI$filename\fI\fR)" 4
.IX Item "languageAutoSet($filename)"
Suggests language name for the given file \fB\f(CB$filename\fB\fR.
.IP "\fBlanguageList\fR" 4
.IX Item "languageList"
Returns a list of languages for which plugins have been defined.
.IP "\fBlanguagePlug\fR(\fI\f(CI$language\fI\fR, \fI?$insensitive?\fR)" 4
.IX Item "languagePlug($language, ?$insensitive?)"
Returns the module name of the plugin for \fB\f(CB$language\fB\fR.
.Sp
If \fB\f(CB$insensitive\fB\fR is set it will also try to match names ignoring case and return the correct module name of the plugin.
.Sp
e.g. \f(CW\*(C`$highlighter\->languagePlug(\*(AqHtMl\*(Aq, 1);\*(C'\fR will return \f(CW\*(C`HTML\*(C'\fR.
.IP "\fBlanguagePropose\fR(\fI\f(CI$filename\fI\fR)" 4
.IX Item "languagePropose($filename)"
Suggests language name for the given file \fB\f(CB$filename\fB\fR.
.IP "\fBsections\fR" 4
.IX Item "sections"
Returns a reference to the sections hash.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
In the Kate \s-1XML\s0 syntax files you find under the section \fB<itemDatas\fR> entries like
\&\f(CW\*(C`<itemData name="Unknown Property" defStyleNum="dsError" italic="1"/>\*(C'\fR. Kate is an editor
so it is ok to have definitions for foreground and background colors and so on. However,
since this module is supposed to be a more universal highlight engine, the attributes need
to be fully abstract. In which case, Kate does not have enough default attributes defined
to fulfill all needs. Kate defines the following standard attributes:
.IP "\(bu" 4
\&\fBdsNormal\fR
.IP "\(bu" 4
\&\fBdsKeyword\fR
.IP "\(bu" 4
\&\fBdsDataType\fR
.IP "\(bu" 4
\&\fBdsDecVal\fR
.IP "\(bu" 4
\&\fBdsBaseN\fR
.IP "\(bu" 4
\&\fBdsFloat\fR
.IP "\(bu" 4
\&\fBdsChar\fR
.IP "\(bu" 4
\&\fBdsString\fR
.IP "\(bu" 4
\&\fBdsComment\fR
.IP "\(bu" 4
\&\fBdsOthers\fR
.IP "\(bu" 4
\&\fBdsAlert\fR
.IP "\(bu" 4
\&\fBdsFunction\fR
.IP "\(bu" 4
\&\fBdsRegionMarker\fR
.IP "\(bu" 4
\&\fBdsError\fR
.PP
This module leaves out the \fB<ds\fR> part and uses following additional attributes:
.IP "\(bu" 4
\&\fBBString\fR
.IP "\(bu" 4
\&\fBIString\fR
.IP "\(bu" 4
\&\fBOperator\fR
.IP "\(bu" 4
\&\fBReserved\fR
.IP "\(bu" 4
\&\fBVariable\fR
.PP
I have modified the \s-1XML\s0 files so that each highlight mode would get its own
attribute. In quite a few cases still not enough attributes were defined. So in
some languages different modes have the same attribute.
.SH "PLUGINS"
.IX Header "PLUGINS"
Below is an overview of existing plugins. All have been tested on use and can be
created. The ones for which no sample file is available are marked. Those marked
\&\s-1OK\s0 have highlighted the test file without apparent mistakes. This does not mean
that all bugs are shaken out.
.PP
.Vb 10
\& LANGUAGE             MODULE                   COMMENT
\& ********             ******                   ******
\& .desktop             Desktop                  OK
\& 4GL                  FourGL                   No sample file
\& 4GL\-PER              FourGLminusPER           No sample file
\& ABC                  ABC                      OK
\& AHDL                 AHDL                     OK
\& ANSI C89             ANSI_C89                 No sample file
\& ASP                  ASP                      OK
\& AVR Assembler        AVR_Assembler            OK
\& AWK                  AWK                      OK
\& Ada                  Ada                      No sample file
\&                      Alerts                   OK hidden module
\& Ansys                Ansys                    No sample file
\& Apache Configuration Apache_Configuration     No sample file
\& Asm6502              Asm6502                  No sample file
\& Bash                 Bash                     OK
\& BibTeX               BibTeX                   OK
\& C                    C                        No sample file
\& C#                   Cdash                    No sample file
\& C++                  Cplusplus                OK
\& CGiS                 CGiS                     No sample file
\& CMake                CMake                    OK
\& CSS                  CSS                      OK
\& CUE Sheet            CUE_Sheet                No sample file
\& Cg                   Cg                       No sample file
\& ChangeLog            ChangeLog                No sample file
\& Cisco                Cisco                    No sample file
\& Clipper              Clipper                  OK
\& ColdFusion           ColdFusion               No sample file
\& Common Lisp          Common_Lisp              OK
\& Component\-Pascal     ComponentminusPascal     No sample file
\& D                    D                        No sample file
\& Debian Changelog     Debian_Changelog         No sample file
\& Debian Control       Debian_Control           No sample file
\& Diff                 Diff                     No sample file
\& Doxygen              Doxygen                  OK
\& E Language           E_Language               OK
\& Eiffel               Eiffel                   No sample file
\& Email                Email                    OK
\& Euphoria             Euphoria                 OK
\& Fortran              Fortran                  OK
\& FreeBASIC            FreeBASIC                No sample file
\& GDL                  GDL                      No sample file
\& GLSL                 GLSL                     OK
\& GNU Assembler        GNU_Assembler            No sample file
\& GNU Gettext          GNU_Gettext              No sample file
\& HTML                 HTML                     OK
\& Haskell              Haskell                  OK
\& IDL                  IDL                      No sample file
\& ILERPG               ILERPG                   No sample file
\& INI Files            INI_Files                No sample file
\& Inform               Inform                   No sample file
\& Intel x86 (NASM)     Intel_X86_NASM           seems to have issues
\& JSP                  JSP                      OK
\& Java                 Java                     OK
\& JavaScript           JavaScript               OK
\& Javadoc              Javadoc                  No sample file
\& KBasic               KBasic                   No sample file
\& Kate File Template   Kate_File_Template       No sample file
\& LDIF                 LDIF                     No sample file
\& LPC                  LPC                      No sample file
\& LaTeX                LaTex                    OK
\& Lex/Flex             Lex_Flex                 OK
\& LilyPond             LilyPond                 OK
\& Literate Haskell     Literate_Haskell         OK
\& Lua                  Lua                      No sample file
\& M3U                  M3U                      OK
\& MAB\-DB               MABminusDB               No sample file
\& MIPS Assembler       MIPS_Assembler           No sample file
\& Makefile             Makefile                 No sample file
\& Mason                Mason                    No sample file
\& Matlab               Matlab                   has issues
\& Modula\-2             Modulaminus2             No sample file
\& Music Publisher      Music_Publisher          No sample file
\& Octave               Octave                   OK
\& PHP (HTML)           PHP_HTML                 OK
\&                      PHP_PHP                  OK hidden module
\& POV\-Ray              POV_Ray                  OK
\& Pascal               Pascal                   No sample file
\& Perl                 Perl                     OK
\& PicAsm               PicAsm                   OK
\& Pike                 Pike                     OK
\& PostScript           PostScript               OK
\& Prolog               Prolog                   No sample file
\& PureBasic            PureBasic                OK
\& Python               Python                   OK
\& Quake Script         Quake_Script             No sample file
\& R Script             R_Script                 No sample file
\& REXX                 REXX                     No sample file
\& RPM Spec             RPM_Spec                 No sample file
\& RSI IDL              RSI_IDL                  No sample file
\& RenderMan RIB        RenderMan_RIB            OK
\& Ruby                 Ruby                     OK
\& SGML                 SGML                     No sample file
\& SML                  SML                      No sample file
\& SQL                  SQL                      No sample file
\& SQL (MySQL)          SQL_MySQL                No sample file
\& SQL (PostgreSQL)     SQL_PostgreSQL           No sample file
\& Sather               Sather                   No sample file
\& Scheme               Scheme                   OK
\& Sieve                Sieve                    No sample file
\& Spice                Spice                    OK
\& Stata                Stata                    OK
\& TI Basic             TI_Basic                 No sample file
\& TaskJuggler          TaskJuggler              No sample file
\& Tcl/Tk               TCL_Tk                   OK
\& UnrealScript         UnrealScript             OK
\& VHDL                 VHDL                     No sample file
\& VRML                 VRML                     OK
\& Velocity             Velocity                 No sample file
\& Verilog              Verilog                  No sample file
\& WINE Config          WINE_Config              No sample file
\& Wikimedia            Wikimedia                No sample file
\& XML                  XML                      OK
\& XML (Debug)          XML_Debug                No sample file
\& Yacc/Bison           Yacc_Bison               OK
\& de_DE                De_DE                    No sample file
\& en_EN                En_EN                    No sample file
\& ferite               Ferite                   No sample file
\& nl                   Nl                       No sample file
\& progress             Progress                 No sample file
\& scilab               Scilab                   No sample file
\& txt2tags             Txt2tags                 No sample file
\& x.org Configuration  X_org_Configuration      OK
\& xHarbour             XHarbour                 OK
\& xslt                 Xslt                     No sample file
\& yacas                Yacas                    No sample file
.Ve
.PP
Module Syntax::Highlight::Engine::Kate::Convert::ToolKit and script
hl-kate-convert can be used to convert existing Kate/KTextEditor Syntax
Highlighting file from \s-1XML\s0 format to Perl.
.SH "BUGS"
.IX Header "BUGS"
Float is detected differently than in the Kate editor.
.PP
The regular expression engine of the Kate editor, qregexp, appears to be more tolerant to mistakes
in regular expressions than Perl. This might lead to error messages and differences in behaviour.
Most of the problems were sorted out while developing, because error messages appeared. For as far
as differences in behaviour is concerned, testing is the only way to find out, so I hope the users
out there will be able to tell me more.
.PP
This module is mimicking the behaviour of the syntax highlight engine of the Kate editor. If you find
a bug/mistake in the highlighting, please check if Kate behaves in the same way. If yes, the cause is
likely to be found there.
.SH "TO DO"
.IX Header "TO DO"
Rebuild the scripts I am using to generate the modules from \s-1XML\s0 files so they are more pro-actively tracking
flaws in the build of the \s-1XML\s0 files like missing lists. Also regular expressions in the \s-1XML\s0 can be tested better
before they are used in plugins.
.PP
Refine the test methods in Syntax::Highlight::Engine::Kate::Template, so that choices for case sensitivity,
dynamic behaviour and lookahead can be determined at generate time of the plugin, might increase throughput.
.PP
Implement code folding.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
All the people who wrote Kate and the syntax highlight \s-1XML\s0 files.
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
This module is written and maintained by:
.PP
Hans Jeuken < haje at toneel dot demon dot nl >
.PP
Copyright (c) 2006 by Hans Jeuken, all rights reserved.
.PP
You may freely distribute and/or modify this module under the same terms
as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Syntax::Highlight::Engine::Kate::Template
.IP "\(bu" 4
<http://www.kate\-editor.org>
.IP "\(bu" 4
KTextEditor Syntax Highlighting Repository <https://quickgit.kde.org/?p=ktexteditor.git&a=tree&f=src%2Fsyntax%2Fdata>