Merge branch 'new-java-keywords' into 'master'

New java keywords

See merge request GNOME/gtksourceview!313

4 files changed, 285 insertions, 187 deletions

diff --git a/.editorconfig b/.editorconfig
index 6878369f..9bc0f641 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -14,3 +14,7 @@ tab_width = 8
 [meson.build]
 indent_size = 2
 indent_style = space
+
+[*.lang]
+indent_size = 2
+indent_style = space
diff --git a/data/language-specs/java.lang b/data/language-specs/java.lang
index de6b8b49..5dfcfec1 100644
--- a/data/language-specs/java.lang
+++ b/data/language-specs/java.lang
@@ -33,10 +33,12 @@
 
   <styles>
     <style id="comment"           name="Comment"                   map-to="def:comment"/>
+    <style id="doc-comment"       name="Documentation comment"     map-to="def:doc-comment"/>
     <style id="escaped-character" name="Escaped Character"         map-to="def:special-char"/>
     <style id="string"            name="String"                    map-to="def:string"/>
     <style id="char"              name="Character"                 map-to="def:character"/>
     <style id="external"          name="External"                  map-to="def:preprocessor"/>
+    <style id="annotation"        name="Annotation"                map-to="def:preprocessor"/>
     <style id="declaration"       name="Declaration"               map-to="def:type"/>
     <style id="storage-class"     name="Storage Class"             map-to="def:type"/>
     <style id="scope-declaration" name="Scope Declaration"         map-to="def:type"/>
@@ -58,6 +60,11 @@
       )
     </define-regex>
 
+    <context id="doc-comment" style-ref="doc-comment" class-disabled="no-spell-check" class="comment">
+      <start>/\*\*(?![\*/])</start>
+      <end>\*/</end>
+    </context>
+
     <context id="string" style-ref="string" end-at-line-end="true" class="string" class-disabled="no-spell-check">
       <start>"</start>
       <end>"</end>
@@ -68,13 +75,30 @@
       </include>
     </context>
 
-   <context id="char" style-ref="char">
-     <match>'(\%{escaped-character}|.)'</match>
-   </context>
+    <context id="char" style-ref="char">
+      <match>'((\%{escaped-character})|.)'</match>
+      <include>
+        <context sub-pattern="2" style-ref="escaped-character"/>
+      </include>
+    </context>
+
+    <context id="annotation" style-ref="annotation">
+      <match>@\w*</match>
+    </context>
 
     <context id="externals" style-ref="external">
+      <keyword>exports</keyword>
       <keyword>import</keyword>
+      <keyword>module</keyword>
+      <keyword>open</keyword>
+      <keyword>opens</keyword>
       <keyword>package</keyword>
+      <keyword>provides</keyword>
+      <keyword>requires</keyword>
+      <keyword>to</keyword>
+      <keyword>transitive</keyword>
+      <keyword>uses</keyword>
+      <keyword>with</keyword>
     </context>
 
     <context id="declarations" style-ref="declaration">
@@ -85,6 +109,10 @@
       <keyword>instanceof</keyword>
       <keyword>interface</keyword>
       <keyword>native</keyword>
+      <keyword>non-sealed</keyword>
+      <keyword>permits</keyword>
+      <keyword>record</keyword>
+      <keyword>sealed</keyword>
       <keyword>throws</keyword>
     </context>
 
@@ -97,6 +125,7 @@
       <keyword>int</keyword>
       <keyword>long</keyword>
       <keyword>short</keyword>
+      <keyword>var</keyword>
       <keyword>void</keyword>
     </context>
 
@@ -133,6 +162,7 @@
       <keyword>switch</keyword>
       <keyword>try</keyword>
       <keyword>while</keyword>
+      <keyword>yield</keyword>
     </context>
 
     <context id="memory" style-ref="keyword">
@@ -144,6 +174,7 @@
     <context id="future-reserved-words" style-ref="reserved">
       <keyword>const</keyword>
       <keyword>goto</keyword>
+      <keyword>_</keyword>
     </context>
 
     <context id="null-value" style-ref="null-value">
@@ -156,21 +187,24 @@
     </context>
 
     <context id="numeric" style-ref="number">
-      <match extended="true">
-        (\b([0-9]+|0[xX][0-9a-fA-F]+)[Ll]?\b|
-         \b(([0-9]+[Ee][-]?[0-9]+|
-            ([0-9]*\.[0-9]+|[0-9]+\.)([Ee][-]?[0-9]+)?)[fFdD]?|
-            [0-9]+[FfDd]))
+      <match extended="true" case-sensitive="false">
+        \b(
+          \d+[fd] |
+          ((\d*\.\d+|\d+\.)(e[-+]?\d+)?|\d+e[-+]?\d+)[fd]? |
+          (0x[\da-f]+|[1-9]\d*|0[0-7]*)l?
+        )
       </match>
     </context>
 
     <context id="java" class="no-spell-check">
       <include>
+        <context ref="doc-comment"/>
         <context ref="def:c-like-comment" style-ref="comment"/>
         <context ref="def:c-like-comment-multiline" style-ref="comment"/>
         <context ref="def:c-like-close-comment-outside-comment"/>
         <context ref="string"/>
         <context ref="char"/>
+        <context ref="annotation"/>
         <context ref="externals"/>
         <context ref="declarations"/>
         <context ref="primitive-types"/>
diff --git a/docs/lang-reference.md b/docs/lang-reference.md
index 45487266..cd532abc 100644
--- a/docs/lang-reference.md
+++ b/docs/lang-reference.md
@@ -22,7 +22,7 @@ The preinstalled language files are located in
 `${PREFIX}/share/gtksourceview-${GSV_API_VERSION}/language-specs/`. Custom
 user languages are usually placed in
 `~/.local/share/gtksourceview-${GSV_API_VERSION}/language-specs/`. Note:
-replace ${GSV_API_VERSION} with 2.0 or 3.0 in the path for GtkSourceView version
+replace `${GSV_API_VERSION}` with 2.0 or 3.0 in the path for GtkSourceView version
 2 or version 3.
 
 ## Some advices
@@ -60,9 +60,9 @@ GtkSourceView.
 - LGPL v2.1+ license (copy/paste the license header from c.lang, for example).
 - Add the e-mail address of the language definition file author(s).
 - Refer to the HACKING file for submitting your language definition
-file upstream. If the file is not included upstream, you can also
-add the language definition file to the GtkSourceView wiki, so
-users can easily find it.
+  file upstream. If the file is not included upstream, you can also
+  add the language definition file to the GtkSourceView wiki, so
+  users can easily find it.
 
 ## Tag `<language>`
 
@@ -80,39 +80,39 @@ Contained elements:
 
 - `id` (mandatory)
 
-Identifier for the description. This is used for
-external references and must be unique among language descriptions. It can
-contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  Identifier for the description. This is used for
+  external references and must be unique among language descriptions. It can
+  contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
 - `name` or `_name` (mandatory)
 
-The name of the language presented to the user. With `_name`, the
-string is marked for translation (see the gettext documentation).
+  The name of the language presented to the user. With `_name`, the
+  string is marked for translation (see the gettext documentation).
 
-The name should be marked for translation only if: (1) it contains a common
-English word, for example "C++ header" should be translated, but not "C++"
-or "XML". Or (2) if the name contains several words, because in some
-languages the word order should be different, for example "LLVM IR" or "RPM
-spec" should also be marked for translation.
+  The name should be marked for translation only if: (1) it contains a common
+  English word, for example "C++ header" should be translated, but not "C++"
+  or "XML". Or (2) if the name contains several words, because in some
+  languages the word order should be different, for example "LLVM IR" or "RPM
+  spec" should also be marked for translation.
 
 - `version` (mandatory)
 
-The version of the XML format (currently "2.0").
+  The version of the XML format (currently "2.0").
 
 - `section` or `_section` (optional)
 
-The category in which the language has to be grouped when presented to the user.
-With `_section` the string is marked for translation. Currently used
-categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
-"Other", but it is possible to use arbitrary categories (while usually
-discouraged). The convention in GtkSourceView is to use `_section`.
+  The category in which the language has to be grouped when presented to the user.
+  With `_section` the string is marked for translation. Currently used
+  categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
+  "Other", but it is possible to use arbitrary categories (while usually
+  discouraged). The convention in GtkSourceView is to use `_section`.
 
 - `hidden` (optional)
 
-It's a hint that the language should be "hidden" from user. For instance,
-def.lang has this flag, and a text editor should not present "default" as
-a syntax highlighting choice.
+  It's a hint that the language should be "hidden" from user. For instance,
+  def.lang has this flag, and a text editor should not present "default" as
+  a syntax highlighting choice.
 
 ## Tag `<metadata>`
 
@@ -122,33 +122,33 @@ Recognized elements are (all optional):
 
 - `mimetypes`
 
-The semicolon-separated list of mimetypes associated to the language. See the
-[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/)
-freedesktop.org specification. A language definition file shipped by
-GtkSourceView needs to have a mimetype defined in the shared-mime-info
-database. If the language definition file is not shipped by GtkSourceView, you
-can also create the mimetype locally, usually in
-`~/.local/share/mime/packages/`.
+  The semicolon-separated list of mimetypes associated to the language. See the
+  [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec/)
+  freedesktop.org specification. A language definition file shipped by
+  GtkSourceView needs to have a mimetype defined in the shared-mime-info
+  database. If the language definition file is not shipped by GtkSourceView, you
+  can also create the mimetype locally, usually in
+  `~/.local/share/mime/packages/`.
 
 - `globs`
 
-The semicolon-separated list of globs associated to the language.
+  The semicolon-separated list of globs associated to the language.
 
 - `line-comment-start`
 
-String used to create single-line comment in files of this type, e.g.
-"#" in shell scripts.
-It may be used in an editor to implement Comment/Uncomment functionality.
+  String used to create single-line comment in files of this type, e.g.
+  "#" in shell scripts.
+  It may be used in an editor to implement Comment/Uncomment functionality.
 
 - `block-comment-start`
 
-String used to start block comment in files of this type, e.g. "/*" in C
-files.
+  String used to start block comment in files of this type, e.g. "/*" in C
+  files.
 
 - `block-comment-end`
 
-String used to end block comment in files of this type, e.g. "*/" in C
-files.
+  String used to end block comment in files of this type, e.g. "*/" in C
+  files.
 
 ## Tag `<styles>`
 
@@ -166,37 +166,37 @@ Contained elements: none.
 
 ### Attributes
 
--`id` (mandatory)
-
-Identifier for the style. This is used in the current language
-to refer to this style and must be unique for the current document.
-It can contain a string of letters, digits,
-hyphens ("`-`") and underscores ("`_`").
-
--`name` or `_name` (mandatory)
-
-The user visible name for the style. With `_name` the string is
-marked for translation.
-  
-The convention in GtkSourceView is to **never** mark those
-strings for translation because they are extremely rarely used in the UI of
-an application (for example it could be used by a GUI tool to edit or create
-style schemes, but it is not really useful beyond that), and because those
-strings would be hard to translate (as a result, if those strings are
-translated, in practice they would often be translated in a way that the
-user doesn't understand what it means; for example for the C language,
-"include" or "define" should not be translated, those are keywords of the
-programming language).
-
--`map-to` (optional)
-
-Used to map the style with a default style, to use colors and
-font properties defined for those default styles.
-The id of the default style has to be preceded with the id of the
-language where it is defined, separated with a semicolon ":".
-When omitted the style is not considered derived from any style and will
-not be highlighted until the user specifies a color scheme for this
-style.
+- `id` (mandatory)
+
+  Identifier for the style. This is used in the current language
+  to refer to this style and must be unique for the current document.
+  It can contain a string of letters, digits,
+  hyphens ("`-`") and underscores ("`_`").
+
+- `name` or `_name` (mandatory)
+
+  The user visible name for the style. With `_name` the string is
+  marked for translation.
+
+  The convention in GtkSourceView is to **never** mark those
+  strings for translation because they are extremely rarely used in the UI of
+  an application (for example it could be used by a GUI tool to edit or create
+  style schemes, but it is not really useful beyond that), and because those
+  strings would be hard to translate (as a result, if those strings are
+  translated, in practice they would often be translated in a way that the
+  user doesn't understand what it means; for example for the C language,
+  "include" or "define" should not be translated, those are keywords of the
+  programming language).
+
+- `map-to` (optional)
+
+  Used to map the style with a default style, to use colors and
+  font properties defined for those default styles.
+  The id of the default style has to be preceded with the id of the
+  language where it is defined, separated with a semicolon ":".
+  When omitted the style is not considered derived from any style and will
+  not be highlighted until the user specifies a color scheme for this
+  style.
 
 ## Tag `<keyword-char-class>`
 
@@ -215,24 +215,24 @@ Contained elements: none.
 
 ### Attributes
 
--`case-sensitive` (optional)
+- `case-sensitive` (optional)
 
-Set to `false` to make regular expressions ignore case.
-Defaults to `true`.
+  Set to `false` to make regular expressions ignore case.
+  Defaults to `true`.
 
--`extended` (optional)
+- `extended` (optional)
 
-Setting this to `true` makes the regular
-expression engine ignore spaces and comments. These comments start with
-"`#`" and continue to the end of the line.
-Defaults to `false`.
+  Setting this to `true` makes the regular
+  expression engine ignore spaces and comments. These comments start with
+  "`#`" and continue to the end of the line.
+  Defaults to `false`.
 
--`dupnames` (optional)
+- `dupnames` (optional)
 
-Setting this to true allows one to repeat an identifier
-for capturing parentheses.  This is useful for some patterns that you
-know only one instance of a named subpattern can ever be matched.
-Defaults to `false`.
+  Setting this to true allows one to repeat an identifier
+  for capturing parentheses.  This is useful for some patterns that you
+  know only one instance of a named subpattern can ever be matched.
+  Defaults to `false`.
 
 ## Tag `<definitions>`
 
@@ -255,7 +255,8 @@ Contained elements:
 ## Tag `<define-regex>`
 
 The syntax highlighting engine of GtkSourceView uses [struct@GLib.Regex],
-which uses the PCRE library. See the [Regular expression syntax](https://developer.gnome.org/glib/stable/glib-regex-syntax.html)
+which uses the PCRE library. See the
+[Regular expression syntax](https://developer-old.gnome.org/glib/stable/glib-regex-syntax.html)
 page in the GLib reference manual.
 
 The `<define-regex>` tag defines a regular expression that can
@@ -270,10 +271,10 @@ element. To disable a group of options, instead, you have to prepend an hyphen
 the standard Perl style regular expressions:
 
 - `\%[` and `\%]` are custom word boundaries, which can
-be redefined with the `<keyword-char-class>` (in contrast with `\b`);
+  be redefined with the `<keyword-char-class>` (in contrast with `\b`);
 
 - `\%{id}` will include the regular expression defined in another
-`<define-regex>` element with the specified id.
+  `<define-regex>` element with the specified id.
 
 It is allowed to use any of the attributes from `<default-regex-options>` as attributes of this tag.
 
@@ -283,10 +284,10 @@ Contained elements: none.
 
 - `id` (mandatory)
 
-Identifier for the regular expression. This is used
-for the inclusion of the defined regular expression and must be unique
-for the current document. It can contain a string of letters, digits,
-hyphens ("`-`") and underscores ("`_`").
+  Identifier for the regular expression. This is used
+  for the inclusion of the defined regular expression and must be unique
+  for the current document. It can contain a string of letters, digits,
+  hyphens ("`-`") and underscores ("`_`").
 
 ## Tag `<context>`
 
@@ -323,45 +324,45 @@ Contained elements:
 
 - `id` (optional)
 
-A unique identifier for the context, used in references to the context. It
-can contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  A unique identifier for the context, used in references to the context. It
+  can contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
 - `style-ref` (optional)
 
-Highlighting style for this context. Value of this attribute
-may be id of a style defined in current lang file, or id of a style
-defined in other files prefixed with corresponding language id,
-e.g. "def:comment".
+  Highlighting style for this context. Value of this attribute
+  may be id of a style defined in current lang file, or id of a style
+  defined in other files prefixed with corresponding language id,
+  e.g. "def:comment".
 
 - `extend-parent` (optional)
 
-A boolean value telling the engine whether the context has higher
-priority than the end of its parent. If not specified it defaults to
-`true`.
+  A boolean value telling the engine whether the context has higher
+  priority than the end of its parent. If not specified it defaults to
+  `true`.
 
-`end-parent` (optional)
+- `end-parent` (optional)
 
-A boolean value telling the engine whether the context terminates parent context.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context terminates parent context.
+  If not specified it defaults to `false`.
 
 - `first-line-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-on the first line of buffer. If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  on the first line of buffer. If not specified it defaults to `false`.
 
 - `once-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-once in its parent. If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  once in its parent. If not specified it defaults to `false`.
 
 - `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
 - `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Container contexts
 
@@ -383,62 +384,62 @@ Contained elements:
 
 ### Attributes
 
--`id` (mandatory only if `<start>` not present)
+- `id` (mandatory only if `<start>` not present)
 
-A unique identifier for the context, used in references to the context. It
-can contain a string of letters, digits, hyphens ("`-`") and
-underscores ("`_`").
+  A unique identifier for the context, used in references to the context. It
+  can contain a string of letters, digits, hyphens ("`-`") and
+  underscores ("`_`").
 
--`style-ref` (optional)
+- `style-ref` (optional)
 
-Highlighting style for this context. Value of this attribute
-may be id of a style defined in current lang file, or id of a style
-defined in other files prefixed with corresponding language id,
-e.g. "def:comment".
+  Highlighting style for this context. Value of this attribute
+  may be id of a style defined in current lang file, or id of a style
+  defined in other files prefixed with corresponding language id,
+  e.g. "def:comment".
 
--`style-inside` (optional)
+- `style-inside` (optional)
 
-If this attribute is "true", then the highlighting style will
-be applied to the area between start and end matches; otherwise
-whole context will be highlighted.
+  If this attribute is "true", then the highlighting style will
+  be applied to the area between start and end matches; otherwise
+  whole context will be highlighted.
 
--`extend-parent` (optional)
+- `extend-parent` (optional)
 
-A boolean value telling the engine whether the context has a higher
-priority than the end of its parent. If not specified it defaults to
-`true`.
+  A boolean value telling the engine whether the context has a higher
+  priority than the end of its parent. If not specified it defaults to
+  `true`.
 
--`end-at-line-end` (optional)
+- `end-at-line-end` (optional)
 
-A boolean value telling the engine whether the context must be forced
-to end at the end of the line. If not specified it defaults to
-`false`.
+  A boolean value telling the engine whether the context must be forced
+  to end at the end of the line. If not specified it defaults to
+  `false`.
 
--`end-parent` (optional)
+- `end-parent` (optional)
 
-A boolean value telling the engine whether the context terminates parent context
-when it ends.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context terminates parent context
+  when it ends.
+  If not specified it defaults to `false`.
 
--`first-line-only` (optional)
+- `first-line-only` (optional)
 
 A boolean value telling the engine whether the context can start only
 on the first line of buffer. If not specified it defaults to `false`.
 
--`once-only` (optional)
+- `once-only` (optional)
 
-A boolean value telling the engine whether the context can occur only
-once in its parent. For a container context, it means that
-**each** included context can occur once.
-If not specified it defaults to `false`.
+  A boolean value telling the engine whether the context can occur only
+  once in its parent. For a container context, it means that
+  **each** included context can occur once.
+  If not specified it defaults to `false`.
 
--`class` (optional)
+- `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
--`class-disabled` (optional)
+- `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Sub-pattern contexts
 
@@ -450,32 +451,32 @@ Contained elements: none.
 
 ### Attributes
 
--`id` (optional)
+- `id` (optional)
 
-A unique identifier for the context. It can contain a string of letters,
-digits, hyphens ("`-`") and underscores ("`_`").
+  A unique identifier for the context. It can contain a string of letters,
+  digits, hyphens ("`-`") and underscores ("`_`").
 
--`sub-pattern` (mandatory)
+- `sub-pattern` (mandatory)
 
-The sub-pattern to which we refer. "0" means the whole expression, "1" the
-first group, "2" the second one, etc. If named sub-patterns are used you can
-also use the name.
+  The sub-pattern to which we refer. "0" means the whole expression, "1" the
+  first group, "2" the second one, etc. If named sub-patterns are used you can
+  also use the name.
 
--`where` (mandatory only in container contexts)
+- `where` (mandatory only in container contexts)
 
-Can be "`start`" or "`end`". It has to be used
-only if the parent is a container context to specify whether the
-sub-pattern is in the regular
-expression of the `<start>` or the `<end>`
-element. In simple contexts it must be omitted.
+  Can be "`start`" or "`end`". It has to be used
+  only if the parent is a container context to specify whether the
+  sub-pattern is in the regular
+  expression of the `<start>` or the `<end>`
+  element. In simple contexts it must be omitted.
 
--`class` (optional)
+- `class` (optional)
 
-A space-separated list of context classes to enable.
+  A space-separated list of context classes to enable.
 
--`class-disabled` (optional)
+- `class-disabled` (optional)
 
-A space-separated list of context classes to disable.
+  A space-separated list of context classes to disable.
 
 ## Reference contexts
 
@@ -487,28 +488,28 @@ Contained elements: none.
 
 - `ref` (mandatory)
 
-The id of the context to be included. A colon followed by an asterisk
-("`:*`") at the end of the id means that the parent should include
-every children of the specified context, instead of the context itself.
-Prepending the id of another language to the id of the context (separated
-with a semicolon ":") is possible to include contexts defined inside such
-external language.
+  The id of the context to be included. A colon followed by an asterisk
+  ("`:*`") at the end of the id means that the parent should include
+  every children of the specified context, instead of the context itself.
+  Prepending the id of another language to the id of the context (separated
+  with a semicolon ":") is possible to include contexts defined inside such
+  external language.
 
 - `style-ref` (optional)
 
-Style in included context may be overridden by using this attribute.
-Its value is id of the style to be used instead of style specified
-in the referenced context.
+  Style in included context may be overridden by using this attribute.
+  Its value is id of the style to be used instead of style specified
+  in the referenced context.
 
 - `ignore-style` (optional)
 
-If this attribute is "true" then the referenced context will not
-be highlighted. It does not affect child contexts and their styles.
+  If this attribute is "true" then the referenced context will not
+  be highlighted. It does not affect child contexts and their styles.
 
--`original` (optional)
+- `original` (optional)
 
-If this attribute is "true", it references the original context, if it
-has been replaced with the `<replace>` tag.
+  If this attribute is "true", it references the original context, if it
+  has been replaced with the `<replace>` tag.
 
 ## Keyword contexts
 
@@ -576,7 +577,8 @@ implement shell-style here-documents with this code:
 </context>
 ```
 
-It is also possible to use any of the attributes from `<default-regex-options>` as attributes of this tag.
+It is also possible to use any of the attributes from
+`<default-regex-options>` as attributes of this tag.
 
 Contained elements: none.
 
@@ -609,7 +611,8 @@ The replace tag allows you to change one context so it functions as
 another context.  For example, in the `html.lang` definition,
 there are a few references to a null context with id
 "`embedded-lang-hook`".  In `php.lang`, that context is
-replaced like this: `<replace id="html:embedded-lang-hook" ref="php-block">`, so that php blocks are recognized within the
+replaced like this: `<replace id="html:embedded-lang-hook" ref="php-block">`,
+so that php blocks are recognized within the
 `html:html` context at the points where the
 `embedded-lang-hook` context appears.
 
@@ -619,8 +622,8 @@ Contained elements: none.
 
 - `id` (mandatory)
 
-The id of the context to replace. Ex: `id="html:embedded-lang-hook"`
+  The id of the context to replace. Ex: `id="html:embedded-lang-hook"`
 
 - `ref` (mandatory)
 
-The id of the context to put in place of the context being replaced. Ex: `ref="php-block"`
+  The id of the context to put in place of the context being replaced. Ex: `ref="php-block"`
diff --git a/tests/syntax-highlighting/file.java b/tests/syntax-highlighting/file.java
new file mode 100644
index 00000000..263aa733
--- /dev/null
+++ b/tests/syntax-highlighting/file.java
@@ -0,0 +1,57 @@
+// This file should compile and execute
+
+import static java.lang.System.out;
+
+interface I {
+    void foo();
+    String[] bar(boolean okay);
+}
+
+abstract class C implements I {
+    public static void println(String str) {
+        out.println(str);
+    }
+
+    @Override
+    public void foo() {}
+}
+
+enum E { YEAH }
+
+/** Do you document your API?
+ * @param fake Oh no!
+ * @return What?
+ */
+record R<T>(int i, double d, char c, Object o, T special) {
+    private static final byte thing = 0;
+}
+
+public final class /* the same as the file name */ file extends C {
+    @Override
+    public String[] bar(boolean okay) {
+        return new String[] {
+            "Float: " + 1f + " or " + 1.e+0f,
+            "Double: " + 1d + " or " + 1.0e-0d,
+            "Long: " + 1L + " or " + 0x1l,
+            "Unsigned: don’t exist in Java",
+            "Escaped chars: \\ \" \101 " + '\141',
+        };
+    }
+
+    public static void main(String[] args) {
+        println(E.YEAH.toString());
+        var me = new file();
+        me.foo();
+        for (var wysiwyg: me.bar(false)) {
+            println(wysiwyg);
+        }
+        while (me != null) {
+            me = null;
+        }
+        var what = switch ("hey") {
+                case "" -> "";
+                default -> { yield "Have fun\u0021"; }
+            };
+        println(what.toUpperCase());
+    }
+}