GitBook: [master] 23 pages modified

docs/README.md

@@ -1,51 +1,45 @@
 # Develop JabRef
 
-This page presents all development informatation around JabRef. For users documentation see <https://docs.jabref.org>.
+This page presents all development informatation around JabRef. For users documentation see [https://docs.jabref.org](https://docs.jabref.org).
 
 ## Excersises
 
-Uni Basel offers a German (🇩🇪) Software Engineering course which uses JabRef as one example.
-Look at [Exercise 5](https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week5/exercises/practical-exercises.md) for an exercise where some important points of JabRef are touched.
+Uni Basel offers a German \(🇩🇪\) Software Engineering course which uses JabRef as one example. Look at [Exercise 5](https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week5/exercises/practical-exercises.md) for an exercise where some important points of JabRef are touched.
 
 ## How tos
 
-- External: [Sync your fork with the JabRef repository](https://help.github.com/articles/syncing-a-fork/)
-- External (🇩🇪): Branches and pull requests: <https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md>
+* External: [Sync your fork with the JabRef repository](https://help.github.com/articles/syncing-a-fork/)
+* External \(🇩🇪\): Branches and pull requests: [https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md](https://github.com/unibas-marcelluethi/software-engineering/blob/master/docs/week2/exercises/practical-exercises.md)
 
 ## Command Line
 
 The package `org.jabref.cli` is responsible for handling the command line options.
 
 During development, one can configure IntelliJ to pass command line paramters:
 
-![IntelliJ-run-configuration](images/intellij-run-configuration-command-line.png)
+![IntelliJ-run-configuration](.gitbook/assets/intellij-run-configuration-command-line%20%282%29.png)
 
-Passing command line arguments using gradle is currently not possible as all arguments (such as `-Dfile.encoding=windows-1252`) are passed to the application.
+Passing command line arguments using gradle is currently not possible as all arguments \(such as `-Dfile.encoding=windows-1252`\) are passed to the application.
 
 Without jlink, it is not possible to generate a fat jar any more. During development, the capabilities of the IDE has to be used.
 
 ## Groups
 
-UML diagram showing aspects of groups: [Groups.uml](Gropus.uml).
+UML diagram showing aspects of groups: [Groups.uml](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/Gropus.uml).
 
 ## Decision Records
 
 This log lists the decisions for JabRef.
 
-<!-- adrlog -->
+* [ADR-0000](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records
+* [ADR-0001](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0001-use-crowdin-for-translations.md) - Use Crowdin for translations
+* [ADR-0002](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0002-use-slf4j-for-logging.md) - Use slf4j together with log4j2 for logging
+* [ADR-0003](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0003-use-gradle-as-build-tool.md) - Use Gradle as build tool
+* [ADR-0003](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0003-use-openjson-as-replacement-for-org-json.md) - Use openjson as replacement for org.json
+* [ADR-0004](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0004-use-mariadb-connector.md) - Use MariaDB Connector
+* [ADR-0005](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0005-fully-support-utf8-only-for-latex-files.md) - Fully Support UTF-8 Only For LaTeX Files
+* [ADR-0006](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0006-only-translated-strings-in-language-file.md) - Only translated strings in language file
+* [ADR-0007](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/0007-human-readable-changelog.md) - Provide a human-readable changelog
 
-- [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records
-- [ADR-0001](0001-use-crowdin-for-translations.md) - Use Crowdin for translations
-- [ADR-0002](0002-use-slf4j-for-logging.md) - Use slf4j together with log4j2 for logging
-- [ADR-0003](0003-use-gradle-as-build-tool.md) - Use Gradle as build tool
-- [ADR-0003](0003-use-openjson-as-replacement-for-org-json.md) - Use openjson as replacement for org.json
-- [ADR-0004](0004-use-mariadb-connector.md) - Use MariaDB Connector
-- [ADR-0005](0005-fully-support-utf8-only-for-latex-files.md) - Fully Support UTF-8 Only For LaTeX Files
-- [ADR-0006](0006-only-translated-strings-in-language-file.md) - Only translated strings in language file
-- [ADR-0007](0007-human-readable-changelog.md) - Provide a human-readable changelog
+For new ADRs, please use [docs/template.md](https://github.com/JabRef/jabref/tree/ec47f2138b0550a4622872d455902443cd56d9cc/docs/docs/template.md) as basis. More information on MADR is available at [https://adr.github.io/madr/](https://adr.github.io/madr/). General information about architectural decision records is available at [https://adr.github.io/](https://adr.github.io/).
 
-<!-- adrlogstop -->
-
-For new ADRs, please use [docs/template.md](docs/template.md) as basis.
-More information on MADR is available at <https://adr.github.io/madr/>.
-General information about architectural decision records is available at <https://adr.github.io/>.

docs/SUMMARY.md

@@ -0,0 +1,25 @@
+# Table of contents
+
+* [Develop JabRef](README.md)
+* [Architectural Decisions](adr/README.md)
+  * [Use Markdown Architectural Decision Records](adr/0000-use-markdown-architectural-decision-records.md)
+  * [Use Crowdin for translations](adr/0001-use-crowdin-for-translations.md)
+  * [Fully Support UTF-8 Only For LaTeX Files](adr/0005-fully-support-utf8-only-for-latex-files.md)
+  * [Only translated strings in language file](adr/0006-only-translated-strings-in-language-file.md)
+  * [Use MariaDB Connector](adr/0004-use-mariadb-connector.md)
+  * [Use slf4j together with log4j2 for logging](adr/0002-use-slf4j-for-logging.md)
+  * [\[short title of solved problem and solution\]](adr/template.md)
+  * [Provide a human-readable changelog](adr/0007-human-readable-changelog.md)
+  * [Use Gradle as build tool](adr/0003-use-gradle-as-build-tool.md)
+* [How to test](testing.md)
+* [Debugging jpackage installations](debugging-jpackage-installations.md)
+* [High-level documentation](high-level-documentation.md)
+* [JabRef's development strategy](development-strategy.md)
+* [Recommendations for UI design](ui-recommendations.md)
+* [Code Howtos](code-howtos.md)
+* [Code Quality](code-quality.md)
+* [Set up a local workspace](guidelines-for-setting-up-a-local-workspace.md)
+* [Custom SVG icons](custom-svg-icons.md)
+* [JavaFX](javafx.md)
+* [Useful development tooling](tools.md)
+

docs/adr/0000-use-markdown-architectural-decision-records.md

@@ -2,25 +2,28 @@
 
 ## Context and Problem Statement
 
-We want to record architectural decisions made in this project.
-Which format and structure should these records follow?
+We want to record architectural decisions made in this project. Which format and structure should these records follow?
 
 ## Considered Options
 
 * [MADR](https://adr.github.io/madr/) 2.1.2 – The Markdown Architectural Decision Records
 * [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
 * [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
-* Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+* Other templates listed at [https://github.com/joelparkerhenderson/architecture\_decision\_record](https://github.com/joelparkerhenderson/architecture_decision_record)
 * Formless – No conventions for file format and structure
 
 ## Decision Outcome
 
 Chosen option: "MADR 2.1.2", because
 
 * Implicit assumptions should be made explicit.
+
   Design documentation is important to enable people understanding the decisions later on.
+
   See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+
 * The MADR format is lean and fits our development style.
 * The MADR structure is comprehensible and facilitates usage & maintenance.
 * The MADR project is vivid.
 * Version 2.1.2 is the latest one available when starting to document ADRs.
+

docs/adr/0001-use-crowdin-for-translations.md

@@ -14,3 +14,4 @@ The JabRef UI is offered in multiple languages. It should be easy for translator
 ## Decision Outcome
 
 Chosen option: "Use Crowdin", because Crowdin is easy to use, integrates in our GitHub workflow, and is free for OSS projects.
+

docs/adr/0002-use-slf4j-for-logging.md

@@ -2,8 +2,7 @@
 
 ## Context and Problem Statement
 
-Up to version 4.1 JabRef uses apache-commons-logging 1.2 for logging errors and messages.
-However, this is not compatible with java 9 and is superseded by log4j.
+Up to version 4.1 JabRef uses apache-commons-logging 1.2 for logging errors and messages. However, this is not compatible with java 9 and is superseded by log4j.
 
 ## Decision Drivers
 
@@ -18,7 +17,7 @@ However, this is not compatible with java 9 and is superseded by log4j.
 
 ## Decision Outcome
 
-Chosen option: "SLF4J with Log4j2 binding", because comes out best (see below).
+Chosen option: "SLF4J with Log4j2 binding", because comes out best \(see below\).
 
 ## Pros and Cons of the Options
 
@@ -46,5 +45,3 @@ Chosen option: "SLF4J with Log4j2 binding", because comes out best (see below).
 * Bad, because Java 9 support only available in alpha
 * Bad, because different syntax than log4j/commons logging
 
-
-

docs/adr/0003-use-gradle-as-build-tool.md

@@ -57,4 +57,5 @@ Chosen option: "Gradle", because it is lean and fits our development style.
 
 ## Links
 
-* GADR: <https://github.com/adr/gadr-java/blob/master/gadr-java--build-tool.md>
+* GADR: [https://github.com/adr/gadr-java/blob/master/gadr-java--build-tool.md](https://github.com/adr/gadr-java/blob/master/gadr-java--build-tool.md)
+

docs/adr/0004-use-mariadb-connector.md

@@ -2,19 +2,18 @@
 
 ## Context and Problem Statement
 
-JabRef needs to connect to a MySQL database.
-See [Shared SQL Database](https://docs.jabref.org/collaborative-work/sqldatabase) for more information.
+JabRef needs to connect to a MySQL database. See [Shared SQL Database](https://docs.jabref.org/collaborative-work/sqldatabase) for more information.
 
 ## Considered Options
 
 * Use MariaDB Connector
 * Use MySQL Connector
 
-Other alternatives are listed at <https://stackoverflow.com/a/31312280/873282>.
+Other alternatives are listed at [https://stackoverflow.com/a/31312280/873282](https://stackoverflow.com/a/31312280/873282).
 
 ## Decision Outcome
 
-Chosen option: "Use MariaDB Connector", because comes out best (see below).
+Chosen option: "Use MariaDB Connector", because comes out best \(see below\).
 
 ## Pros and Cons of the Options
 
@@ -26,9 +25,8 @@ The [MariaDB Connector](https://mariadb.com/kb/en/library/about-mariadb-connecto
 
 ### Use MySQL Connector
 
-The [MySQL Connector](https://www.mysql.com/de/products/connector/) is distributed by Oracle and licensed under GPL-2. Source: <https://downloads.mysql.com/docs/licenses/connector-j-8.0-gpl-en.pdf>.
-Oracle added the [Universal FOSS Exception, Version 1.0](https://oss.oracle.com/licenses/universal-foss-exception/) to it, which seems to limit the effects of GPL.
-More information on the FOSS Exception are available at <https://www.mysql.com/de/about/legal/licensing/foss-exception/>.
+The [MySQL Connector](https://www.mysql.com/de/products/connector/) is distributed by Oracle and licensed under GPL-2. Source: [https://downloads.mysql.com/docs/licenses/connector-j-8.0-gpl-en.pdf](https://downloads.mysql.com/docs/licenses/connector-j-8.0-gpl-en.pdf). Oracle added the [Universal FOSS Exception, Version 1.0](https://oss.oracle.com/licenses/universal-foss-exception/) to it, which seems to limit the effects of GPL. More information on the FOSS Exception are available at [https://www.mysql.com/de/about/legal/licensing/foss-exception/](https://www.mysql.com/de/about/legal/licensing/foss-exception/).
 
 * Good, because it stems from the same development team than MySQL
 * Bad, because the "Universal FOSS Exception" makes licensing more complicated.
+

docs/adr/0005-fully-support-utf8-only-for-latex-files.md

@@ -2,18 +2,17 @@
 
 ## Context and Problem Statement
 
-The feature [search for citations](https://github.com/JabRef/user-documentation/issues/210) displays the content of LaTeX files.
-The LaTeX files are text files and might be encoded arbitrarily.
+The feature [search for citations](https://github.com/JabRef/user-documentation/issues/210) displays the content of LaTeX files. The LaTeX files are text files and might be encoded arbitrarily.
 
 ## Considered Options
 
 * Support UTF-8 encoding only
 * Support ASCII encoding only
-* Support (nearly) all encodings
+* Support \(nearly\) all encodings
 
 ## Decision Outcome
 
-Chosen option: "Support UTF-8 encoding only", because comes out best (see below).
+Chosen option: "Support UTF-8 encoding only", because comes out best \(see below\).
 
 ### Positive Consequences
 
@@ -36,9 +35,12 @@ Chosen option: "Support UTF-8 encoding only", because comes out best (see below)
 * Good, because easy to implement
 * Bad, because does not support any encoding at all
 
-### Support (nearly) all encodings
+### Support \(nearly\) all encodings
 
 * Good, because easy to implement
 * Bad, because it relies on Apache Tika's `CharsetDetector`, which resides in `tika-parsers`.
-  This causes issues during compilation (see https://github.com/JabRef/jabref/pull/3421#issuecomment-524532832).
+
+  This causes issues during compilation \(see [https://github.com/JabRef/jabref/pull/3421\#issuecomment-524532832](https://github.com/JabRef/jabref/pull/3421#issuecomment-524532832)\).
+
   Example: `error: module java.xml.bind reads package javax.activation from both java.activation and jakarta.activation`.
+

docs/adr/0006-only-translated-strings-in-language-file.md

@@ -2,15 +2,13 @@
 
 ## Context and Problem Statement
 
-JabRef has translation files `JabRef_it.properties`, ...
-There are translated and unstranslated strings.
-Which ones should be in the translation file?
+JabRef has translation files `JabRef_it.properties`, ... There are translated and unstranslated strings. Which ones should be in the translation file?
 
 ## Decision Drivers
 
 * Translators should find new strings to translate easily
 * New strings to translate should be written into `JabRef_en.properties` to enable translation by the translators
-* Crowdin should be kept as translation platform, because 1) it is much easier for the translators than the GitHub workflow and 2) it is free for OSS projects.
+* Crowdin should be kept as translation platform, because 1\) it is much easier for the translators than the GitHub workflow and 2\) it is free for OSS projects.
 
 ## Considered Options
 
@@ -20,15 +18,15 @@ Which ones should be in the translation file?
 
 ## Decision Outcome
 
-Chosen option: "Only translated strings in language file", because comes out best (see below.
+Chosen option: "Only translated strings in language file", because comes out best \(see below.
 
 ## Pros and Cons of the Options
 
 ### Only translated strings in language file
 
 * Good, because Crowdin supports it
 * Bad, because translators need tooling to see untranslated strings
-* Bad, because issues with FXML (https://github.com/JabRef/jabref/issues/3796)
+* Bad, because issues with FXML \([https://github.com/JabRef/jabref/issues/3796](https://github.com/JabRef/jabref/issues/3796)\)
 
 ### Translated and untranslated strings in language file, have value the untranslated string to indicate untranslated
 
@@ -39,9 +37,10 @@ Chosen option: "Only translated strings in language file", because comes out bes
 ### Translated and untranslated strings in language file, have empty to indicate untranslated
 
 * Good, because untranslated strings can be identified easily
-* Good, because works with FMXL (?)
+* Good, because works with FMXL \(?\)
 * Bad, because Crowdin does not support it
 
 ## Links
 
 * Related to [ADR-0001](0001-use-crowdin-for-translations.md).
+

docs/adr/0007-human-readable-changelog.md

@@ -2,8 +2,7 @@
 
 ## Context and Problem Statement
 
-Changes of a release have to be communicated.
-How and which stile to use?
+Changes of a release have to be communicated. How and which stile to use?
 
 ## Considered Options
 
@@ -14,9 +13,11 @@ How and which stile to use?
 
 Chosen option: "Keep-a-changelog format with freedom in the bullet points", because
 
-- [Keep-a-changelog](https://keepachangelog.com/) structures the changelog
-- Each entry can be structured to be understandable
-- Forcing to prefix each line with `We fixed`, `We changed`, ... seems to be read strange.
+* [Keep-a-changelog](https://keepachangelog.com/) structures the changelog
+* Each entry can be structured to be understandable
+* Forcing to prefix each line with `We fixed`, `We changed`, ... seems to be read strange.
+
   We nevertheless try to follow that style.
 
-Further discussion can be found at [#2277](https://github.com/JabRef/jabref/issues/2277).
+Further discussion can be found at [\#2277](https://github.com/JabRef/jabref/issues/2277).
+

docs/adr/README.md

@@ -2,6 +2,5 @@
 
 This directory contains the architectural decisions for JabRef.
 
-For new ADRs, please use [template.md](template.md) as basis.
-More information on the used format is available at <https://adr.github.io/madr/>.
-General information about architectural decision records is available at <https://adr.github.io/>.
+For new ADRs, please use [template.md](template.md) as basis. More information on the used format is available at [https://adr.github.io/madr/](https://adr.github.io/madr/). General information about architectural decision records is available at [https://adr.github.io/](https://adr.github.io/).
+