KSyntaxHighlighting

Syntax Highlighting

Syntax highlighting engine for Kate syntax definitions

Table of contents

  1. Introduction
  2. Syntax Definition Files
  3. Out of scope
  4. Build it
  5. How to contribute
  6. Adding unit tests for a syntax definition
  7. Report bug or help to fix them

Introduction

This is a stand-alone implementation of the Kate syntax highlighting engine. It's meant as a building block for text editors as well as for simple highlighted text rendering (e.g. as HTML), supporting both integration with a custom editor as well as a ready-to-use QSyntaxHighlighter sub-class.

Syntax Definition Files

This library uses Kate syntax definition files for the actual highlighting, the file format is documented here.

More than 300 syntax definition files are included, that are located in data/syntax/ and have the **.xml** extension. Additional ones are picked up from the file system if present, so you can easily extend this by application-specific syntax definitions for example.

To install or test a syntax definiton file locally, place it in org.kde.syntax-highlighting/syntax/, which is located in your user directory. Usually it is:

For local user $HOME/.local/share/org.kde.syntax-highlighting/syntax/
For Kate's Flatpak package $HOME/.var/app/org.kde.kate/data/org.kde.syntax-highlighting/syntax/
For Kate's Snap package $HOME/snap/kate/current/.local/share/org.kde.syntax-highlighting/syntax/
On Windows® USERPROFILE%.kde.syntax-highlighting\

For more details, see "The Highlight Definition XML Format" (Working with Syntax Highlighting, KDE Documentation).

Also, in data/schema/ there is a script to validate the syntax definiton XML files. Use the command validatehl.sh mySyntax.xml.

Out of scope

To not turn this into yet another text editor, the following things are considered out of scope:

  • code folding, beyond providing folding range information
  • auto completion
  • spell checking
  • user interface for configuration
  • management of text buffers or documents

If you need any of this, check out KTextEditor.

Build it

  1. Create and change into a build directory. Usually, a folder called build is created inside the syntax-highlighting source directory.
1 mkdir <build-directory>
2 cd <build-directory>
  1. Run the configure process with cmake and compile:
1 cmake <source-directory>
2 make

For more details see "Building Kate from Sources on Linux" (Kate Editor Website).

NOTE: If running cmake shows an error related to your version of KDE Frameworks, you edit the CMakeLists.txt file in the line find_package(ECM 5.XX.X ...).

  1. To run tests:
1 make test

The tests are located in the autotests directory. This command can be used to check changes to units test after modifying some syntax definition file. To add a unit test or update the references, see the section "Adding unit tests for a syntax definition".

How to contribute

KDE uses a GitLab instance at invent.kde.org for code review. The official repository of the KSyntaxHighlighting framework is here.

All the necessary information to send contributions is here.

What you should know before working with syntax definition files and sending a patch

Adding unit tests for a syntax definition

  1. Add an input file into the autotests/input/ folder, lets call it test.<language-extension>.
  2. If the file extension is not sufficient to trigger the right syntax definition, you can add an second file testname.<language-extension>.syntax that contains the syntax definition name to enforce the use of the right extension.
  3. Do make && make test.

    Note that after adding or modifying something in **<source-directory>/autotests/input/**, an error will be showed when running make test, because the references in the source directory do not match the ones now generated.

  4. Inspect the outputs found in your binary directory autotests/folding.out/, autotests/html.output/ and autotests/output/.
  5. If OK, run in the binary folder ./autotests/update-reference-data.sh to copy the results to the right location. That script updates the references in the source directory in autotest/folding/, autotest/html/ and autotest/reference/.
  6. Add the result references after the copying to the git.

Report bug or help to fix them

KDE uses Bugzilla to management of bugs at bugs.kde.org. You can see the bugs reported of frameworks-syntax-highlighting here.

Also, you can report a bug here.

However, some users often report bugs related to syntax highlighting in kate/syntax and kile/editor.

This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Sun Aug 2 2020 22:58:07 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.