runtime(java): Manage circularity for every :syn-included syntax file

With "g:markdown_fenced_languages" defined and "java" added
to its list, a circular dependency between the Markdown and
Java syntax files will be made.  To break it, no Markdown
documentation comments will be recognised in fenced blocks
in Markdown files; in order to view Java source files,
"java" must be removed from "g:markdown_fenced_languages",
and this task can be automated as follows.

1) Add to "~/.after/ftplugin/java.vim":
------------------------------------------------------------
if exists("g:markdown_fenced_languages") &&
	\ !(exists("g:java_ignore_javadoc") ||
	\ exists("g:java_ignore_markdown"))
    let s:idx = index(g:markdown_fenced_languages, 'java')
    if s:idx > -1
	call remove(g:markdown_fenced_languages, s:idx)
    endif
    unlet s:idx
endif
------------------------------------------------------------

2) Optionally add to "~/.after/ftplugin/markdown.vim":
------------------------------------------------------------
if exists("g:markdown_fenced_languages") &&
	\ index(g:markdown_fenced_languages, 'java') < 0
    call add(g:markdown_fenced_languages, 'java')
endif
------------------------------------------------------------

(Make sure that the above snippets appear in the files under
the "ftplugin" NOT "syntax" directory.)

Finally, unless the new version of the syntax file is made
available from "$VIMRUNTIME" (and from "~/.vim/syntax" if
necessary), OTHER discoverable file versions will be used
whose behaviour may interfere with this fix.

related: #15740
closes: #15796

Signed-off-by: Aliaksei Budavei <0x000c70@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
diff --git a/runtime/syntax/testdir/input/markdown_circularity.markdown b/runtime/syntax/testdir/input/markdown_circularity.markdown
new file mode 100644
index 0000000..8f442a9
--- /dev/null
+++ b/runtime/syntax/testdir/input/markdown_circularity.markdown
@@ -0,0 +1,54 @@
+No code is recognised in HTML snippets.
+
+~~~html
+<pre><code>
+/** HTML syntax circularity tests. */
+class HTMLSyntaxCircularityTests
+{
+    /// @hidden
+    ///
+    /// @param args optional command-line arguments
+    public static void main(String[] args)
+    {
+        System.out.println("""
+            ```java
+            class SyntaxCircularityTests
+            {
+                public static void main(String[] args)
+                {
+                    System.out.println(".");
+                }
+            }
+            ```
+        """);
+    }
+}
+</code></pre>
+~~~
+
+
+Markdown documentation comments are not recognised in Java snippets.
+
+```java
+/** Java syntax circularity tests. */
+class JavaSyntaxCircularityTests
+{
+    /// @hidden
+    ///
+    /// @param args optional command-line arguments
+    public static void main(String[] args)
+    {
+        System.out.println("""
+            <pre><code>
+            class SyntaxCircularityTests
+            {
+                public static void main(String[] args)
+                {
+                    System.out.println(".");
+                }
+            }
+            </code></pre>
+        """);
+    }
+}
+```