From 7520e5fa553d923da1f22ca0c5633b955d03aa2b Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum Date: Wed, 26 Jan 2022 13:10:01 +0100 Subject: [PATCH 1/3] improved the docs --- docs/dsp-tools-excel.md | 56 ++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 37 deletions(-) diff --git a/docs/dsp-tools-excel.md b/docs/dsp-tools-excel.md index b51b7da57..0e4cc2117 100644 --- a/docs/dsp-tools-excel.md +++ b/docs/dsp-tools-excel.md @@ -2,14 +2,11 @@ # Excel files for data modelling and data import -dsp-tools is able to process Excel files and output the appropriate JSON or XML file. The JSON/XML file can then be used -to create the ontology on the DSP server or import data to the DSP repository. dsp-tools can also be used to create a -list from an Excel file. +dsp-tools is able to process Excel files and output the appropriate JSON or XML file. The JSON/XML file can then be used to create the ontology on the DSP server or import data to the DSP repository. dsp-tools can also be used to create a list from an Excel file. ## Create the resources for a data model from an Excel file -With dsp-tools the `resources` section used in a data model (JSON) can be created from an Excel file. Only `XLSX` files -are allowed. The `resources` section can be inserted into the ontology file and then be uploaded onto a DSP server. +With dsp-tools, the `resources` section used in a data model (JSON) can be created from an Excel file. Only `XLSX` files are allowed. The `resources` section can be inserted into the ontology file and then be uploaded onto a DSP server. **An Excel file template can be found [here](assets/templates/resources_template.xlsx). It is recommended to work from the template.** @@ -20,17 +17,17 @@ The expected worksheets of the Excel file are: The Excel sheet must have the following format. -The worksheet called `classes` has the following form: +The worksheet called `classes` has the following format: ![img-resources-example-1.png](assets/images/img-resources-example-1.png) The expected columns are: - `name` : The name of the resource -- `super` : The base resource of the resource - `en`, `de`, `fr`, `it` : The labels of the resource in different languages, at least one language has to be provided - `comment_en`, `comment_de`, `comment_fr`, `comment_it`: optional comments in the respective language +- `super` : The base class of the resource -All other worksheets, one for each resource class, have the following form: +All other worksheets, one for each resource class, have the following format: ![img-resources-example-2.png](assets/images/img-resources-example-2.png){ width=50% } The expected columns are: @@ -38,13 +35,13 @@ The expected columns are: - `Property` : The name of the property - `Cardinality` : The cardinality, one of: `1`, `0-1`, `1-n`, `0-n` -For further information about resources, see [here](./dsp-tools-create.md#resources). +The GUI order is given by the order in which the properties are listed in the Excel sheet. + +For further information about resources, see [here](./dsp-tools-create-ontologies.md#resources). ## Create the properties for a data model from an Excel file -With dsp-tools the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first -worksheet of the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted into -the ontology file and then be uploaded onto a DSP server. +With dsp-tools, the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first worksheet of the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted into the ontology file and then be uploaded onto a DSP server. **An Excel file template can be found [here](assets/templates/properties_template.xlsx). It is recommended to work from the template.** @@ -55,13 +52,13 @@ The expected columns are: - `name` : The name of the property - `super` : The base property of the property -- `object` : The resource the property refers to if it is a link property (property derived from `hasLinkTo`) +- `object` : If the property is derived from `hasValue`, the type of the property must be further specified by the object it takes, e.g. `TextValue`, `ListValue`, or `IntValue`. If the property is derived from `hasLinkTo`, the `object` specifies the resource class that this property refers to. - `en`, `de`, `fr`, `it` : The labels of the property in different languages, at least one language has to be provided - `comment_en`, `comment_de`, `comment_fr`, `comment_it`: optional comments in the respective language - `gui_element` : The GUI element for the property -- `hlist` : In case of list values the according list +- `hlist` : In case of list values: the name of the list -For further information about properties, see [here](./dsp-tools-create.md#properties). +For further information about properties, see [here](./dsp-tools-create-ontologies.md#properties). ## Create a DSP-conform XML file from an Excel file @@ -69,28 +66,17 @@ For further information about properties, see [here](./dsp-tools-create.md#prope ## Create a list from one or several Excel files -With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON -ontology and uploaded to a DSP server. The expected format of the Excel files is -described [here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a -separate Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). -It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel sheet -has to be in the exact same cell (i.e. with the same cell index) in its own Excel sheet. +With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON ontology and uploaded to a DSP server. The expected format of the Excel files is described [here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a separate Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel sheet has to be in the exact same cell (i.e. with the same cell index) in its own Excel sheet. -Only Excel files with file extension `.xlsx` are considered. All Excel files have to be located in the same directory. -When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has to -be provided in the Excel file's file name after an underline and before the file extension, p.ex. `liste_de.xlsx` would -be considered a list with German (`de`) labels, `list_en.xlsx` a list with English (`en`) labels. The language has to be -a valid ISO 639-1 or ISO 639-2 language code. +Only Excel files with file extension `.xlsx` are considered. All Excel files have to be located in the same directory. When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has to be provided in the Excel file's file name after an underline and before the file extension, p.ex. `liste_de.xlsx` would be considered a list with German (`de`) labels, `list_en.xlsx` a list with English (`en`) labels. The language has to be a valid ISO 639-1 or ISO 639-2 language code. -The following example shows how to create a JSON list from two Excel files which are in a directory called `lists`. The -output is written to the file `list.json`. +The following example shows how to create a JSON list from two Excel files which are in a directory called `lists`. The output is written to the file `list.json`. ```bash dsp-tools excel lists list.json ``` -The two Excel files `liste_de.xlsx` and `list_en.xlsx` are located in a folder called `lists`. `liste_de.xlsx` contains -German labels for the list, `list_en.xlsx` contains the English labels. +The two Excel files `liste_de.xlsx` and `list_en.xlsx` are located in a folder called `lists`. `liste_de.xlsx` contains German labels for the list, `list_en.xlsx` contains the English labels. ``` lists @@ -98,10 +84,7 @@ lists |__ list_en.xlsx ``` -For each list node, the `label`s are read from the Excel files. The language code, provided in the file name, is then -used for the labels. As node `name`, a simplified version of the English label is taken if English is one of the -available languages. If English is not available, one of the other languages is chosen (which one depends on the -representation of the file order). If there are two node names with the same name, an incrementing number is appended to +For each list node, the `label`s are read from the Excel files. The language code, provided in the file name, is then used for the labels. As node `name`, a simplified version of the English label is taken if English is one of the available languages. If English is not available, one of the other languages is chosen (which one depends on the representation of the file order). If there are two node names with the same name, an incrementing number is appended to the `name`. ```JSON @@ -134,8 +117,7 @@ the `name`. } } ] -}, ... +} ``` -After the creation of the list, a validation against the JSON schema for lists is performed. An error message ist -printed out if the list is not valid. Furthermore, it is checked that no two nodes are the same. +After the creation of the list, a validation against the JSON schema for lists is performed. An error message is printed out if the list is not valid. Furthermore, it is checked that no two nodes are the same. \ No newline at end of file From 20840d70c5ff09f4495090178a3748312ba85958 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum Date: Wed, 26 Jan 2022 14:46:42 +0100 Subject: [PATCH 2/3] break too long lines --- docs/dsp-tools-excel.md | 49 +++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/docs/dsp-tools-excel.md b/docs/dsp-tools-excel.md index 0e4cc2117..465dc7214 100644 --- a/docs/dsp-tools-excel.md +++ b/docs/dsp-tools-excel.md @@ -2,13 +2,18 @@ # Excel files for data modelling and data import -dsp-tools is able to process Excel files and output the appropriate JSON or XML file. The JSON/XML file can then be used to create the ontology on the DSP server or import data to the DSP repository. dsp-tools can also be used to create a list from an Excel file. +dsp-tools is able to process Excel files and output the appropriate JSON or XML file. The JSON/XML file can then be +used to create the ontology on the DSP server or import data to the DSP repository. dsp-tools can also be used to +create a list from an Excel file. ## Create the resources for a data model from an Excel file -With dsp-tools, the `resources` section used in a data model (JSON) can be created from an Excel file. Only `XLSX` files are allowed. The `resources` section can be inserted into the ontology file and then be uploaded onto a DSP server. +With dsp-tools, the `resources` section used in a data model (JSON) can be created from an Excel file. Only `XLSX` +files are allowed. The `resources` section can be inserted into the ontology file and then be uploaded onto a DSP +server. -**An Excel file template can be found [here](assets/templates/resources_template.xlsx). It is recommended to work from the template.** +**An Excel file template can be found [here](assets/templates/resources_template.xlsx). It is recommended to work from +the template.** The expected worksheets of the Excel file are: @@ -41,9 +46,12 @@ For further information about resources, see [here](./dsp-tools-create-ontologie ## Create the properties for a data model from an Excel file -With dsp-tools, the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first worksheet of the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted into the ontology file and then be uploaded onto a DSP server. +With dsp-tools, the `properties` section used in a data model (JSON) can be created from an Excel file. Only the first +worksheet of the Excel file is considered and only XLSX files are allowed. The `properties` section can be inserted +into the ontology file and then be uploaded onto a DSP server. -**An Excel file template can be found [here](assets/templates/properties_template.xlsx). It is recommended to work from the template.** +**An Excel file template can be found [here](assets/templates/properties_template.xlsx). It is recommended to work +from the template.** The Excel sheet must have the following format: ![img-properties-example.png](assets/images/img-properties-example.png) @@ -52,7 +60,9 @@ The expected columns are: - `name` : The name of the property - `super` : The base property of the property -- `object` : If the property is derived from `hasValue`, the type of the property must be further specified by the object it takes, e.g. `TextValue`, `ListValue`, or `IntValue`. If the property is derived from `hasLinkTo`, the `object` specifies the resource class that this property refers to. +- `object` : If the property is derived from `hasValue`, the type of the property must be further specified by the +object it takes, e.g. `TextValue`, `ListValue`, or `IntValue`. If the property is derived from `hasLinkTo`, +the `object` specifies the resource class that this property refers to. - `en`, `de`, `fr`, `it` : The labels of the property in different languages, at least one language has to be provided - `comment_en`, `comment_de`, `comment_fr`, `comment_it`: optional comments in the respective language - `gui_element` : The GUI element for the property @@ -66,17 +76,28 @@ For further information about properties, see [here](./dsp-tools-create-ontologi ## Create a list from one or several Excel files -With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON ontology and uploaded to a DSP server. The expected format of the Excel files is described [here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a separate Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel sheet has to be in the exact same cell (i.e. with the same cell index) in its own Excel sheet. +With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON +ontology and uploaded to a DSP server. The expected format of the Excel files is described +[here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a separate +Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). +It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel +sheet has to be in the exact same cell (i.e. with the same cell index) in its own Excel sheet. -Only Excel files with file extension `.xlsx` are considered. All Excel files have to be located in the same directory. When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has to be provided in the Excel file's file name after an underline and before the file extension, p.ex. `liste_de.xlsx` would be considered a list with German (`de`) labels, `list_en.xlsx` a list with English (`en`) labels. The language has to be a valid ISO 639-1 or ISO 639-2 language code. +Only Excel files with file extension `.xlsx` are considered. All Excel files have to be located in the same directory. +When calling the `excel` command, this folder is provided as an argument to the call. The language of the labels has +to be provided in the Excel file's file name after an underline and before the file extension, p.ex. `liste_de.xlsx` +would be considered a list with German (`de`) labels, `list_en.xlsx` a list with English (`en`) labels. The language +has to be a valid ISO 639-1 or ISO 639-2 language code. -The following example shows how to create a JSON list from two Excel files which are in a directory called `lists`. The output is written to the file `list.json`. +The following example shows how to create a JSON list from two Excel files which are in a directory called `lists`. +The output is written to the file `list.json`. ```bash dsp-tools excel lists list.json ``` -The two Excel files `liste_de.xlsx` and `list_en.xlsx` are located in a folder called `lists`. `liste_de.xlsx` contains German labels for the list, `list_en.xlsx` contains the English labels. +The two Excel files `liste_de.xlsx` and `list_en.xlsx` are located in a folder called `lists`. `liste_de.xlsx` +contains German labels for the list, `list_en.xlsx` contains the English labels. ``` lists @@ -84,7 +105,10 @@ lists |__ list_en.xlsx ``` -For each list node, the `label`s are read from the Excel files. The language code, provided in the file name, is then used for the labels. As node `name`, a simplified version of the English label is taken if English is one of the available languages. If English is not available, one of the other languages is chosen (which one depends on the representation of the file order). If there are two node names with the same name, an incrementing number is appended to +For each list node, the `label`s are read from the Excel files. The language code, provided in the file name, is then +used for the labels. As node `name`, a simplified version of the English label is taken if English is one of the +available languages. If English is not available, one of the other languages is chosen (which one depends on the +representation of the file order). If there are two node names with the same name, an incrementing number is appended to the `name`. ```JSON @@ -120,4 +144,5 @@ the `name`. } ``` -After the creation of the list, a validation against the JSON schema for lists is performed. An error message is printed out if the list is not valid. Furthermore, it is checked that no two nodes are the same. \ No newline at end of file +After the creation of the list, a validation against the JSON schema for lists is performed. An error message is +printed out if the list is not valid. Furthermore, it is checked that no two nodes are the same. From 4d72ec6cf9ec38fa8e9822e6a529be705c9bc146 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum Date: Wed, 26 Jan 2022 14:49:16 +0100 Subject: [PATCH 3/3] replace 'format' by 'structure' --- docs/dsp-tools-excel.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/dsp-tools-excel.md b/docs/dsp-tools-excel.md index 465dc7214..8cef370b9 100644 --- a/docs/dsp-tools-excel.md +++ b/docs/dsp-tools-excel.md @@ -20,9 +20,9 @@ The expected worksheets of the Excel file are: - `classes`: a table with all resource classes intended to be used in the resulting JSON - `class1`, `class2`,...: a table for each resource class named after its name -The Excel sheet must have the following format. +The Excel sheet must have the following structure. -The worksheet called `classes` has the following format: +The worksheet called `classes` has the following structure: ![img-resources-example-1.png](assets/images/img-resources-example-1.png) The expected columns are: @@ -32,7 +32,7 @@ The expected columns are: - `comment_en`, `comment_de`, `comment_fr`, `comment_it`: optional comments in the respective language - `super` : The base class of the resource -All other worksheets, one for each resource class, have the following format: +All other worksheets, one for each resource class, have the following structure: ![img-resources-example-2.png](assets/images/img-resources-example-2.png){ width=50% } The expected columns are: @@ -53,7 +53,7 @@ into the ontology file and then be uploaded onto a DSP server. **An Excel file template can be found [here](assets/templates/properties_template.xlsx). It is recommended to work from the template.** -The Excel sheet must have the following format: +The Excel sheet must have the following structure: ![img-properties-example.png](assets/images/img-properties-example.png) The expected columns are: @@ -77,7 +77,7 @@ For further information about properties, see [here](./dsp-tools-create-ontologi ## Create a list from one or several Excel files With dsp-tools a JSON list can be created from one or several Excel files. The list can then be inserted into a JSON -ontology and uploaded to a DSP server. The expected format of the Excel files is described +ontology and uploaded to a DSP server. The expected structure of the Excel files is described [here](./dsp-tools-create.md#lists-from-excel). It is possible to create multilingual lists. In this case, a separate Excel file has to be created for each language. The data has to be in the first worksheet of the Excel file(s). It is important that all the Excel lists have the same structure. So, the translation(s) of a label in one Excel