diff --git a/COLLABORATE.md b/COLLABORATE.md
new file mode 100644
--- /dev/null
+++ b/COLLABORATE.md
@@ -0,0 +1,125 @@
+# How to contribute to the KSyntaxHighlighting framework
+
+## Repository and sending patches
+
+KDE uses Phabricator as a task management and patch revision system
+(however projects are gradually moving to GitLab at **invent.kde.org** that
+replaces Phabricator's code review functionality).
+The official repository of the KSyntaxHighlighting framework is:
+
+ https://phabricator.kde.org/source/syntax-highlighting/
+
+All the necessary information to send contributions in Phabricator is here:
+
+ https://community.kde.org/Infrastructure/Phabricator
+
+**Tip:** When creating a diff, it is recommended to add reviewers, you can
+add the groups: `#framework_syntax_highlighting, #kate`
+
+
+## Create or edit syntax highlighting files
+
+The syntax highlighting definition files consist of XML files that are located in
+**data/syntax/**. The documentation to create or edit this files can be found at:
+
+ https://docs.kde.org/trunk5/en/applications/katepart/highlight.html
+
+You can install or test some XML file, placing it in **org.kde.syntax-highlighting/syntax/**,
+which is located in the 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%\AppData\Local\org.kde.syntax-highlighting\syntax\ |
+
+
+
+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 XML files. Use the
+command `validatehl.sh mySyntax.xml`.
+
+
+## What you should know before working with syntax highlighting files and sending a patch
+
+* If you are modifying an existing 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.
+ More information about the MIT license: https://directory.fsf.org/wiki/License:Expat
+
+* 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 XML file, create a new test file; if you are
+ going to modify a XML file, adds examples to existing test files. This files
+ usually have the name **test.<language-extension>**.
+ It is worth mentioning that, if the file extension is not sufficient to trigger the
+ right syntax definition, you can add an second file **<test-file-name>.syntax**
+ that contains the syntax definition name to enforce the use of the right extension.
+
+ 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.
+
+
+## Building and generate the autotests files
+
+To compile the KSyntaxHighlighting framework, use the commands:
+
+ cd
+ cmake
+ make
+
+Also see: https://kate-editor.org/build-it/
+
+Then, to generate the autotests files, run:
+
+ make test
+
+However, the output files are kept in your build directory, in
+**autotests/folding.out/**, **autotests/html.output/** and **autotests/output/**.
+Thus, after adding or modifying something in **<source-directory>/autotests/input/**,
+an error will be showed when running `make test`.
+Finally, check that the generated files are OK and run in the build directory:
+
+ autotest/update-reference-data.sh
+
+That script updates the files in **autotest/folding/**, **autotest/html/**
+and **autotest/reference/**.
+
+
+## Report bug or help to fix them
+
+KDE uses Bugzilla to management of bugs. You can see the bugs reported
+of **frameworks-syntax-highlighting** in:
+
+ https://bugs.kde.org/describecomponents.cgi?product=frameworks-syntax-highlighting
+
+To report a bug:
+
+ https://bugs.kde.org/enter_bug.cgi?product=frameworks-syntax-highlighting
+
+However, some users often report bugs related to syntax highlighting in **kate** and **kile**:
+
+* Bugs in *kate/syntax*: https://bugs.kde.org/buglist.cgi?component=syntax&product=kate&resolution=---
+* Bugs in *kile/editor*: https://bugs.kde.org/buglist.cgi?component=editor&product=kile&resolution=---
diff --git a/README.md b/README.md
--- a/README.md
+++ b/README.md
@@ -2,6 +2,16 @@
Syntax highlighting engine for Kate syntax definitions
+## 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)
+
## Introduction
This is a stand-alone implementation of the Kate syntax highlighting engine.
@@ -14,10 +24,39 @@
This library uses Kate syntax definition files for the actual highlighting,
the file format is documented [here](https://docs.kde.org/stable5/en/applications/katepart/highlight.html).
-More than 250 syntax definition files are included, additional ones are
+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%\AppData\Local\org.kde.syntax-highlighting\syntax\ |
+
+
+
+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`.
+
## Out of scope
To not turn this into yet another text editor, the following things are considered
@@ -31,19 +70,103 @@
If you need any of this, check out [KTextEditor](https://api.kde.org/frameworks/ktexteditor/html/).
+## 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
+ cd
+ ```
+
+2. Run the configure process with *cmake* and compile:
+
+ ```bash
+ cmake
+ 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).
+
## Adding unit tests for a syntax definition
-* add an input file into the autotests/input/ folder, lets call it test.
+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/**.
-* if the file extension is not sufficient to trigger the right syntax definition, you can add an
- second file testname..syntax that contains the syntax definition name
- to enforce the use of the right extension
+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/**.
-* do "make && make test"
+6. Add the result references after the copying to the git.
-* inspect the outputs found in your binary directory autotests/folding.out, autotests/html.output and autotests/output
+## Report bug or help to fix them
-* if ok, run in the binary folder "./autotests/update-reference-data.sh" to copy the results to the right location
+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).
-* add the result references after the copying to the git
+Also, you can report a bug [here](https://bugs.kde.org/enter_bug.cgi?product=frameworks-syntax-highlighting).
+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=---).