Merge branch 'Phu2-master' into 28-use-jekyll-theme

.github/workflows/jekyll.yml

@@ -0,0 +1,64 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@8575951200e472d5f2d95c625da0c7bec8217c42 # v1.161.0
+        with:
+          ruby-version: '3.1' # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v4
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

_config.yml

@@ -0,0 +1,33 @@
+title: Metafacture Documentation
+description: This is the central place for the documentation about Metafacture.
+theme: just-the-docs
+
+url: https://Phu2.github.io/metafacture-documentation
+
+aux_links:
+  Metafacture Documentation on Github: https://github.com/Phu2/metafacture-documentation
+
+# Set a path/url to a logo that will be displayed instead of the title
+logo: "/assets/images/metafacture_small.png"
+favicon_ico: "/assets/images/favicon.ico"
+
+# Footer content
+# appears at the bottom of every page's main content
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+footer_content: "Metafacture Documentation is maintained by the <a href=\"https://lobid.org/team-en/\">Open infrastructure team of hbz.</a>"
+
+# Footer last edited timestamp
+last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
+last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
+
+# Custom colors, see _sass/color_schemes/metafacture.scss
+color_scheme: metafacture
+
+# see https://just-the-docs.github.io/just-the-docs/docs/search/#search-granularity
+search:
+  heading_level: 6
+  previews: 6

_sass/color_schemes/metafacture.scss

@@ -0,0 +1 @@
+$link-color: #4183c4;

_sass/custom/custom.scss

@@ -0,0 +1,4 @@
+h4 {font-size: 1rem !important;}
+h5 {
+    font-size: 1.5rem !important;
+}

Approaching a transformation with metafacture.md → docs/Approaching a transformation with metafacture.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Approaching a transformation with metafacture
+nav_order: 4
+---
+
 Every approach to transform metadata with metafacture is quite similiar:
 
 - You need to know the type and source of the input and the type and destination of the output:

Documentation-Maintainer-Guide.md → docs/Documentation-Maintainer-Guide.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Maintainer Guide
+nav_order: 8
+---
+
+# Maintainer Guide
 
 ## how to change flux-commands.md
 

Getting-Started.md → docs/Getting-Started.md

@@ -1,17 +1,20 @@
-![logo](https://github.com/culturegraph/metafacture-core/wiki/img/metafacture_small.png)
-
+---
+layout: default
+title: Getting Started
+nav_order: 2
+---
 
 # Getting started!
 
 ## Playground
 
 The easiest way to get started with Metafacture is the Playground. Take a look at the [first example](https://metafacture.org/playground/?flux=PG_DATA%0A%7Cas-lines%0A%7Cdecode-formeta%0A%7Cfix%0A%7Cencode-xml%28rootTag%3D%22collection%22%29%0A%7Cprint%0A%3B&fix=move_field%28_id%2C+id%29%0Amove_field%28a%2C+title%29%0Apaste%28author%2C+b.v%2C+b.n%2C+%27~aus%27%2C+c%29%0Aretain%28id%2C+title%2C+author%29&data=1%7Ba%3A+Faust%2C+b+%7Bn%3A+Goethe%2C+v%3A+JW%7D%2C+c%3A+Weimar%7D%0A2%7Ba%3A+R%C3%A4uber%2C+b+%7Bn%3A+Schiller%2C+v%3A+F%7D%2C+c%3A+Weimar%7D&active-editor=fix) and run it by pressing the !["Process"](https://metafacture.org/img/process.png) button. Check out the other examples (first button, !["Load Examples"](https://metafacture.org/img/load-exmples.png)) for different input sources, transformations, and output formats.
 
-For commands available in the Flux, see [the Flux commands documentation](/flux-commands.md).
+For commands available in the Flux, see [the Flux commands documentation](/docs/flux/flux-commands.html).
 
-For functions and usage of the Fix, see [the Fix functions and cookbook](/Fix-functions-and-cookbook).
+For functions and usage of the Fix, see [the Fix functions and cookbook](/docs/fix/Fix-functions-and-cookbook.html).
 
-For next steps get familar with [FLUX](/Flux-User-Guide.md) and [FIX](/Fix-User-Guide.md). And try out some Metafacture workflows.
+For next steps get familar with [FLUX](/docs/flux/Flux-User-Guide.html) and [FIX](/docs/fix/Fix-User-Guide.html). And try out some Metafacture workflows.
 
 ## Command line
 
@@ -24,7 +27,7 @@ To get started, you can export a workflow from the Playground (last button, !["E
 
 To set up IDE support for editing your Flux and Fix files, see [the IDE extensions page](https://metafacture.org/ide-extensions/index.html).
 
-For next steps get familar with [FLUX](/Flux-User-Guide.md) and [FIX](/Fix-User-Guide.md). And try out some Metafacture workflows.
+For next steps get familar with [FLUX](/docs/flux/Flux-User-Guide.html) and [FIX](/docs/fix/Fix-User-Guide.html). And try out some Metafacture workflows.
 
 ## Using Metafacture as a Java library
 
@@ -55,4 +58,4 @@ To use Fix you would declare `metafix` instead of `metafacture-io` as in the exa
 Occasionally, we publish snapshot builds on [Sonatype OSS Repository](https://oss.sonatype.org/index.html#nexus-search;gav~org.metafacture~~~~~kw,versionexpand). The version number is derived from the branch name. Snapshot builds from the master branch always have the version `master-SNAPSHOT`. We also provide sometimes pre releases as github packages.
 
 
-If you plan to use Metafacture as a Java library or if you wish to add commands to Flux you should get familar with the [Framework](/Framework-User-Guide.md).
+If you plan to use Metafacture as a Java library or if you wish to add commands to Flux you should get familar with the [Framework](/docs/java-integration/Framework-User-Guide.html).

docs/LICENSE.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: LICENSE
+nav_order: 9
+---
+
+MIT License
+
+Copyright (c) 2022 just-the-docs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

MF-in-5-min.md → docs/MF-in-5-min.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: 5 min Intro into MF
+nav_order: 3
+---
+
 # Introduction - A quick 5 minute introduction to Metafacture
 
 ## HELLO WORLD
@@ -87,7 +93,7 @@ $ cat yaml2json.flux
 
 ## FIX LANGUAGE
 
-Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. A full list Fix functions is available at https://github.com/metafacture/metafacture-documentation/blob/master/Fix-function-and-Cookbook.md#functions.
+Many data conversions need a mapping from one field to another field plus optional conversions of the data inside these fields. Metafacture provides the transformation module `fix` that uses the Catmandu-inspired Fix language to assist in these mappings. See the [full list of Fix functions](/docs/fix/Fix-functions-and-Cookbook.html#functions).
 
 Fixes can be provided inline as text argument of the fix module in the Flux script, or as a pointer to a Fix script. A Fix script groups one or more fixes in a file.
 
@@ -173,6 +179,6 @@ The 245 field with its subfields of each MARC record is mapped to the title fiel
 The `retain` Fix function keeps only the title field in the output. (In contrast to Catmandu there are no special marc or pica fixes since the internal handling of records and elements is more generic. Also the internal serialization of MARC is not as complex as in Catmandu.)
 
 
-Now you should be ready to [get started](./Getting-Started.md).
+Now you should be ready to [get started](/docs/Getting-Started.html).
 
 (Note: This mini introduction to Metafacture is inspired by the mini introduction to Catmandu here: https://metacpan.org/dist/Catmandu/view/lib/Catmandu/Introduction.pod)

Fix-User-Guide.md → docs/fix/Fix-User-Guide.md

@@ -1,11 +1,16 @@
-![logo](https://github.com/culturegraph/metafacture-core/wiki/img/metafacture_small.png)
+---
+layout: default
+title: Fix User Guide
+parent: Fix
+nav_order: 1
+---
 
 # Fix User Guide
 
 This document provides an introduction to the Metafacture Fix language (short: Metafix or Fix). The Fix language for Metafacture is introduced as an alternative to configuring data transformations with Metamorph. Inspired by Catmandu Fix, Metafix processes metadata not as a continuous data stream but as discrete records.
 
 ## Part of a metafacture worflow
-Metafacture Fix is a transformation module that can be used in a [Flux Workflow](/Flux-User-Guide.md), for this you have to use this in your pipeline:
+Metafacture Fix is a transformation module that can be used in a [Flux Workflow](/docs/flux/Flux-User-Guide.html), for this you have to use this in your pipeline:
 
 Flux-Example:
 ```PERL
@@ -85,7 +90,7 @@ do Bind(params,…)
 end
 ```
 
-Find here a [list of all functions, selectors, binds and conditionals](/Fix-function-and-Cookbook.md).
+Find here a [list of all functions, selectors, binds and conditionals](//docs/fix/s-and-Cookbook.html).
 
 
 ## Addressing Pieces of Data: FIX-Path and the record structure in FIX

Fix-function-and-Cookbook.md → docs/fix/Fix-functions-and-Cookbook.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Fix Functions and Cookbook
+parent: Fix
+nav_order: 2
+---
+
 This page is a replication of the passage of the Fix Readme.md.
 
 ## Functions and cookbook

docs/fix/fix.md

@@ -0,0 +1,19 @@
+---
+layout: default
+title: Fix
+nav_order: 6
+has_children: true
+---
+
+Metafix is a domain specific language for metadata transformation based on Catmandu FIX. The FIX object performing the transformation is used as part of a processing pipeline.
+
+If you are using **Metafacture with CLI or Playground** and therefore the Flux scripting language to build and run pipelines, use the `fix` command in your FLUX-Pipeline. 
+
+If you are using **Metafacture as a Java library**, just create a Metafix object and add it to your pipeline (see also the [Framework User Guide](#framework)).
+
+The transformation itself is declared in a fix-object which can be a file. For more information on how to declare transformations see [Metafix User Guide](/Fix-User-Guide.md).
+
+See [here a list for all available FIX functions and a cookbook for using fix](//docs/fix/Fix-functions-and-Cookbook.html).
+
+> [!NOTE]
+> PS: There is also the transformation modul MORPH. Have a look at[ the old documentation](https://github.com/metafacture/metafacture-core/wiki/Metamorph-User-Guide) and the german cookbook by [Swissbib](https://swissbib.gitlab.io/metamorph-doku/).

Flux-User-Guide.md → docs/flux/Flux-User-Guide.md

@@ -1,4 +1,9 @@
-![logo](https://github.com/culturegraph/metafacture-core/wiki/img/metafacture_small.png)
+---
+layout: default
+title: Flux User Guide
+parent: Flux
+nav_order: 1
+---
 
 # Flux User Guide
 
@@ -46,6 +51,7 @@ This sets the variable `var1` to the value 'value1' and `var2` to the value 'val
 
 ## Writing Flux files
 The following snippet shows a simple flux file:
+
 ```c
 //declare variables
 default file = FLUX_DIR + "10.marc21";
@@ -60,8 +66,9 @@ file
 | write("stdout")
 ;
 ```
+
 In the first section [variables](#variables) are declared, in the second, we [define the flow](#flow-definitions).
-A flow is a combination of different [FLUX commands. Here is a list to all available Flux-Commands.](https://github.com/metafacture/metafacture-documentation/blob/master/flux-commands.md)
+A flow is a combination of different [FLUX commands. Here is a list to all available Flux-Commands.](/docs/flux/flux-commands.html)
 
 Linebreaks are optional, but help concerning readability. One can add comments with `//`.
 Semicolons `;` mark the end of a variable assignment or flow definition. 
@@ -85,15 +92,15 @@ The syntax for defining flows takes its cues from bash pipes. Commands are conca
 
 Some commands take a constructor argument. It is provided within brackets: `command("arg")`.
 Furthermore, some commands have named options. These are set as follows `command(optionname="arg1",annotheroption="arg2")` or with constructor argument: `command("arg",option="arg2")`.
-To learn about the available options of a command, execute Flux without arguments - it will list all available commands, including options. Or simply have a look at the [list of available FLUX commands.](https://github.com/metafacture/metafacture-documentation/blob/master/flux-commands.md)
+To learn about the available options of a command, execute Flux without arguments - it will list all available commands, including options. Or simply have a look at the [list of available FLUX commands.](/flux-commands.md)
 
 
 To some commands the entire environment can be given as an argument. This is done with the `*` character: `fix("tranformation.fix", *)`. In this case Metafix gains access to all variable assignments made in Flux.
 (See also [[Metafix-User-Guide#parameters-to-metafix-definitions]]).
 
 Note that unlike shell pipes, the data flowing between Flux commands is _typed_. This means that only commands with matching signatures can be combined. Commands expect a certain input and provide a certain output like: `StreamReceiver, `Object`, `Reader` and others.
 
-To lookup the signatures, again: execute Flux without arguments or see: [[Metafix-User-Guide#parameters-to-metafix-definitions]]). It will list all available commands, including signatures. Or simply have a look at the  [list of available FLUX commands.](https://github.com/metafacture/metafacture-documentation/blob/master/flux-commands.md)
+To lookup the signatures, again: execute Flux without arguments or see: [[Metafix-User-Guide#parameters-to-metafix-definitions]]). It will list all available commands, including signatures. Or simply have a look at the  [list of available FLUX commands.](/docs/flux/flux-commands.html)
 
 ### Variables
 Variables are always Strings and can be concatenated with the `+` operator. Escape sequences follow the Java String conventions: `\n`=line break, `\t`=tab, `\\`=\, `\u0024`=unicode character, etc.
@@ -108,16 +115,16 @@ Flux supports single line C/Java-style comments: `//comment`.
 
 
 ## Overview of the commands and some examples
-1. Have a look at the [List of available FLUX commands](https://github.com/metafacture/metafacture-documentation/blob/master/flux-commands.md) or execute the flux without arguments to get a short help text along with a list of all registered commands. This is the list of FLUX commands mentioned already above.
-2. There are several example flux files along with sample data in the folder `examples/`: https://github.com/metafacture/metafacture-core/tree/master/metafacture-runner/src/main/dist/examples
+1. Have a look at the [List of available FLUX commands](/flux-commands.md) or execute the flux without arguments to get a short help text along with a list of all registered commands. This is the list of FLUX commands mentioned already above.
+2. There are several example flux files along with sample data in the repo folder `examples/`: [https://github.com/metafacture/metafacture-core/tree/master/metafacture-runner/src/main/dist/examples](https://github.com/metafacture/metafacture-core/tree/master/metafacture-runner/src/main/dist/examples)
 
 _________________________
-# For developers: 
+## For developers: 
 
 > [!NOTE]
 > Coding in JAVA.
 
-## Adding new Commands
+### Adding new Commands
 Add your class and a descriptive flux shortcut to `flux-commands.properties`. This file acts as a lookup table for flux commands. Use the proper file, i.e. the one residing in the same module where your newly created class resides. If you have e.g. created a class in the module `metafacture-biblio`, you add the flux-command to https://github.com/metafacture/metafacture-core/blob/master/metafacture-biblio/src/main/resources/flux-commands.properties.
 Recompile. That's all to add a command.
 

flux-commands.md → docs/flux/flux-commands.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Flux Commands
+parent: Flux
+nav_order: 2
+---
+
 Available flux commands
 =======================
 

docs/flux/flux.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Flux
+nav_order: 5
+has_children: true
+---
+
+# FLUX
+
+Flux is a scripting language to easily build and run processing pipelines. No Java programming is necessary - it's used as a command line. To use Flux you may download the binary distribution of Metafacture.
+
+For more information on how to use Flux, see the [Flux User Guide](/docs/flux/Flux-User-Guide.html).
+
+See [here a list for all available FLUX-Commands](/docs/flux/flux-commands.html).

Framework-User-Guide.md → docs/java-integration/Framework-User-Guide.md

@@ -1,9 +1,14 @@
-![logo](https://github.com/culturegraph/metafacture-core/wiki/img/metafacture_small.png)
+---
+layout: default
+title: Framework User Guide
+parent: Java Integration
+nav_order: 1
+---
 
 # Framework User Guide
 
 > [!NOTE]
->Relevant for Java developers. For using metafacture without Java Code see the [FLUX user guide](/Flux-User-Guide.md).
+>Relevant for Java developers. For using metafacture without Java Code see the [FLUX user guide](/docs/flux/Flux-User-Guide.html).
 
 This page explains how to create a Metafacture objects and how to assemble them to form a processing pipeline. We use as an example a simple pipeline containing a Metafix instance.