README.md 7.17 KB
Newer Older
1
# Syntax Highlighting
Volker Krause's avatar
Volker Krause committed
2

3 4
Syntax highlighting engine for Kate syntax definitions

5 6 7 8 9 10 11 12 13 14
## Table of contents

1. [Introduction](#introduction)
2. [Syntax Definition Files](#syntax-definition-files)
3. [Out of scope](#out-of-scope)
4. [Build it](#build-it)
5. [How to contribute](#how-to-contribute)
6. [Adding unit tests for a syntax definition](#adding-unit-tests-for-a-syntax-definition)
7. [Report bug or help to fix them](#report-bug-or-help-to-fix-them)

15
## Introduction
Volker Krause's avatar
Volker Krause committed
16

17 18 19 20
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.
Volker Krause's avatar
Volker Krause committed
21

22
## Syntax Definition Files
Volker Krause's avatar
Volker Krause committed
23

24
This library uses Kate syntax definition files for the actual highlighting,
Amit Kumar Jaiswal's avatar
Amit Kumar Jaiswal committed
25
the file format is documented [here](https://docs.kde.org/stable5/en/applications/katepart/highlight.html).
Volker Krause's avatar
Volker Krause committed
26

27 28
More than 300 syntax definition files are included, that are located
in **data/syntax/** and have the **.xml** extension. Additional ones are
29 30
picked up from the file system if present, so you can easily extend this
by application-specific syntax definitions for example.
Volker Krause's avatar
Volker Krause committed
31

32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
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:

<table>
    <tr>
        <td>For local user</td>
        <td>$HOME/.local/share/org.kde.syntax-highlighting/syntax/</td>
    </tr>
    <tr>
        <td>For <a href="https://flathub.org/apps/details/org.kde.kate">Kate's Flatpak package</a></td>
        <td>$HOME/.var/app/org.kde.kate/data/org.kde.syntax-highlighting/syntax/</td>
    </tr>
    <tr>
        <td>For <a href="https://snapcraft.io/kate">Kate's Snap package</a></td>
        <td>$HOME/snap/kate/current/.local/share/org.kde.syntax-highlighting/syntax/</td>
    </tr>
    <tr>
        <td>On Windows®</td>
        <td>%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax\ </td>
    </tr>
</table>

For more details, see ["The Highlight Definition XML Format" (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/trunk5/en/applications/katepart/highlight.html#katehighlight-xml-format).

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

60
## Out of scope
Volker Krause's avatar
Volker Krause committed
61

62 63
To not turn this into yet another text editor, the following things are considered
out of scope:
Volker Krause's avatar
Volker Krause committed
64

65 66 67
* code folding, beyond providing folding range information
* auto completion
* spell checking
Volker Krause's avatar
Volker Krause committed
68
* user interface for configuration
Nicolás Alvarez's avatar
Nicolás Alvarez committed
69
* management of text buffers or documents
70

Amit Kumar Jaiswal's avatar
Amit Kumar Jaiswal committed
71
If you need any of this, check out [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/).
72

73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136
## Build it

1. Create and change into a build directory. Usually, a folder called **build**
   is created inside the **syntax-highlighting** source directory.

   ```bash
   mkdir <build-directory>
   cd <build-directory>
   ```

2. Run the configure process with *cmake* and compile:

   ```bash
   cmake <source-directory>
   make
   ```

   For more details see ["Building Kate from Sources on Linux" (Kate Editor Website)](https://kate-editor.org/build-it/).

   **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 ...)`.

3. To run tests:

   ```bash
   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"](#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](https://invent.kde.org/frameworks/syntax-highlighting).

All the necessary information to send contributions is [here](https://community.kde.org/Infrastructure/GitLab).

### 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](https://directory.fsf.org/wiki/License:Expat).
  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:
    * [Available Default Styles (Working with Syntax Highlighting, KDE Documentation)](https://docs.kde.org/trunk5/en/applications/katepart/highlight.html#kate-highlight-default-styles)
    * [Kate Part (KF5): New Default Styles for better Color Schemes (Kate Editor Website)](https://kate-editor.org/2014/03/07/kate-part-kf5-new-default-styles-for-better-color-schemes/)

* 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).

137 138
## Adding unit tests for a syntax definition

139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154
1. Add an input file into the **autotests/input/** folder, lets call it
   **test.&lt;language-extension&gt;**.

2. If the file extension is not sufficient to trigger the right syntax definition, you can add an
   second file **testname.&lt;language-extension&gt;.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
   **&lt;source-directory&gt;/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/**.
155

156 157 158 159
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/**.
160

161
6. Add the result references after the copying to the git.
162

163
## Report bug or help to fix them
164

165 166
KDE uses Bugzilla to management of bugs at **bugs.kde.org**. You can see the bugs
reported of **frameworks-syntax-highlighting** [here](https://bugs.kde.org/describecomponents.cgi?product=frameworks-syntax-highlighting).
167

168
Also, you can report a bug [here](https://bugs.kde.org/enter_bug.cgi?product=frameworks-syntax-highlighting).
169

170 171 172
However, some users often report bugs related to syntax highlighting in
[kate/syntax](https://bugs.kde.org/buglist.cgi?component=syntax&product=kate&resolution=---)
and [kile/editor](https://bugs.kde.org/buglist.cgi?component=editor&product=kile&resolution=---).