Syntax highlighting engine for Kate syntax definitions
Table of contents
- Syntax Definition Files
- Out of scope
- Build it
- How to contribute
- Adding unit tests for a syntax definition
- Report bug or help to fix them
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
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/|
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
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.
- Create and change into a build directory. Usually, a folder called build is created inside the syntax-highlighting source directory.
- Run the configure process with cmake and compile:
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 ...).
- To run tests:
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
All the necessary information to send contributions is here.
What you should know before working with syntax definition files and sending a patch
- If you are modifying an existing syntax definition XML file, you must increase the version number of the language.
- The KSyntaxHighlighting framework is under MIT license. Ideally, use MIT license for your contributions, including new XML files.
Do not use hard colors, as they may not look good or be illegible in some color themes. Prefer to use the default color styles.
For more information, see:
Important: add test files, these are found in autotests/input/. If you are going to add a new syntax XML file, create a new test file; if you are going to modify a XML file, adds examples to existing test files.
Then, it is necessary to generate and update the files in autotests/folding/, autotests/html/ and autotests/reference/, which must be included in the patches. The instructions are in the next section.
Adding unit tests for a syntax definition
- Add an input file into the autotests/input/ folder, lets call it test.<language-extension>.
- 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.
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.
- Inspect the outputs found in your binary directory autotests/folding.out/, autotests/html.output/ and autotests/output/.
- If OK, run in the binary folder
./autotests/update-reference-data.shto copy the results to the right location. That script updates the references in the source directory in autotest/folding/, autotest/html/ and autotest/reference/.
- Add the result references after the copying to the git.
Report bug or help to fix them
Also, you can report a bug here.