Bug 414997

Summary:	Custom user syntax highlighting file does not override system syntax highlighting file
Product:	[Applications] kate	Reporter:	Russell <prusselltechgroup>
Component:	syntax	Assignee:	KWrite Developers <kwrite-bugs-null>
Status:	RESOLVED FIXED
Severity:	normal	CC:	christoph
Priority:	NOR
Version First Reported In:	19.08.3
Target Milestone:	---
Platform:	Other
OS:	Linux
Latest Commit:	https://commits.kde.org/kate/afa4538b6412977d0aeb8f7a0c100a9f314df3ad	Version Fixed In:
Sentry Crash Report:

Description Russell 2019-12-09 19:48:37 UTC

SUMMARY

Cannot override a system KDE Kate syntax highlighting file located at /usr/share/org.kde.syntax-highlighting/syntax/ with a user defined KDE Kate syntax highlighting file installed at $HOME/.local/share/org.kde.syntax-highlighting/syntax/ per KDE KatePart documentation.

The KDE KatePart documentation is located here:
https://docs.kde.org/trunk5/en/applications/katepart/highlight.html

The pertinent text is:
-------------
The formal definition, also known as the XSD you find in Syntax Highlighting repository in the file language.xsd

Custom .xml highlight definition files are located in org.kde.syntax-highlighting/syntax/ in your user folder found with qtpaths--paths GenericDataLocation which usually is $HOME/.local/share
-------------

STEPS TO REPRODUCE
1. Create a valid custom asciidoc.xml file
2. Copy to $HOME/.local/share/org.kde.syntax-highlighting/syntax/asciidoc.xml
3. Start kate
4. Review menu paths: Tools > Highlighting > Markup and Tools > Highlighting > Other
5. Rename /usr/share/org.kde.syntax-highlighting/syntax/asciidoc.xml
6. Repeat steps 3 and 4

OBSERVED RESULT
A user custom xml file exists at $HOME/.local/share/org.kde.syntax-highlighting/syntax/asciidoc.xml

When the system xml file exists at /usr/share/org.kde.syntax-highlighting/syntax/asciidoc.xml, the KDE Kate menu appears:

Tools > Highlighting > Markup > AsciiDoc
Tools > Highlighting > Other > not there

When the system xml file does not exist at /usr/share/org.kde.syntax-highlighting/syntax/asciidoc.xml, the KDE Kate menu appears:

Tools > Highlighting > Markup > not there
Tools > Highlighting > Other > AsciiDoc

NOTE: 

The user custom syntax highlighting/code folding file for asciidoc has a language element with these attributes:

-------------
<language name="AsciiDoc" section="Other"
          version="2" kateversion="3.7"
          extensions="*.asciidoc;*.txt;" mimetype=""
          priority="10"
-------------

EXPECTED RESULT

When both a system and user custom KDE Kate syntax highlighting exist, the user custom KDE Kate syntax highlighting file should override, or priority should be obeyed.

In this particular case, the KDE Kate menu should appear:

Tools > Highlighting > Markup > not there
Tools > Highlighting > Other > AsciiDoc

A custom user xml file should override the system xml.

SOFTWARE/OS VERSIONS

KDE Plasma Version: 5.17.3
KDE Frameworks Version: 5.64.0
Qt Version: 5.13.2
KATE: 19.08.3

ADDITIONAL INFORMATION

Comment 1 Christoph Cullmann 2019-12-13 18:26:13 UTC

Hi, which file is used is decided by the version of it (for files of the same name).

If you increment the file version in the xml, does it work?

(this is done that way to allow e.g. local files of the user to be overruled if KTextEditor ships updates with higher versions)

Comment 2 Russell 2019-12-21 08:29:00 UTC

That worked.  

In my custom file, I changed the language attribute from 'version="2"' to 'version="992"'. The system file was at 'version="3"'. 

Would it be possible to change this to a documentation update for https://docs.kde.org/stable5/en/applications/katepart/highlight.html.

Documentation suggestion:

+++++++++++++
Custom .xml highlight definition files are located in org.kde.syntax-highlighting/syntax/ in your user folder found with qtpaths--paths GenericDataLocation which usually is $HOME/.local/share. Regarding the language element, if multiple .xml files on your system have the same name attribute, the file with the highest version attribute will be loaded. 
+++++++++++++

Comment 3 Christoph Cullmann 2019-12-21 15:12:52 UTC

Git commit afa4538b6412977d0aeb8f7a0c100a9f314df3ad by Christoph Cullmann.
Committed on 21/12/2019 at 15:12.
Pushed by cullmann into branch 'master'.

document that the version is important for the choice of the syntax definition to load

M  +2    -0    doc/katepart/development.docbook

https://invent.kde.org/kde/kate/commit/afa4538b6412977d0aeb8f7a0c100a9f314df3ad

Comment 4 Christoph Cullmann 2019-12-21 15:12:56 UTC

Git commit afa4538b6412977d0aeb8f7a0c100a9f314df3ad by Christoph Cullmann.
Committed on 21/12/2019 at 15:12.
Pushed by scmsync into branch 'master'.

document that the version is important for the choice of the syntax definition to load

M  +2    -0    doc/katepart/development.docbook

https://commits.kde.org/kate/afa4538b6412977d0aeb8f7a0c100a9f314df3ad

Comment 5 Christoph Cullmann 2019-12-21 15:14:28 UTC

Thanks for the suggestion!