docs: improve docs and example data for excel2xml (DEV-1370)

docs/assets/0123-import-scripts/README.md

@@ -0,0 +1,142 @@
+# Welcome to 0123-import-scripts!
+
+This is a template repository that can be used for the archiving process of a big dataset at the end of a research 
+project's lifetime. Download and unpack this repository from the 
+[excel2xml documentation page](https://docs.dasch.swiss/latest/DSP-TOOLS/dsp-tools-excel2xml/).  
+
+In this README, you will learn how to write a Python script for preparing data for an import into DSP.  
+
+Featuring: 
+
+- first steps with Visual Studio Code
+- the module `excel2xml` of dsp-tools
+- the benefits of Version Control with Git
+- the benefits of the Debugging Mode
+- extras: OpenRefine, Git GUIs, regexr
+
+
+# First steps with Visual Studio Code (VSC)
+[**Visual Studio Code**](https://code.visualstudio.com/download) is the industry standard IDE, free to use, and 
+recommended for your daily work at DaSCH. Recommended extensions to install from within VSC: 
+
+- redhat.vscode-xml
+- ms-python.python
+- ms-python.vscode-pylance 
+- zainchen.json
+- nickdemayo.vscode-json-editor
+- visualstudioexptteam.vscodeintellicode
+- redhat.vscode-xml
+- dotjoshjohnson.xml
+
+
+## Initialize Git
+Open this repository in Visual Studio Code, change to the "Source Control" tab, and click on "Inizialize Repository":
+
+![git init](assets/git-init.png)
+
+Stage all changes, write "init" as commit message, and commit all changes:
+
+![git commit](assets/git-commit.png)
+
+You now have the option "Publish Branch". This is to synchronize your local work with a GitHub repository on 
+[https://github.com/dasch-swiss/](https://github.com/dasch-swiss/). For this purpose, replace `0123` by your project's 
+shortcode, and `import` by your project's shortname. This is especially recommended for big projects where you spend 
+weeks/months on, when you might want to have a backup, or when you want to invite colleagues for collaboration or a code
+review.
+
+
+## Choose a Python interpreter
+Open `import-script.py`. You can now choose a Python interpreter by clicking on the Version number on the bottom right.
+You can either work with the global (system-wide) Python, or you can create a 
+[virtual environment](https://python.land/virtual-environments) for your project. If you don't know which one to choose, 
+take the one installed via Homebrew, which is located in `/usr/local/Cellar`. Probably you already have a symlink 
+(`/usr/local/bin/python3` or `/usr/bin/python3`) that redirects to `/usr/local/Cellar`. The only thing that you 
+shouldn't do is selecting a virtual environment of another project.
+
+![python interpreter](assets/python-interpreter.png)
+
+
+## The benefits of the debugging mode
+To start the debugging process, switch to the "Run and Debug" tab.
+
+1. set a break point
+2. click "Run and Debug"
+3. choose "Debug the currently active Python file"
+4. The control bar appears, and debugging starts.
+
+![configure debugging](assets/configure-debugging.png)
+
+Code execution will interrupt at your break point, that means, before the line of the break point is executed. Use 
+this opportunity to inspect what has been done until now in the "Variables" area on the left, where the current state of
+the program is shown.  
+
+If one of the dependencies is not installed, install it with `pip install package` in the Terminal of Visual Studio 
+Code.
+
+![pause at breakpoint](assets/pause-at-breakpoint.png)
+
+If you want to experiment with different scenarios how to proceed, go to the "Debug Console" where you can execute 
+code. For example, let's inspect the Pandas Dataframe by typing `main_df.info`.  
+You see that there are some empty rows at the end which don't contain useful data. The next two lines of code will 
+eliminate them. Click on "Step Over" two times, or set a new break point two lines further down and click on "Continue".
+Now, type again `main_df.info` in the Debug Console. You will see that the empty rows are gone.  
+
+![inspect dataframe](assets/inspect-dataframe.png)
+
+
+You see that the debugging mode is a useful tool to understand code and to inspect it for correctness. 
+
+| **Tip**                                                                                                   |
+|-----------------------------------------------------------------------------------------------------------|
+| **Make regular use of the debugging mode to check if your code really does what you think it should do!** | 
+
+
+## The benefits of version control
+One of the big benefits of version control is the diff viewer. Visual Studio highlights the changes you have introduced 
+since your last commit. 
+
+- Deletions are shown as red triangle.
+- Additions are shown as green bars.
+- Changed lines are shown as striped bars.
+
+Click on these visual elements to see a small popup that shows you the difference. In the popup, you can stage the 
+change, revert it, or jump to the next/previous change.
+
+![diffs](assets/diffs.png)
+
+Once you have a bunch of code changes that can be meaningfully grouped together, you should make a commit (and perhaps
+push it to a GitHub repo).
+
+
+| **Tips**                                                                |
+|-------------------------------------------------------------------------|
+| **Test your code (e.g. with the debugging mode) before committing it.** | 
+| **Make small commits that contain only one new feature.**               | 
+
+
+## Some extras
+### Data cleaning with OpenRefine
+[**OpenRefine**](https://openrefine.org/) is a tool for working with messy data. Once downloaded and installed, it runs 
+as a local server, accessed by your browser. So, all data remains on your own machine. Installation is quick and 
+painless: 
+```
+brew install openrefine
+```
+
+The potentials for the everyday work of the Client Services at DaSCH are twofold:
+1. Data cleaning (recommended): For this purpose, you can think of OpenRefine as a much better version of Excel. You 
+   can perform operations which would be very tiresome in Excel.
+2. Conversion to our dps-customised xml format for bulk upload (not recommended)
+
+Read more in [this report](https://docs.google.com/document/d/1Y_hZV8UV-Irw-7PLdhm0BGKnGfXJs8JO).
+
+
+### Git GUIs
+Git can be complicated, so you will appreciate to work with one of these GUIs:
+
+ - [**SmartGit**](https://www.syntevo.com/smartgit/) has a free edition. 
+ - [**GitHub Desktop**](https://desktop.github.com/)
+ - [**SourceTree**](https://www.sourcetreeapp.com/)
+
+### Learn, build and test RegEx
+[https://regexr.com](https://regexr.com)

docs/assets/0123-import-scripts/data-raw.csv

@@ -0,0 +1,7 @@
+Object,Title,Description,Category,Public,Color,Date,Time,Weight (kg),Location,URL,  ,  
+Anubis,Bengal cat,An example of a domesticated cat,"Säugetiere, Huumans",yes,#f5f5dc,2015_01_01,2015-01-01T13:45:12Z,4.8,2661604,https://en.wikipedia.org/wiki/Cat,,
+Meteorite,Gibeon Meteorite,This is a piece of the so-called Gibeon Meteroite,Physics,1,#808080,"March 5,1908",1908-03-05T12:00:00-05:00,0.3,11821111,https://en.wikipedia.org/wiki/Gibeon_(meteorite),,
+BM1888-0601-716,Lekythos,"Attic red-figured Lekythos BM 1888,601.716",Artwörk,TRUE,,1.12.1973 - 6.1.1974,,0.5,351274,https://www.britishmuseum.org/collection/object/G_1888-0601-716,,
+Horohoroto,Picture and Poem by Matsuo Bashō,ほろほろと山吹ちるかたきのおと,Kunstwerk,,,1849/1850,,1,,https://en.wikipedia.org/wiki/Haiku#/media/File:Basho_Horohoroto.jpg,,
+  ,,,,,,,,,,,,
+  ,  ,,,,,,,,,,,

docs/assets/0123-import-scripts/import-project.json

@@ -0,0 +1,218 @@
+{
+  "$schema": "https://raw.githubusercontent.com/dasch-swiss/dsp-tools/main/knora/dsplib/schemas/ontology.json",
+  "project": {
+    "shortcode": "0123",
+    "shortname": "import",
+    "longname": "Template project for importing data to DaSCH",
+    "descriptions": {
+      "en": "Template project to demonstrate the archiving process of a big dataset at the end of a research project's lifetime."
+    },
+    "keywords": ["Data and Service Center for the Humanities (DaSCH)"],
+    "lists": [
+      {
+        "name": "category",
+        "labels": {"de": "Kategorie", "en": "Category"},
+        "comments": {"en": "A list containing categories", "de": "Eine Liste mit Kategorien"},
+        "nodes": [
+          {
+            "name": "artwork",
+            "labels": {"de": "Kunstwerk", "en": "Artwork"}
+          },
+          {
+            "name": "nature",
+            "labels": {"de": "Natur", "en": "Nature"},
+            "nodes": [
+              {
+                "name": "humans",
+                "labels": {"de": "Menschen", "en": "Humans"}
+              },
+              {
+                "name": "animals",
+                "labels": {"de": "Tiere", "en": "Animals"},
+                "nodes": [
+                  {
+                    "name": "mammals",
+                    "labels": {"de": "Säugetiere", "en": "Mammals"}
+                  },
+                  {
+                    "name": "birds",
+                    "labels": {"de": "Vögel", "en": "Birds"}
+                  },
+                  {
+                    "name": "reptiles",
+                    "labels": {"de": "Reptilien", "en": "Reptiles"}
+                  }
+                ]
+              },
+              {
+                "name": "plants",
+                "labels": {"de": "Pflanzen", "en": "Plants"}
+              },
+              {
+                "name": "physics",
+                "labels": {"de": "Physik", "en": "Physics"}
+              }
+            ]
+          }
+        ]
+      }
+    ],
+    "ontologies": [
+      {
+        "name": "import",
+        "label": "The template ontology for data import",
+        "properties": [
+          {
+            "name": "hasTime",
+            "super": ["hasValue"],
+            "object": "TimeValue",
+            "labels": {"en": "Time"},
+            "gui_element": "TimeStamp"
+          },
+          {
+            "name": "hasImage",
+            "super": ["hasLinkTo"],
+            "object": ":Image2D",
+            "labels": {"en": "Image"},
+            "gui_element": "Searchbox"
+          },
+          {
+            "name": "hasDescription",
+            "super": ["hasValue"],
+            "object": "TextValue",
+            "labels": {"en": "Description"},
+            "gui_element": "Richtext"
+          },
+          {
+            "name": "hasName",
+            "super": ["hasValue"],
+            "object": "TextValue",
+            "labels": {"en": "Name"},
+            "gui_element": "SimpleText"
+          },
+          {
+            "name": "hasTitle",
+            "super": ["hasValue"],
+            "object": "TextValue",
+            "labels": {"en": "Title"},
+            "gui_element": "SimpleText"
+          },
+          {
+            "name": "hasDate",
+            "super": ["hasValue"],
+            "object": "DateValue",
+            "labels": {"en": "Dating"},
+            "gui_element": "Date"
+          },
+          {
+            "name": "hasLocation",
+            "super": ["hasValue"],
+            "object": "GeonameValue",
+            "labels": {"en": "Location"},
+            "gui_element": "Geonames"
+          },
+          {
+            "name": "hasExternalLink",
+            "super": ["hasValue"],
+            "object": "UriValue",
+            "labels": {"en": "External link"},
+            "gui_element": "SimpleText"
+          },
+          {
+            "name": "hasCategory",
+            "super": ["hasValue"],
+            "object": "ListValue",
+            "labels": {"en": "Category"},
+            "gui_element": "List",
+            "gui_attributes": {"hlist": "category"}
+          },
+          {
+            "name": "hasColor",
+            "super": ["hasColor"],
+            "object": "ColorValue",
+            "labels": {"en": "Colour"},
+            "gui_element": "Colorpicker"
+          },
+          {
+            "name": "isPublic",
+            "super": ["hasValue"],
+            "object": "BooleanValue",
+            "labels": {"en": "Public"},
+            "gui_element": "Checkbox"
+          },
+          {
+            "name": "hasWeight",
+            "super": ["hasValue"],
+            "object": "DecimalValue",
+            "labels": {"en": "Weight"},
+            "gui_element": "SimpleText"
+          }
+        ],
+        "resources": [
+          {
+            "name": "Image2D",
+            "labels": {"en": "2D image"},
+            "super": "StillImageRepresentation",
+            "cardinalities": [
+              {
+                "propname": ":hasTitle",
+                "cardinality": "1"
+              }
+            ]
+          },
+          {
+            "name": "Object",
+            "labels": {"en": "Object"},
+            "super": "Resource",
+            "cardinalities": [
+              {
+                "propname": ":hasImage",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasCategory",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasName",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasDescription",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasWeight",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasDate",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasLocation",
+                "cardinality": "0-1"
+              },
+              {
+                "propname": ":isPublic",
+                "cardinality": "0-1"
+              },
+              {
+                "propname": ":hasColor",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasExternalLink",
+                "cardinality": "0-n"
+              },
+              {
+                "propname": ":hasTime",
+                "cardinality": "0-n"
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}