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