Update docs to new structure

.sdkmanrc

@@ -0,0 +1,2 @@
+java=24.0.1-tem
+#visualvm=2.1.10

build-logic/src/main/kotlin/buildlogic.java-common-conventions.gradle.kts

@@ -42,11 +42,11 @@ java {
         // - build.gradle -> jacoco -> toolVersion (because JaCoCo does not support newest JDK out of the box. Check versions at https://www.jacoco.org/jacoco/trunk/doc/changes.html)
         // - .devcontainer/devcontainer.json#L34 and
         // - .moderne/moderne.yml
-        // - .github/workflows/deployment*.yml
+        // - .github/workflows/binaries*.yml
         // - .github/workflows/tests*.yml
         // - .github/workflows/update-gradle-wrapper.yml
         // - docs/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-12-build.md
-        // - mise.toml
+        // - .sdkmanrc
         languageVersion = JavaLanguageVersion.of(24)
         // See https://docs.gradle.org/current/javadoc/org/gradle/jvm/toolchain/JvmVendorSpec.html for a full list
         // See https://docs.gradle.org/current/javadoc/org/gradle/jvm/toolchain/JvmVendorSpec.html for a full list

docs/code-howtos/bibtex.md

@@ -5,13 +5,15 @@ parent: Code Howtos
 
 The main class to handle a single BibTeX entry is `org.jabref.model.entry.BibEntry`.
 The content of a `.bib` file is handled in `org.jabref.model.database.BibDatabase`.
-Things not written in the `.bib` file, but required for handling are stored in `org.jabref.model.database.BibDatabaseContext`.
+The BibTeX contents (as in the `BibDatabase`) along with some metadata required for handling are stored in `org.jabref.model.database.BibDatabaseContext`.
 For instance, this stores the mode of the library, which can be BibTeX or `biblatex`.
 
 Standard BibTeX fields known to JabRef are modeled in `org.jabref.model.entry.field.StandardField`.
 A user-defined field not known to JabRef's code is modelled in `org.jabref.model.entry.field.UnknownField`.
 Typically, to get from a String to a `Field`, one needs to use `org.jabref.model.entry.field.FieldFactory#parseField(java.lang.String)`.
 
+Reading of `.bib` files is done in `org.jabref.logic.importer.fileformat.BibtexImporter`.
+
 ## Cross-references
 
 BibTeX allows for referencing other entries by the field `crossref` (`org.jabref.model.entry.field.StandardField#CROSSREF`).

docs/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-11-code-into-ide.md

@@ -6,39 +6,78 @@ nav_order: 11
 
 # Step 1: Get the code into IntelliJ
 
-Start IntelliJ.
+## IntelliJ Startup
+
+Start IntelliJ IDEA.
 
 IntelliJ shows the following window:
 
 {% figure caption:"IntelliJ Start Window" %}
 ![IntelliJ Start Window](guidelines-intellij-start-window.png)
 {% endfigure %}
 
+## Open the project
+
 Click on "Open"
 
-Choose `build.gradle` in the root of the jabref source folder:
+Choose `build.gradle.kts` in the root of the `jabref` source folder:
 
-{% figure caption:"Choose `build.gradle` in the “Open Project or File” dialog" %}
-![Open File or Project dialog](guidelines-intellij-choose-build-gradle.png)
+{% figure caption:"Choose `build.gradle.kts` in the “Open Project or File” dialog" %}
+![Open File or Project dialog](11-3-choose-build-gradle-kts.png)
 {% endfigure %}
 
-After pressing "OK", IntelliJ asks how that file should be opened.
+After clicking "Open," IntelliJ asks how that file should be opened.
 Answer: "Open as Project"
 
 {% figure caption:"Choose “Open as Project” in the Open Project dialog" %}
-![Open Project dialog](guidelines-choose-open-as-project.png)
+![Open Project dialog](11-4-guidelines-choose-open-as-project.png)
 {% endfigure %}
 
 Then, trust the project:
 
 {% figure caption:"Choose “Trust Project” in the “Trust and Open Project” dialog" %}
-![Trust and Open Project dialog](guidelines-trust-project.png)
+![Trust and Open Project dialog](12-05-guidelines-trust-project.png)
 {% endfigure %}
 
-## Ensure that committing via IntelliJ works
+## Confirm JDK Downloading
+
+IntelliJ asks for JDK downloading.
+Keep the suggested Java version and choose "Eclipse Temurin" as Vendor.
+Click "Download".
+
+{% figure caption:"Choose “Eclipse Temurin” in the “Download JDK” dialog" %}
+![Choose Eclipse Temurin](12-06-download-jdk-temurin.png)
+{% endfigure %}
 
-IntelliJ offers committing using the UI.
-Press <kbd>Alt</kbd>+<kbd>0</kbd> to open the commit dialog.
+## Allow JDK to access the internet
+
+Allow also access for both cases and click "Allow access".
+
+{% figure caption:"Trust JDK" %}
+![Windows Firewall JDK](12-07-trust-firewall.png)
+{% endfigure %}
+
+## Wait for IntelliJ IDEA to import the gradle project
+
+IntelliJ shows "Importing 'jabref' Gradle Project" at the lower right corner.
+This will take several minutes.
+Wait until this disappears.
+
+{% figure caption:"Importing 'jabref' Gradle Project" %}
+![Importing 'jabref' Gradle Project](12-08-importing-project.png)
+{% endfigure %}
+
+## IntelliJ IDEA will report low memory
+
+{% figure caption:"Low memory pop up" %}
+![alt text](12-09-low-memory.png)
+{% endfigure %}
+
+1. Click on "Configure".
+2. Set "2500" MB (instead of 1262) and click on "Save and Restart".
+3. Wait until IntelliJ is up and running again.
+
+## Ensure that committing via IntelliJ works
 
 Unfortunately, IntelliJ has no support for ignored sub modules [[IDEA-285237](https://youtrack.jetbrains.com/issue/IDEA-285237/ignored-changes-in-submodules-are-still-visible-in-the-commit-window)].
 Fortunately, there is a workaround:
@@ -49,32 +88,19 @@ Go to **File > Settings... > Version Control > Directory Mappings**.<br>
 Currently, it looks as follows:
 
 {% figure caption:"Directory Mappings unmodified" %}
-![Directory Mappings including sub modules](intellij-directory-mappings-unmodified.png)
+![Directory Mappings including sub modules](12-12-intellij-directory-mappings-unmodified.png)
 {% endfigure %}
 
 You need to tell IntelliJ to ignore the submodules `jablib\src\main\abbrv.jabref.org`, `jablib\src\main\resources\csl-locales`, and `jablib\src\main\resources\csl-styles`.
 Select all three (holding the <kbd>Ctrl</kbd> key).
-Then press the red minus button on top.
+Then press the minus button on top.
 
 This will make these directories "Unregistered roots:", which is fine.
 
 {% figure caption:"Directory Mappings having three unregistered roots" %}
-![Directory Mappings having three repositories unregistered](intellij-directory-mappings-unregistered-roots.png)
+![Directory Mappings having three repositories unregistered](12-13-intellij-directory-mappings-unregistered-roots.png)
 {% endfigure %}
 
-## Ensure that committing with other tools work
-
-Open a "git bash".
-On Windows, navigate to `C:\git-repositories\JabRef`.
-Open the context menu of the file explorer (using the right mouse button), choose "Open Git Bash here".
-
-Execute following command:
-
-```shell
-git update-index --assume-unchanged buildres/abbrv.jabref.org jablib/src/main/resources/csl-styles jablib/src/main/resources/csl-locales
-```
-
-{: .tip }
-If you do not see the context menu, re-install git following the steps given at [StackOverflow](https://stackoverflow.com/a/50667280/873282).
+Click "OK"
 
 <!-- markdownlint-disable-file MD033 -->

docs/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-12-build.md

@@ -6,90 +6,57 @@ nav_order: 12
 
 # Step 2: Set up the build system: JDK and Gradle
 
-## Ensure that JDK 23 is available to IntelliJ
+## Ensure that the project is synchronized
 
-Ensure you have a Java 23 SDK configured by navigating to **File > Project Structure... > Platform Settings > SDKs**.<br>
-**Note:** In some MacBooks, `Project Structure` can be found at the "IntelliJ" button of the app menu instead of at "File".
+Press the synchronization button in the gradle menu.
 
-{% figure caption:"JDKs 11, 14, and 15 shown in available SDKs. JDK 23 is missing." %}
-![Platform Settings - SDKs](intellij-choose-jdk-adoptopenjdk-on-windows-project-settings.png)
-{% endfigure %}
-
-If there is another JDK than JDK 23 selected, click on the plus button and choose "Download JDK..."
+1. Locate the gradle icon on the right side and click on it.
+2. Click on the arrows on the left side of this pane.
 
-{% figure caption:"Download JDK..." %}
-![Platform Settings - SDKs - plus button - Download JDK...](guidelines-select-download-jdk.png)
+{% figure caption:"Gradle sync button" %}
+![Platform Settings - SDKs](13-01-gradle-sync.png)
 {% endfigure %}
 
-Select JDK version 23 and then Eclipse Temurin.
+Press <kbd>Alt</kbd>+<kbd>1</kbd> to show the project view
 
-{% figure caption:"Example for JDK 23 - Choose Eclipse Temurin" %}
-![Download Eclipse Temurin](guidelines-intellij-select-jdk-eclipse-temurin.png)
-{% endfigure %}
+Then, on the left side the project folder is there:
 
-After clicking "Download", IntelliJ installs Eclipse Temurin:
-
-{% figure caption:"IntelliJ installs Eclipse Temurin" %}
-![IntelliJ installs Eclipse Temurin](guidelines-intellij-installs-temurin.png)
+{% figure caption:"Project folder" %}
+![Project folder](13-02-project-folder.png)
 {% endfigure %}
 
-Navigate to **Project Settings > Project** and ensure that the projects' SDK is Java 23.
+## Switch JDK to the latest one
 
-{% figure caption:"Project SDK is pinned to the downloaded SDK (showing JDK 23 as example)" %}
-![Project SDK is JDK 23](guidelines-intellij-project-settings-jdk.png)
-{% endfigure %}
+Open the module settings:
 
-Click "OK" to store the changes.
+1. Open the context menu of the project
+2. Choose "Open Module Settings"
 
-## Ensure correct JDK setting for Gradle
-
-Navigate to **File > Settings... > Build, Execution, Deployment > Build Tools > Gradle** and select the "Project SDK" as the Gradle JVM at the bottom.
-If that does not exist, just select JDK 23.
-
-{% figure caption:"Gradle JVM is project SDK (showing "Project SDK temurin-23" as example)" %}
-![Gradle JVM is project SDK](guidelines-intellij-settings-gradle-gradlejvm-is-projectjvm.png)
+{% figure caption:"Open Module Settings" %}
+![Open Module Settings](13-03-open-module-settings.png)
 {% endfigure %}
 
-## Enable compilation by IntelliJ
+Enable JDK 24:
 
-To prepare IntelliJ's build system additional steps are required:
+1. On the left, navigate to "Project".
+2. Choose "Download JDK..."
+3. Select version 24
+4. Select vendor "Eclipse Temurin"
+5. Click on "Download"
 
-Navigate to **Build, Execution, Deployment > Compiler > Java Compiler**, and under "Override compiler parameters per-module", click add (\[+]) and choose `JabRef.main`:
-
-{% figure caption:"Choose JabRef.main" %}
-![Gradle JVM is project SDK](guidelines-choose-module.png)
+{% figure caption:"Download Eclipse Temurin" %}
+![Download Eclipse Temurin](13-04-download-temurin.png)
 {% endfigure %}
 
-Copy following text into your clipboard:
+Finally enable the JDK:
 
-```text
---add-exports=javafx.controls/com.sun.javafx.scene.control=org.jabref
---add-exports=org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref
---add-reads org.jabref=org.apache.commons.csv
---add-reads org.jabref=org.fxmisc.flowless
---add-reads org.jabref=langchain4j.core
---add-reads org.jabref=langchain4j.open.ai
-```
-
-Then double click inside the cell "Compilation options".
-Press <kbd>Ctrl</kbd>+<kbd>A</kbd> to mark all text.
-Press <kbd>Ctrl</kbd>+<kbd>V</kbd> to paste all text.
-Press <kbd>Enter</kbd> to have the value really stored.
-Otherwise, it seems like the setting is stored, but it is not there if you reopen this preference dialog.
-
-Note: If you use the expand arrow, you need to press <kbd>Shift</kbd>+<kbd>Enter</kbd> to close the expansion and then <kbd>Enter</kbd> to commit the value.
-
-{% figure caption:"Resulting settings for module JabRef.main" %}
-![Overridden compiler parameters](guidelines-overridden-compiler-parameters.png)
-{% endfigure %}
-
-Then click on "Apply" to store the setting.
-
-Note: If this step is omitted, you will get: `java: package com.sun.javafx.scene.control is not visible (package com.sun.javafx.scene.control is declared in module javafx.controls, which does not export it to module org.jabref)`.
+1. Click "OK" to close the dialog "Project Structure".
+2. Wait for IntelliJ to index the new JDK.
+3. If IntelliJ crashes, restart it. At "Help > Memory Settings", increase the "Maximum Heap Size".
 
 ## Enable annotation processors
 
-Enable annotation processors by navigating to **Build, Execution, Deployment > Compiler > Annotation processors** and check "Enable annotation processing"
+Enable annotation processors by navigating to **File > Settings > Build, Execution, Deployment > Compiler > Annotation processors** and check "Enable annotation processing"
 
 {% figure caption:"Enabled annotation processing" %}
 ![Enable annotation processing](guidelines-intellij-enable-annotation-processing.png)
@@ -98,29 +65,23 @@ Enable annotation processors by navigating to **Build, Execution, Deployment > C
 ## Using Gradle from within IntelliJ IDEA
 
 {: .note }
-Ensuring JabRef builds with Gradle should always be the first step because, e.g. it generates additional sources that are required for compiling the code.
-
-Open the Gradle Tool Window with the small button that can usually be found on the right side of IDEA or navigate to **View > Tool Windows > Gradle**.
-In the Gradle Tool Window, press the "Reload All Gradle Projects" button to ensure that all settings are up-to-date with the setting changes.
+Ensuring JabRef builds with Gradle should always be the first step since this is the commonly supported way to build JabRef.
 
-{% figure caption:"Reload of Gradle project" %}
-![Highlighted reload button](guidelines-gradle-tool-windows-refresh.png)
-{% endfigure %}
-
-After that, you can use the Gradle Tool Window to build all parts of JabRef and run it.
-To do so, expand the JabRef project in the Gradle Tool Window and navigate to Tasks.
-From there, you can build and run JabRef by double-clicking **JabRef > Tasks > application > run**.
+Use the Gradle Tool Window to build all parts of JabRef and run it.
+To do so, expand the JabRef project in the Gradle Tool Window, navigate to "jabgui", expand it, navigate to "application", expand it, and double click "run".
 
 {% figure caption:"JabRef > Tasks > application > run" %}
-![JabRef > Tasks > application > run](guidelines-gradle-run.png)
+![JabRef > Tasks > application > run](13-05-run-gradle.png)
 {% endfigure %}
 
 The Gradle run window opens, shows compilation and then the output of JabRef.
 The spinner will run as long as JabRef is open.
 
-{% figure caption:"Gradle run Window" %}
-![Gradle run window](guidelines-gradle-run-output.png)
-{% endfigure %}
+You might get an out-of-memory-exception as follows:
+
+```text
+OpenJDK 64-Bit Server VM warning: INFO: os::commit_memory(0x00000000cb600000, 177209344, 0) failed; error='The paging file is too small for this operation to complete' (DOS error/errno=1455)
+```
 
 You can close JabRef again.
 
@@ -130,8 +91,45 @@ Now you can also select "jabref \[run]" and either run or debug the application
 {: .note }
 You can run any other development task similarly.
 
+## Enable compilation by IntelliJ
+
+This is currently not possible due to [IDEA-3733059](https://youtrack.jetbrains.com/issue/IDEA-373305).
+
+<!--
+
+To prepare IntelliJ's build system additional steps are required:
+
+Navigate to **File > Settings > Build, Execution, Deployment > Compiler > Java Compiler**, and under "Override compiler parameters per-module", click add (\[+]) and choose `JabRef`.
+
+Copy following text into your clipboard:
+
+```text
+--add-exports=javafx.controls/com.sun.javafx.scene.control=org.jabref
+--add-exports=org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref
+```
+
+Then double click inside the cell "Compilation options".
+Press <kbd>Ctrl</kbd>+<kbd>V</kbd> to paste all text.
+Press <kbd>Enter</kbd> to have the value really stored.
+Otherwise, it seems like the setting is stored, but it is not there if you reopen this preference dialog.
+
+Note: If you use the expand arrow, you need to press <kbd>Shift</kbd>+<kbd>Enter</kbd> to close the expansion and then <kbd>Enter</kbd> to commit the value.
+
+Then click on "Apply" to store the setting.
+
+Note: If this step is omitted, you will get: `java: package com.sun.javafx.scene.control is not visible (package com.sun.javafx.scene.control is declared in module javafx.controls, which does not export it to module org.jabref)`.
+
+IntelliJ prompts with "Back Up Your Settings".
+You can choose "Skip" here.
+
+-->
+
 ## Using IntelliJ's internal build system for tests
 
+This is currently not possible due to [IDEA-3733059](https://youtrack.jetbrains.com/issue/IDEA-373305).
+
+<!--
+
 In **File > Settings... > Build, Execution, Deployment > Build Tools > Gradle** the setting "Run tests using:" is set to "IntelliJ IDEA".
 
 {% figure caption:"IntelliJ setting: Run tests using IntelliJ" %}
@@ -150,6 +148,8 @@ This should happen without any error.
 
 Now you can use IntelliJ IDEA's internal build system by using **Build > Build Project**.
 
+-->
+
 ## Final build system checks
 
 To run an example test from IntelliJ, we let IntelliJ create a launch configuration:

docs/getting-into-the-code/guidelines-for-setting-up-a-local-workspace/intellij-89-run-with-intellij.md

@@ -6,6 +6,8 @@ nav_order: 89
 
 # Advanced: Build and run using IntelliJ IDEA
 
+Following is currently not possible due to [IDEA-3733059](https://youtrack.jetbrains.com/issue/IDEA-373305).
+
 In "Step 2: Setup the build system: JDK and Gradle", IntelliJ was configured to use Gradle as tool for launching JabRef.
 It is also possible to use IntelliJ's internal build and run system to launch JabRef.
 Due to [IDEA-119280](https://youtrack.jetbrains.com/issue/IDEA-119280), it is a bit more work.