docs(watermarker): create initial documentation (#86)

Co-authored-by: Malte Hellmeier <[email protected]>

cli/src/main/kotlin/Main.kt

@@ -288,7 +288,7 @@ fun Status.print() {
  *  - nop
  */
 fun Status.handle() {
-    if (this.isSuccess) {
+    if (isSuccess && !hasCustomMessage) {
         return
     }
 

docs/docs/03-usage/10-watermarker/01-installation.md

@@ -9,10 +9,18 @@ title: Installation
  that can be found in the LICENSE file.
 -->
 
-# Installation
+import PatentHint from './../../patent-hint.mdx'
+
+<PatentHint components={props.components} />
 
-_Follows soon._
+# Installation
 
 ## System Requirements
 
+**Java** is required to build the library with [Gradle](https://gradle.org/).
+
 ## Building from Source
+1. Clone the TREND repository
+2. Go into the directory of the watermarker: `cd TREND/watermarker`
+3. Build the library: `./gradlew build`
+4. Publish the artifacts locally: `./gradlew publishToMavenLocal`

docs/docs/03-usage/10-watermarker/02-kotlin.md

@@ -0,0 +1,143 @@
+---
+title: Kotlin
+---
+
+<!--
+ Copyright (c) 2024 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V.
+
+ This work is licensed under the Fraunhofer License (on the basis of the MIT license)
+ that can be found in the LICENSE file.
+-->
+
+import PatentHint from './../../patent-hint.mdx'
+
+<PatentHint components={props.components} />
+
+# Kotlin
+If you want to use watermarking inside your Kotlin project, this page gives you the necessary
+information.
+
+## Compile the Library
+See [Installation](../installation).
+
+## Example: Watermarking Text with Text
+Below you can see an example project that inserts a text as watermark into a cover text and then
+extracts the watermark from the watermarked text.
+
+### 1. Add Library as Dependency
+*Line 12 is the important line that adds our library as dependency into the project. Currently, we
+are working with local deployment, so you will have to add `mavenLocal()` as repo (line 8) and
+publish the library to mavenLocal (see [Installation](../installation)).*
+```kt title="build.gradle.kts" showLineNumbers
+plugins {
+    id("org.jetbrains.kotlin.jvm") version "2.0.0"
+    application
+}
+
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    implementation("de.fraunhofer.isst.trend:watermarker:0.1.0-SNAPSHOT")
+}
+
+application {
+    mainClass.set("MainKt")
+}
+```
+
+### 2. Use the Library
+*The extension functions `handle()` and `unwrap()` are optional for easy error handling with our
+custom return types (see [Concepts](../../../development/watermarker/concepts/#error-handling-1)
+for more details).*
+```kt title="src/main/kotlin/Main.kt" showLineNumbers
+import de.fraunhofer.isst.trend.watermarker.Watermarker
+import de.fraunhofer.isst.trend.watermarker.returnTypes.Result
+import de.fraunhofer.isst.trend.watermarker.returnTypes.Status
+import de.fraunhofer.isst.trend.watermarker.watermarks.TextWatermark
+import kotlin.system.exitProcess
+
+fun main() {
+    // *********************
+    // ***** INSERTION *****
+    // *********************
+
+    // the coverText should be enhanced with a watermark
+    val coverText =
+        "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " +
+            "incididunt ut labore et dolore magna aliqua. Blandit volutpat maecenas " +
+            "volutpat blandit aliquam etiam erat velit."
+    // the watermarkText is that watermark that will be included in the coverText above
+    val watermarkText = "Test"
+
+    // prepare watermarker
+    val watermarker = Watermarker()
+
+    // creating a watermark with text as content
+    val watermark = TextWatermark.new(watermarkText)
+
+    // inserting the watermark into the cover text and handling potential errors and warnings
+    val watermarkedText = watermarker.textAddWatermark(coverText, watermark).unwrap()
+
+    // print the watermarked text
+    println("watermarked text:")
+    println(watermarkedText)
+    println()
+
+    // **********************
+    // ***** Extraction *****
+    // **********************
+
+    // extract the watermark from the watermarked text
+    val extractedWatermarks = watermarker.textGetTextWatermarks(watermarkedText).unwrap()
+    check(extractedWatermarks.size == 1)
+    val extractedWatermark = extractedWatermarks[0]
+
+    // print the watermark text
+    println("Found a watermark in the text:")
+    println(extractedWatermark.text)
+
+}
+
+/**
+ * Handles a status depending on its variant:
+ * Variant Error:
+ *  - print error and exit with code -1
+ * Variant Warning:
+ *  - print warning
+ * Variant Success:
+ *  - nop
+ */
+fun Status.handle() {
+    if (isSuccess) {
+        return
+    }
+
+    println(this)
+
+    if (isError) {
+        exitProcess(-1)
+    }
+}
+
+/**
+ * Unwraps a Result depending on its variant:
+ * Variant Error:
+ *  - print error and exit with code -1
+ * Variant Warning:
+ *  - print warning
+ *  - return non-null value
+ * Variant Success:
+ *  - return non-null value
+ */
+fun <T> Result<T>.unwrap(): T {
+    status.handle()
+    checkNotNull(value) {
+        "A Result with a Status of type Success or Warning are expected to have a value"
+    }
+
+    return value!!
+}
+```

docs/docs/03-usage/10-watermarker/03-java.md

@@ -0,0 +1,151 @@
+---
+title: Java
+---
+
+<!--
+ Copyright (c) 2024 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V.
+
+ This work is licensed under the Fraunhofer License (on the basis of the MIT license)
+ that can be found in the LICENSE file.
+-->
+
+import PatentHint from './../../patent-hint.mdx'
+
+<PatentHint components={props.components} />
+
+# Java
+If you want to use watermarking inside your Java project, this page gives you the necessary
+information.
+
+## Compile the Library
+See [Installation](../installation).
+
+## Example: Watermarking Text with Text
+Below you can see an example project that inserts a text as watermark into a cover text and then
+extracts the watermark from the watermarked text.
+
+### 1. Add Library as Dependency
+*Line 11 is the important line that adds our library as dependency into the project. Currently, we
+are working with local deployment, so you will have to add `mavenLocal()` as repo (line 8) and
+publish the library to mavenLocal (see [Installation](../installation)).*
+```kt title="build.gradle.kts" showLineNumbers
+plugins {
+    application
+}
+
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    implementation("de.fraunhofer.isst.trend:watermarker:0.1.0-SNAPSHOT")
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}
+
+application {
+    mainClass.set("Main")
+}
+```
+
+### 2. Use the Library
+*The static functions `handle(...)` and `unwrap(...)` are optional for easy error handling with our
+custom return types (see [Concepts](../../../development/watermarker/concepts/#error-handling-1)
+for more details).*
+```java title="src/main/java/Main.java" showLineNumbers
+import de.fraunhofer.isst.trend.watermarker.Watermarker;
+import de.fraunhofer.isst.trend.watermarker.returnTypes.Result;
+import de.fraunhofer.isst.trend.watermarker.returnTypes.Status;
+import de.fraunhofer.isst.trend.watermarker.watermarks.TextWatermark;
+
+import java.util.List;
+
+
+public class Main {
+    public static void main(String[] args) {
+        // *********************
+        // ***** INSERTION *****
+        // *********************
+
+        // the coverText should be enhanced with a watermark
+        String coverText =
+                "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " +
+                        "incididunt ut labore et dolore magna aliqua. Blandit volutpat maecenas " +
+                        "volutpat blandit aliquam etiam erat velit.";
+        // the watermarkText is that watermark that will be included in the coverText above
+        String watermarkText = "Test";
+
+        // prepare watermarker
+        Watermarker watermarker = new Watermarker();
+
+        // creating a watermark with text as content
+        TextWatermark watermark = TextWatermark.Companion.create(watermarkText);
+
+        // inserting the watermark into the cover text and handling potential errors and warnings
+        String watermarkedText = unwrap(watermarker.textAddWatermark(coverText, watermark));
+
+        // print the watermarked text
+        System.out.println("watermarked text:");
+        System.out.println(watermarkedText);
+        System.out.println();
+
+        // **********************
+        // ***** Extraction *****
+        // **********************
+
+        // extract the watermark from the watermarked text
+        List<TextWatermark> extractedWatermarks =
+                unwrap(watermarker.textGetTextWatermarks(watermarkedText, true, false));
+        assert(extractedWatermarks.size() == 1);
+        TextWatermark extractedWatermark = extractedWatermarks.get(0);
+
+        // print the watermark text
+        System.out.println("Found a watermark in the text:");
+        System.out.println(extractedWatermark.getText());
+    }
+
+    /**
+     * Handles a status depending on its variant:
+     * Variant Error:
+     *  - print error and exit with code -1
+     * Variant Warning:
+     *  - print warning
+     * Variant Success:
+     *  - nop
+     */
+    public static void handle(Status status) {
+        if (status.isSuccess() && !status.getHasCustomMessage()) {
+            return;
+        }
+
+        System.out.println(status);
+
+        if (status.isError()) {
+            System.exit(-1);
+        }
+    }
+
+    /**
+     * Unwraps a Result depending on its variant:
+     * Variant Error:
+     *  - print error and exit with code -1
+     * Variant Warning:
+     *  - print warning
+     *  - return non-null value
+     * Variant Success:
+     *  - return non-null value
+     */
+    public static <T> T unwrap(Result<T> result) {
+        handle(result.getStatus());
+        assert result.getHasValue() :
+                "A Result with a Status of type Success or Warning are expected to have a value";
+
+        return result.getValue();
+    }
+}
+```

docs/docs/03-usage/10-watermarker/04-javascript.md

@@ -0,0 +1,71 @@
+---
+title: JavaScript
+---
+
+<!--
+ Copyright (c) 2024 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V.
+
+ This work is licensed under the Fraunhofer License (on the basis of the MIT license)
+ that can be found in the LICENSE file.
+-->
+
+import PatentHint from './../../patent-hint.mdx'
+
+<PatentHint components={props.components} />
+
+# JavaScript
+If you want to use watermarking inside your JavaScript project, this page gives you the necessary
+information.
+
+## Compile the Library
+See [Installation](../installation).
+
+
+## Plain JavaScript
+In order to use this library in plain JavaScript, follow these steps:
+
+1. Build the library ([see above](#compile-the-library))
+2. Import the generated JS library:
+   ```html
+   <script src='[relative-path-to]/TREND/watermarker/build/dist/js/productionExecutable/watermarker.js'></script>
+   ```
+3. This generates a variable `watermarker`s that provides access to the library functionalities.
+   However, the actual watermarker object is behind the package path and you might want to reassign
+   the watermarker variable to get rid of the long path like this:
+   ```js
+   watermarker = watermarker.de.fraunhofer.isst.trend.watermarker;
+   ```
+4. Now you are ready to use the watermarker in plain JS. An example HTML file can be found
+[in the repositories' examples](https://github.com/FraunhoferISST/TREND/blob/main/samples/plain_js/plain_js_minimal_example.html).
+
+You can open the file in the browser, no web server required.
+
+## JavaScript Modules
+In order to use this library in JavaScript modules, follow these steps:
+
+1. Build the library ([see above](#compile-the-library))
+2. Import the generated JS library according to your module system:
+
+   ```Javascript
+   // CommonJS (CJS)
+   let watermarker = require('[relative-path-to]/TREND/watermarker/build/dist/js/productionExecutable/watermarker.js'); // built as executable
+   // or
+   let watermarker = require('[relative-path-to]/TREND/watermarker/build/js/packages/watermarker/kotlin/watermarker.js'); // built as module
+
+   // ECMAScript Modules (ESM)
+   import watermarker from '[relative-path-to]/TREND/watermarker/build/dist/js/productionExecutable/watermarker.js'; // built as executable
+   // or
+   import watermarker from '[relative-path-to]/TREND/watermarker/build/js/packages/watermarker/kotlin/watermarker.js'; // built as module
+   ```
+
+3. This generates a variable `watermarker` that provides access to the library functionalities.
+   However, the actual watermarker object is behind the package path and you might want to reassign
+   the watermarker variable to get rid of the long path like this:
+   ```Javascript
+   watermarker = watermarker.de.fraunhofer.isst.trend.watermarker;
+   ```
+   *Note that imports in ESM are implicitly constant.*
+4. Now you are ready to use the watermarker in your module. An example node script can be found
+[in the repositories' examples](https://github.com/FraunhoferISST/TREND/blob/main/samples/js_modules/js_modules_minimal_example.js).
+
+Run it using `node npm_minimal_example.js`.