Completely refactor.

Add bmml syntax grammars and examples.
Upgrade to Gradle 9 and Java 17.

Author: wolandscat

.idea/.name

@@ -4,23 +4,61 @@ Antlr4 grammars for ADL, ODIN, BEL, EL, BMM.
 
 == Overview
 
-The grammars in this project are an attempt to systematise all grammars for openEHR in one place, and using common lexers for common patterns such as identifiers, paths, terminal values and so on. The grammars use modal lexers (example: https://github.com/openEHR/openEHR-antlr4/blob/master/combined/src/main/antlr/Adl2Lexer.g4[ADL2 lexer^]) to handle the multiple formalisms that may appear in e.g. ADL files, CADL blocks within ADL (which may have further embedded ODIN or JSON blocks) and so on.
+The grammars in this project are an attempt to systematise all grammars for openEHR in one place, and using common lexers for common patterns such as identifiers, paths, terminal values and so on. The grammars use modal lexers (example: https://github.com/openEHR/openEHR-antlr4/blob/master/reader_common/src/main/antlr/Adl2Lexer.g4[ADL2 lexer^]) to handle the multiple formalisms that may appear in e.g. ADL files, CADL blocks within ADL (which may have further embedded ODIN or JSON blocks) and so on.
 
 It is eventually intended to be used as the official source for grammars for various specifications, i.e. replacing existing grammars in the https://github.com/openEHR/adl-antlr[adl-antlr^] repository.
 
 == Status
 
 This is a development repository containing Antlr4 grammars for most of the languages and syntaxes in use in openEHR.
 
-== What's in the project?
+== How is the project structured?
 
-The grammars are maintained under the `combined/src/main/antlr` directory. The other modules may be ignored for the moment.
+This is a multi-module project, using gradle as the build system. IntelliJ is the usual IDE, but it is configured with gradle rather than the internal build and test.
+
+=== Build Design
+
+Building is set up with an attempt at best practices using gradle 9.1.0 or later. Common build specifications are in the gradle special module `buildSrc`, which contains a file `java-build-conventions.gradle`, which defines a plugin that can be re-used in all other modules using the following include:
+
+```
+plugins {
+    id("java-build-conventions")
+}
+```
+
+Building can be performed from the command line, e.g. within IntelliJ's terminal as follows:
+
+```
+./gradlew clean
+./gradlew build --continue
+```
+
+THe `--continue` switch above will ensure that a build continues across all modules, even if test cases fail post build of each module.
+
+=== Grammars
+
+The grammars are maintained in various modules:
+
+* the `reader_common/src/main/antlr` directory contains common reusable grammars, incuding some legacy ones;
+* the modules `reader_adl2`, `reader_adl14`, `reader_bmml` etc contain top-level grammars for complete languages, in files under `src/main/antlr`. Each of these modules re-uses the `reader_common` module grammars, via the `build.gradle` statement:
+
+```
+dependencies {
+    api project(':reader_common')
+}
+```
+
+NOTE: to use the Antlr plugin preview function for any of the top-level grammars, e.g. `bmml`, testing within te `reader_bmml` module will not work. Although there are gradle rules to make gradle pass the 'grammar import' directory to the antlr plug-in code generator during gradle building, the plugin previewer does not use the import directory, and cannot correctly evaluate a grammar in one of these modules, because it doesn't see the referenced grammars in `reader_common`. To run the previewer therefore, there is currently no option but to copy the grammar files from `reader_bmml`, `reader_adl2` etc, to the `antlr` directory in `reader_common` and do it there, followed by removing these files.
 
 == Testing
 
-A Java test program is in `/combined/src/test/java/org/openehr/adlReader`, and test files in `/combined/src/test/resources` .
+Each module contains its own test class(es) in `src/test/xxx` and test files, under `src/test/resources`, in the usual way.
+
+Common test utility code is in the module `test_fixtures`. Ideally it would be in `reader_common/src/testFixtures`, but this could not be made to work due to IntelliJ's documented inability to handle `testFixtures` properly (as of end 2025).
+
+The test cases are known to generally work using IntelliJ Idea 2025.x, with the Antlr4 4.13.1 plug-in (see top-level build.gradle file), and Java 17 JRE & JDK installed.
 
-The test cases are known to work using IntelliJ Idea 2021.2.2, with the Antlr4 4.10.1 plug-in (see top-level build.gradle file), and Java 11 JRE & JDK installed.
+To run the tests in `reader_adl2`, for example, use the test class  `reader_adl2/src/test/java/org/openehr/reader_adl2/Adl2ReaderTest.java`. A similar test class can be found in the other `reader_xxx` modules.
 
 == Related Specifications