From be5b69f41cea50a37c0ff840830232ebe65cf041 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com> Date: Thu, 17 Feb 2022 16:05:43 +0100 Subject: [PATCH] docs: improve docs (DEV-450) (#152) * improve docs * correct the heading hierarchy of CHANGELOG.md * Instad of layout-hacking, adapt the CSS to have more top-padding for headers * adapt layout * update pyproject.toml for autopep8 --- CHANGELOG.md | 32 +-- docs/assets/style/theme.css | 16 ++ docs/dsp-tools-create-ontologies.md | 42 ++-- docs/dsp-tools-information-for-developers.md | 3 +- docs/dsp-tools-xmlupload.md | 237 ++++++++++--------- 5 files changed, 178 insertions(+), 152 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 372aa2e28..f7c57ea7e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,7 +13,7 @@ * **xmlupload:** use custom IRIs created from salsah ARKs for XML upload (DEV-179) ([#147](https://www.github.com/dasch-swiss/dsp-tools/issues/147)) ([873324a](https://www.github.com/dasch-swiss/dsp-tools/commit/873324ad4cd4fefd48d8d2fc37f08774285849d5)) -### [1.8.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.8.0...v1.8.1) (2022-01-11) +## [1.8.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.8.0...v1.8.1) (2022-01-11) ### Bug Fixes @@ -45,7 +45,7 @@ * improve ontology schema and extend tests (DEV-313) ([#140](https://www.github.com/dasch-swiss/dsp-tools/issues/140)) ([656ccff](https://www.github.com/dasch-swiss/dsp-tools/commit/656ccff0ff553b13b19242c9997220600e53a76f)) -### [1.7.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.7.0...v1.7.1) (2021-12-14) +## [1.7.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.7.0...v1.7.1) (2021-12-14) ### Bug Fixes @@ -76,7 +76,7 @@ * update DSP-Tools to support ArchiveRepresentation (DEV-259) ([#128](https://www.github.com/dasch-swiss/dsp-tools/issues/128)) ([85a40c2](https://www.github.com/dasch-swiss/dsp-tools/commit/85a40c203d0fa7afc7f7bb122aac0860c304acf4)) -### [1.6.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.6.0...v1.6.1) (2021-11-25) +## [1.6.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.6.0...v1.6.1) (2021-11-25) ### Bug Fixes @@ -103,14 +103,14 @@ * **id-to-iri:** extend xmlupload to allow references to existing resources (DEV-60) ([#108](https://www.github.com/dasch-swiss/dsp-tools/issues/108)) ([40b01db](https://www.github.com/dasch-swiss/dsp-tools/commit/40b01db9d32353dce048e60f48e1454ff7a9bbd5)) -### [1.5.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.1...v1.5.2) (2021-11-16) +## [1.5.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.1...v1.5.2) (2021-11-16) ### Maintenance * **documentation:** add missing documentation for excel2resources (DEV-144) ([cde0db5](https://www.github.com/dasch-swiss/dsp-tools/commit/cde0db5fc925055c0b7a5b3ff3706afd26497f8c)) -### [1.5.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.0...v1.5.1) (2021-10-13) +## [1.5.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.0...v1.5.1) (2021-10-13) ### Bug Fixes @@ -131,7 +131,7 @@ * **docs:** fix example in documentation (DSP-1740) ([#99](https://www.github.com/dasch-swiss/dsp-tools/issues/99)) ([11cdd72](https://www.github.com/dasch-swiss/dsp-tools/commit/11cdd72911e41d837a99579caf0d9d799b0360fc)) -### [1.4.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.4.0...v1.4.1) (2021-09-20) +## [1.4.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.4.0...v1.4.1) (2021-09-20) ### Maintenance @@ -151,21 +151,21 @@ * **excel-to-properties:** create properties from Excel (DSP-1577) ([#89](https://www.github.com/dasch-swiss/dsp-tools/issues/89)) ([9f48e9a](https://www.github.com/dasch-swiss/dsp-tools/commit/9f48e9ae580121e01896fc4f2f8491da8150a180)) * **excel-to-resources:** create resources from excel (DSP-1576) ([#88](https://www.github.com/dasch-swiss/dsp-tools/issues/88)) ([7b0302f](https://www.github.com/dasch-swiss/dsp-tools/commit/7b0302f2feed3475f908c3915ce89d9b5d423d11)) -### [1.3.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.2...v1.3.3) (2021-09-07) +## [1.3.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.2...v1.3.3) (2021-09-07) ### Bug Fixes * wrong values & property ([#86](https://www.github.com/dasch-swiss/dsp-tools/issues/86)) ([7cf6405](https://www.github.com/dasch-swiss/dsp-tools/commit/7cf6405ad045bbd97d34bc2d0a2d4872e873a78e)) -### [1.3.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.1...v1.3.2) (2021-08-17) +## [1.3.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.1...v1.3.2) (2021-08-17) ### Bug Fixes * **import:** fix import error when starting script directly ( DSP-1869) ([05b1eb1](https://www.github.com/dasch-swiss/dsp-tools/commit/05b1eb148b3dbb2c3c4c38f85cfaa7aa782c2641)) -### [1.3.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.0...v1.3.1) (2021-08-11) +## [1.3.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.0...v1.3.1) (2021-08-11) ### Bug Fixes @@ -179,7 +179,7 @@ * **excel-lists:** create multilanguage json lists from excel files ( DSP-1580) ([#75](https://www.github.com/dasch-swiss/dsp-tools/issues/75)) ([06d071a](https://www.github.com/dasch-swiss/dsp-tools/commit/06d071a6d47cd1002610c70b076319236bdab0db)) -### [1.2.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.2.0...v1.2.1) (2021-07-27) +## [1.2.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.2.0...v1.2.1) (2021-07-27) ### Bug Fixes @@ -193,14 +193,14 @@ * **verbose xml upload:** use v option to print verbose output in XML upload ( DSP-1797) ([#70](https://www.github.com/dasch-swiss/dsp-tools/issues/70)) ([b1f56a1](https://www.github.com/dasch-swiss/dsp-tools/commit/b1f56a1efe8ff32376c8e4f8bf8f292d6061e016)) -### [1.1.6](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.5...v1.1.6) (2021-07-22) +## [1.1.6](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.5...v1.1.6) (2021-07-22) ### Documentation * add changelog ([#71](https://www.github.com/dasch-swiss/dsp-tools/issues/71)) ([ce1feab](https://www.github.com/dasch-swiss/dsp-tools/commit/ce1feab45e15cb203447a906c93b7caaf951670e)) -### [1.1.5](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.4...v1.1.5) (2021-07-14) +## [1.1.5](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.4...v1.1.5) (2021-07-14) ### Documentation @@ -209,21 +209,21 @@ * **dsp-tools-xmlupload:** addition to incomplete paragraph ( DSP-1693) ([#67](https://www.github.com/dasch-swiss/dsp-tools/issues/67)) ([318547f](https://www.github.com/dasch-swiss/dsp-tools/commit/318547fd58fd015209b42a1279baef11056b585d)) -### [1.1.4](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.3...v1.1.4) (2021-06-16) +## [1.1.4](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.3...v1.1.4) (2021-06-16) ### Documentation * add copyright information to docs ( DSP-1190) ([#65](https://www.github.com/dasch-swiss/dsp-tools/issues/65)) ([0174c4a](https://www.github.com/dasch-swiss/dsp-tools/commit/0174c4afda601047a92669a2f1f92a05d75999cb)) -### [1.1.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.2...v1.1.3) (2021-06-08) +## [1.1.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.2...v1.1.3) (2021-06-08) ### Documentation * update readme after documentation update ( DSP-1693) ([#63](https://www.github.com/dasch-swiss/dsp-tools/issues/63)) ([7b7dcca](https://www.github.com/dasch-swiss/dsp-tools/commit/7b7dcca55c729aa6bf995c04ae37f50a630bf9a5)) -### [1.1.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.1...v1.1.2) (2021-06-07) +## [1.1.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.1...v1.1.2) (2021-06-07) ### Maintenance @@ -235,7 +235,7 @@ * improve documentation ( DSP-1693) ([#62](https://www.github.com/dasch-swiss/dsp-tools/issues/62)) ([591b5ad](https://www.github.com/dasch-swiss/dsp-tools/commit/591b5ad46f8c4b6aecd023ff1448953a7c6c7d45)) -### [1.1.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.0...v1.1.1) (2021-04-20) +## [1.1.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.0...v1.1.1) (2021-04-20) ### Bug Fixes diff --git a/docs/assets/style/theme.css b/docs/assets/style/theme.css index 38339e095..05ec4069e 100644 --- a/docs/assets/style/theme.css +++ b/docs/assets/style/theme.css @@ -2,3 +2,19 @@ .md-tabs { background-color: rgb(89, 73, 167) !important; } +h1 { + font-weight: bold; + padding-top: 50px; +} +h2 { + font-weight: bold; + padding-top: 50px; +} +h3 { + font-weight: bold; + padding-top: 50px; +} +h4 { + font-weight: bold; + padding-top: 50px; +} diff --git a/docs/dsp-tools-create-ontologies.md b/docs/dsp-tools-create-ontologies.md index fbc720883..4a1c48585 100644 --- a/docs/dsp-tools-create-ontologies.md +++ b/docs/dsp-tools-create-ontologies.md @@ -85,7 +85,7 @@ The following fields are mandatory: The following fields are optional: -- `comments` (but if omitted a default value `[no comment provided]`) is used +- `comments` - `super` (with the exception of `LinkValue` where `super` is mandatory) - `subject` - `gui_attributes` @@ -112,7 +112,7 @@ A resource object needs to have the following fields: The following field is optional: -- `comments` (but if omitted a default value `[no comment provided]`) is used +- `comments` A detailed description of `resources` can be found [below](#properties-object-in-detail). @@ -150,8 +150,7 @@ and "it" are supported). `"comments": { "": "", "": "", ... }` -Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is mandatory but -can be omitted. In that case the default value `[no comment provided]` (with language "en") is used. +Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is optional. ### Super @@ -170,9 +169,9 @@ The following base properties are defined by DSP: - `hasLinkTo`: This value represents a link to another resource. You have to indicate the "_object_" as a prefixed name that identifies the resource class this link points to (a ":" prepended to the name is sufficient if the resource is defined in the current ontology). -- `hasColor`: Defines a color value (_ColorValue_) -- `hasComment`: Defines a "standard" comment -- `hasGeometry`: Defines a geometry value (a JSON describing a polygon, circle or rectangle), see _ColorValue_ +- `hasColor`: Defines a color value +- `hasComment`: Defines a standard comment +- `hasGeometry`: Defines a geometry value (a JSON describing a polygon, circle or rectangle) - `isPartOf`: A special variant of _hasLinkTo_. It says that an instance of the given resource class is an integral part of another resource class. E.g. a "page" is part of a "book". - `isRegionOf`: A special variant of _hasLinkTo_. It means that the given resource class is a "region" of another @@ -196,7 +195,7 @@ Example of a `properties` object: ], "labels": { "en": "School ID", - "de": "ID der Schule" + "de": "ID der Schule", "fr": "ID de l'école" }, "gui_element": "SimpleText", @@ -320,7 +319,7 @@ A string representation of the color in the hexadecimal form e.g. "#ff8000". { "name": "hasColor", "super": [ - "hasValue" + "hasColor" ], "object": "ColorValue", "labels": { @@ -458,7 +457,7 @@ or moving images. { "name": "hasGeometry", "super": [ - "hasValue" + "hasGeometry" ], "object": "GeomValue", "labels": "Geometry", @@ -606,7 +605,7 @@ Represents a time-interval - _gui_attributes_: - `maxlength=integer` (optional): The maximum number of characters accepted - `size=integer` (optional): The size of the input field -- `Interval`: not yet implemented. +- `Interval`: Two spin boxes, one for each decimal - _gui_attributes_: No attributes *Example:* @@ -759,26 +758,28 @@ and "it" are supported). `"super": ["", "", ...]` -A resource is always derived from at least one other resource. The most generic resource class for DSP is `Resource`. A resource may be derived from resources defined in external ontologies. +A resource is always derived from at least one other resource. The most generic resource class for DSP is `Resource`. +A resource may be derived from resources defined in external ontologies. The following predefined resources are provided by DSP: -- `Resource`: A generic resource that represents an item from the real world -- `StillImageRepresentation`: An object that is connected to a still image -- `TextRepresentation`: An object that is connected to an (external) text (not yet implemented) -- `AudioRepresentation`: An object representing audio data (not yet implemented) +- `Resource`: A generic resource representing an item from the real world. This is the most general case, to be +used in all cases when your resource is none of the special cases below. +- `StillImageRepresentation`: An object representing a still image +- `TextRepresentation`: An object representing an (external) text (not yet implemented) +- `AudioRepresentation`: An object representing an audio file - `DDDRepresentation`: An object representing a 3-D representation (not yet implemented) - `DocumentRepresentation`: An object representing an opaque document (e.g. a PDF) - `MovingImageRepresentation`: An object representing a moving image (video, film) -- `ArchiveRepresentation`: An object representing a archive file (e.g. Zip) +- `ArchiveRepresentation`: An object representing an archive file (e.g. Zip) - `Annotation`: A predefined annotation object. It has automatically the following predefined properties defined: - `hasComment` (1-n) - `isAnnotationOf` (1) -- `LinkObj`: A resource class linking together several other, generic, resource classes. The class has the following +- `LinkObj`: A resource class linking together several other resource classes. The class has the following properties: - `hasComment` (1-n) - `hasLinkTo` (1-n) -- `Region`: Represents a simple region. The class has the following properties: +- `Region`: Represents a region in an image. The class has the following properties: - `hasColor` (1) - `isRegionOf` (1) - `hasGeometry` (1) @@ -812,8 +813,7 @@ resource can have as well as how many times the relation is established. `"comments": { "": "", "": "", ... }` -Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is mandatory but -can be omitted. In that case the default value `[no comment provided]` (with language "en") is used. +Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is optional. Example for a resource definition: diff --git a/docs/dsp-tools-information-for-developers.md b/docs/dsp-tools-information-for-developers.md index 4c586e88b..04d93638c 100644 --- a/docs/dsp-tools-information-for-developers.md +++ b/docs/dsp-tools-information-for-developers.md @@ -46,7 +46,6 @@ in `pyproject.toml` in the root directory of the project. ```toml [tool.autopep8] max_line_length = 180 -in-place = true experimental = true [tool.mypy] @@ -56,7 +55,7 @@ show_column_numbers = true strict = true ``` -You can use the configuration with `autopep8 --global-config pyproject.toml [file path]` +You can use the configuration with `autopep8 --global-config pyproject.toml --in-place $FilePath$` and `mypy --config-file pyproject.toml [file path]`. diff --git a/docs/dsp-tools-xmlupload.md b/docs/dsp-tools-xmlupload.md index c22df53dd..004bdf6a0 100644 --- a/docs/dsp-tools-xmlupload.md +++ b/docs/dsp-tools-xmlupload.md @@ -2,9 +2,9 @@ # DSP XML file format for importing data -With dsp-tools data can be imported into a DSP repository (on a DSP server) from an XML file. The import file is a +With dsp-tools, data can be imported into a DSP repository (on a DSP server) from an XML file. The import file is a standard XML file as described on this page. After a successful upload of the data, an output file is written (called -`id2iri_mapping_[timstamp].json`) with the mapping of internal IDs used inside the XML and their corresponding IRIs which +`id2iri_mapping_[timstamp].json`) with the mapping from the internal IDs used inside the XML to their corresponding IRIs which uniquely identify them inside DSP. This file should be kept if data is later added with the `--incremental` [option](#incremental-xml-upload). The import file must start with the standard XML header: @@ -208,29 +208,29 @@ Example for a property element of type text (``) with two value eleme ``` | ⚠ Look out | -| :--------------------------------------------------------------------------------------------------------------------------------------------- | +|:-----------------------------------------------------------------------------------------------------------------------------------------------| | In case of a cardinality 1-n, multiple `` tags have to be created inside the `` tag (do not use multiple `` tags). | The following property elements exist: -- ``: contains the path to the file -- ``: contains text values +- ``: contains a path to a file (if the resource is a multimedia resource) +- ``: contains a boolean value - ``: contains color values - ``: contains date values - ``: contains decimal values -- ``: contains a JSON geometry definition for a region -- ``: contains a [geonames.org](https://www.geonames.org/) location code +- ``: contains JSON geometry definitions for a region +- ``: contains [geonames.org](https://www.geonames.org/) location codes - ``: contains list element labels -- ``: contains [iconclass.org](http://iconclass.org/) codes +- ``: contains [iconclass.org](http://iconclass.org/) codes (not yet implemented) - ``: contains integer values - ``: contains interval values -- ``: contains time period values +- ``: contains time period values (not yet implemented) - ``: contains links to other resources +- ``: contains text values - ``: contains time values - ``: contains URI values -- ``: contains boolean values -### `` +### <bitstream> The `` element is used for bitstream data. It contains the path to a bitstream object like an image file, a ZIP container, an audio file etc. It must only be used if the resource is a `StillImageRepresentation`, an @@ -243,7 +243,7 @@ Note: Attributes: -- `permissions` : ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions` : ID or a permission set (optional, but if omitted, very restricted default permissions apply) Example: @@ -251,57 +251,40 @@ Example: postcards/images/EURUS015a.jpg ``` -### `` +### <boolean-prop> -The `` element is used for text values. It must contain at least one `` element. +The `` element is used for boolean values. It must contain exactly one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` -The `` element has the following attributes: +#### <boolean> -- `encoding`: either "utf8" or "xml" (required) - - `utf8`: The element describes a simple text without markup. The text is a simple UTF-8 string. - - `xml`: The element describes a complex text containing markup. It must follow the XML format as defined by the - [DSP standard mapping](https://docs.knora.org/03-apis/api-v1/xml-to-standoff-mapping/). -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) -- `comment`: a comment for this specific value (optional) +The `` element must contain the string "true" or "false", or the numeral 1 (true) or 0 (false). -There are two variants of text: +Attributes: -#### Simple text (UTF-8) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) +- `comment`: a comment for this specific value (optional) -An example for simple text: +Example: ```xml - - Probe bei "Wimberger". Lokal in Wien? - + + true + ``` -#### Text with markup (XML) - -dsp-tools assumes that for markup (standoff markup) the -[DSP standard mapping](https://docs.knora.org/03-apis/api-v1/xml-to-standoff-mapping/) used (custom mapping is not yet -implemented). - -Example of a text containing a link to another resource: - ```xml - - The third object and a link. - + + 0 + ``` -Please note that the `href` option within the anchor tag (``) points to an internal resource of the DSP and has to -conform to the special format `IRI:[res-id]:IRI` where [res-id] is the resource id defined within the XML import file. - -Within a text property, multiple simple and complex text values may be mixed. -### `` +### <color-prop> The `` element is used for color values. It must contain at least one `` element. @@ -309,14 +292,14 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <color> The `` element is used to indicate a color value. The color has to be given in web-notation, that is a `#` followed by 3 or 6 hex numerals. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) A property with two color values would be defined as follows: @@ -328,15 +311,15 @@ A property with two color values would be defined as follows: ``` -### `` +### <date-prop> -The `` element is used for date values. It must contain a `` element. +The `` element is used for date values. It must contain at least one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <date> the `` element contains a DSP-specific date value. It has the following format: @@ -355,7 +338,7 @@ it _month_, if also the month is omitted, the precision is _year_. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -372,7 +355,7 @@ Example: ``` -### `` +### <decimal-prop> The `` element is used for decimal values. It must contain at least one `` element. @@ -380,13 +363,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <decimal> The `` element contains a decimal number. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -397,7 +380,7 @@ Example: ``` -### `` +### <geometry-prop> The `` element is used for a geometric definition of a 2-D region (e.g. a region on an image). It must contain at least one `` element. @@ -410,7 +393,7 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <geometry> A geometry value is defined as a JSON object. It contains the following data: @@ -451,10 +434,10 @@ Example of a `` element: Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) -### `` +### <geoname-prop> The `` element is used for values that contain a [geonames.org](http://geonames.org) ID. It must contain at least one `` element. @@ -463,13 +446,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <geoname> Contains a valid [geonames.org](http://geonames.org) ID. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example (city of Vienna): @@ -480,7 +463,7 @@ Example (city of Vienna): ``` -### `` +### <list-prop> The `` element is used as entry point into a list (list node). List nodes are identified by their `name` attribute that was given when creating the list nodes (which must be unique within each list!). It must contain at least @@ -491,13 +474,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) - `list`: name of the list as defined in the ontology (required) -#### `` +#### <list> The `` element references a node in a (pull-down or hierarchical) list. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -508,7 +491,7 @@ Example: ``` -### `` (_not yet implemented_) +### <iconclass-prop> (_not yet implemented_) The `` element is used for [iconclass.org](http://iconclass.org) ID. It must contain at least one `` element. @@ -520,13 +503,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` (_not yet implemented_) +#### <iconclass> (_not yet implemented_) References an [iconclass.org](https://iconclass.org) ID. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Usage: @@ -537,7 +520,7 @@ Usage: ``` -### `` +### <integer-prop> The `` element is used for integer values. It must contain at least one `` element. @@ -545,13 +528,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <integer> The `` element contains an integer value. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -562,22 +545,22 @@ Example: ``` -### `` +### <interval-prop> -The `` element is used for time periods with start and end dates. It must contain at least one +The `` element is used for intervals between two decimal numbers. It must contain at least one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <interval> The `` element contains two decimals separated by a colon (`:`). Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -588,23 +571,23 @@ Example: ``` -### `` +### <resptr-prop> -The `` element is used to link other resources within DSP. It must contain a `` element. +The `` element is used to link other resources within DSP. It must contain at least one `` element. Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <resptr> The `` element contains either the internal ID of another resource inside the XML or the IRI of an already -existing resource on DSP. Inside the same XML file a mixture of the two is not possible. If referencing existing +existing resource on DSP. Inside the same XML file, a mixture of the two is not possible. If referencing existing resources, `xmlupload --incremental` has to be used. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -618,7 +601,65 @@ be referenced as: ``` -### `` +### <text-prop> + +The `` element is used for text values. It must contain at least one `` element. + +Attributes: + +- `name`: name of the property as defined in the ontology (required) + + +#### <text> + +The `` element has the following attributes: + +- `encoding`: either "utf8" or "xml" (required) + - `utf8`: The element describes a simple text without markup. The text is a simple UTF-8 string. + - `xml`: The element describes a complex text containing markup. It must follow the XML format as defined by the + [DSP standard mapping](https://docs.knora.org/03-apis/api-v1/xml-to-standoff-mapping/). +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) +- `comment`: a comment for this specific value (optional) + +There are two variants of text: Simple (UTF8) and complex (XML). Within a text property, multiple simple and +complex text values may be mixed. Both simple and complex text values can be used inside all gui_elements +that are defined in an ontology (SimpleText, Richtext, Textarea, see [here](dsp-tools-create-ontologies.md#textvalue)). +But typically, you would use UTF8 in a SimpleText, and XML in Richtext or Textarea. + + +#### Simple text (UTF-8) + +An example for simple text: + +```xml + + Probe bei "Wimberger". Lokal in Wien? + +``` + +If your text is very long, it is not advised to add XML-"pretty-print" whitespaces after line breaks. These +whitespaces will be taken into the text field as they are. + + +#### Text with markup (XML) + +dsp-tools assumes that for markup (standoff markup), the +[DSP standard mapping](https://docs.knora.org/03-apis/api-v1/xml-to-standoff-mapping/) is used (custom mapping is not yet +implemented). + +Example of a text containing a link to another resource: + +```xml + + The third object and a link. + +``` + +Please note that the `href` option within the anchor tag (``) points to an internal resource of the DSP and has to +conform to the special format `IRI:[res-id]:IRI` where [res-id] is the resource id defined within the XML import file. + + +### <time-prop> The `` element is used for time values. It must contain at least one ` ``` -### `` +### <uri-prop> The `` element is used for referencing resources with a URI. It must contain at least one `` element. @@ -687,13 +728,13 @@ Attributes: - `name`: name of the property as defined in the ontology (required) -#### `` +#### <uri> The `` element contains a syntactically valid URI. Attributes: -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) +- `permissions`: ID or a permission set (optional, but if omitted, very restricted default permissions apply) - `comment`: a comment for this specific value (optional) Example: @@ -704,36 +745,6 @@ Example: ``` -### `` - -The `` element is used for boolean values. It must contain a `` element. - -Attributes: - -- `name`: name of the property as defined in the ontology (required) - -#### `` - -The `` element must contain the string "true" or "false", or the numeral 1 (true) or 0 (false). - -Attributes: - -- `permissions`: ID or a permission set (optional, but if omitted very restricted default permissions apply) -- `comment`: a comment for this specific value (optional) - -Example: - -```xml - - true - -``` - -```xml - - 0 - -``` ## Incremental XML Upload