From a7ecd47156b62edc07270c04574bcf105941e2d3 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com> Date: Tue, 31 Oct 2023 11:16:09 +0100 Subject: [PATCH] docs: fix typos in docs (#615) --- docs/excel2xml-module.md | 6 ++-- docs/file-formats/excel2json.md | 8 ++--- docs/file-formats/excel2xml.md | 4 +-- docs/file-formats/json-project/caveats.md | 2 +- docs/file-formats/json-project/ontologies.md | 22 ++++++------ docs/file-formats/json-project/overview.md | 37 ++++++++++---------- docs/file-formats/xml-data-file.md | 4 +-- 7 files changed, 42 insertions(+), 41 deletions(-) diff --git a/docs/excel2xml-module.md b/docs/excel2xml-module.md index 5662e7de8..af6e7a7ec 100644 --- a/docs/excel2xml-module.md +++ b/docs/excel2xml-module.md @@ -302,7 +302,7 @@ At the very end, save the file under a name that you can choose yourself. The method `check_notna(cell)` checks a value if it is usable in the context of data archiving. A value is considered usable if it is -- a number (integer or float, but not numpy.nan) +- a number (integer or float, but not `numpy.nan`) - a boolean - a string with at least one Unicode letter (matching the regex ``\\p{L}``) or number, or at least one _, !, or ? (The strings "None", "<NA>", "N/A", and "-" are considered invalid.) @@ -340,8 +340,8 @@ might expect: |--------------|------------------------------|------------------------------------------------------------------| | 0 | False | True, because 0 is a valid integer for your integer property | | " " | True | False, because an empty string is not usable for a text property | -| numpy.nan | True | False, because N/A is not a usable value | -| pandas.NA | TypeError (*) | False, because N/A is not a usable value | +| `numpy.nan` | True | False, because N/A is not a usable value | +| `pandas.NA` | TypeError (*) | False, because N/A is not a usable value | | "<NA>" | True | False, because this is the string representation of N/A | | "-" | True | False, because this is a placeholder in an empty text field | (*) TypeError: boolean value of NA is ambiguous diff --git a/docs/file-formats/excel2json.md b/docs/file-formats/excel2json.md index a1bd66d08..e284c3f63 100644 --- a/docs/file-formats/excel2json.md +++ b/docs/file-formats/excel2json.md @@ -84,7 +84,7 @@ The expected columns are: (optional): Description of the resource class. Can be longer than the label. - [`super`](./json-project/ontologies.md#resource-super) (mandatory): The type of this resource class, - i.e. the base resource class(es) that this resource class is derived from. + i.e. the base resource class/classes that this resource class is derived from. Must be one of the values listed in the documentation. If more than one: separated by commas. @@ -136,7 +136,7 @@ The expected columns are: - [`comment_en`, `comment_de`, `comment_fr`, `comment_it`, `comment_rm`](./json-project/ontologies.md#property-comments) (optional): Description of the property. Can be longer than the label. - [`super`](./json-project/ontologies.md#property-super) - (mandatory): The type of this property, i.e. the base property/ies that this property is derived from. + (mandatory): The type of this property, i.e. the base property/properties that this property is derived from. Must be one of the values listed in the documentation. If more than one: separated by commas. - [`object`](./json-project/ontologies.md#property-object-gui_element-gui_attributes) @@ -154,7 +154,7 @@ The expected columns are: - [`gui_attributes`](./json-project/ontologies.md#property-object-gui_element-gui_attributes) (only mandatory for lists): Some `gui_element`s need further specifications. Read the documentation of the respective `object` to learn if your `gui_element` needs a `gui_attributes`. - Form: "attr: value, attr: value". + Form: `attr: value, attr: value`. The optional columns may be omitted in the Excel. @@ -188,7 +188,7 @@ Some notes: file has to be in the exact same cell as the one in the first Excel file. - Only Excel files with file extension `.xlsx` are considered. - The file name must consist of the language label, e.g. `de.xlsx` / `en.xlsx`. -- The language has to be one of {de, en, fr, it, rm}. +- The language has to be one of {`de`, `en`, `fr`, `it`, `rm`}. - As node name, a simplified version of the English label is taken. If English is not available, one of the other languages is taken. - If there are two nodes with the same name, an incrementing number is appended to the name. diff --git a/docs/file-formats/excel2xml.md b/docs/file-formats/excel2xml.md index 4c0d08a2e..12f9608de 100644 --- a/docs/file-formats/excel2xml.md +++ b/docs/file-formats/excel2xml.md @@ -14,9 +14,9 @@ The Excel/CSV file must be structured as in this image: Some notes: -- The special tags ``, ``, and `` are represented as resources of restype `Annotation`, +- The special tags ``, ``, and `` are represented as resources of the type `Annotation`, `LinkObj`, and `Region`. -- The columns "ark", "iri", and "creation_date" are only used for DaSCH internal data migration. +- The columns `ark`, `iri`, and `creation_date` are only used for DaSCH internal data migration. - If `file` is provided, but no `file permissions`, an attempt will be started to deduce them from the resource permissions (`res-default` → `prop-default` and `res-restricted` → `prop-restricted`). If this attempt is not successful, a `BaseError` will be raised. diff --git a/docs/file-formats/json-project/caveats.md b/docs/file-formats/json-project/caveats.md index 5c2f371b0..3a7f7e6f2 100644 --- a/docs/file-formats/json-project/caveats.md +++ b/docs/file-formats/json-project/caveats.md @@ -33,7 +33,7 @@ it is necessary to reference entities that are defined elsewhere. The following ## DSP Base Resources and Base Properties to be Used Directly in the XML File -From several DSP base resources no subclasses can be created in a project ontology. +From several DSP base resources, no subclasses can be created in a project ontology. However, they can be used directly in the XML data file: - `Annotation` is an annotation to another resource of any class. diff --git a/docs/file-formats/json-project/ontologies.md b/docs/file-formats/json-project/ontologies.md index 1a0ac6769..84c592a58 100644 --- a/docs/file-formats/json-project/ontologies.md +++ b/docs/file-formats/json-project/ontologies.md @@ -14,9 +14,9 @@ An ontology thus has to offer at least two things: - **properties** describing these resources. These properties are linked either to a final value or may define a relationship to another resource. -Let's assume that we define a resource class called "Person" and two properties called "hasBirthday" and "hasParent". -For a specific **instance** of a "Person", "hasBirthday" will have a final value such as "1960-05-21", whereas -"hasParent" will link to another instance of a "Person". +Let's assume that we define a resource class called `Person` and two properties called `hasBirthday` and `hasParent`. +For a specific **instance** of a `Person`, `hasBirthday` will have a final value such as "1960-05-21", whereas +`hasParent` will link to another instance of a `Person`. Within DSP, properties may be re-used for different resources. E.g. a property "description" may be used for a resource called "image" as well as "movie". Therefore, the list of properties is separated from the list of resources. The @@ -164,7 +164,7 @@ but in most cases it doesn't make sense to omit them.) `"name": ""` -A name for the property, e.g. "pageOf", "hasBirthdate", "createdBy". It should be in the form of +A name for the property, e.g. `pageOf`, `hasBirthdate`, `createdBy`. It should be in the form of a [xsd:NCNAME](https://www.w3.org/TR/xmlschema11-2/#NCName). This means a string without blanks or special characters but `-` and `_` are allowed (although not as first character). @@ -178,8 +178,8 @@ By convention, property names start with a lower case letter. `"labels": {"": "", ...}` -Collection of `labels` for the property as strings with language tag (currently "en", "de", "fr", "it", -and "rm" are supported). +Collection of `labels` for the property as strings with language tag +(currently, `en`, `de`, `fr`, `it`, and `rm` are supported). @@ -189,7 +189,7 @@ and "rm" are supported). `"comments": { "": "", "": "", ... }` -Comments with language tags. Currently, "de", "en", "fr", "it", and "rm" are supported. +Comments with language tags. Currently, `de`, `en`, `fr`, `it`, and `rm` are supported. The `comments` element is optional. @@ -986,9 +986,8 @@ By convention, resource names start with an upper case letter. `"labels": {"": "", ...}` -Collection of `labels` for the resource as strings with language tag (currently "en", "de", "fr", "it", -and "rm" are supported). - +Collection of `labels` for the resource as strings with language tag +(currently, `en`, `de`, `fr`, `it`, and `rm` are supported). ### Resource: `super` @@ -1071,5 +1070,6 @@ but in most cases it doesn't make sense to omit them.) `"comments": { "": "", "": "", ... }` -Comments with language tags. Currently, "de", "en", "fr", "it", and "rm" are supported. +Comments with language tags +(currently, `en`, `de`, `fr`, `it`, and `rm` are supported). The `comments` element is optional. diff --git a/docs/file-formats/json-project/overview.md b/docs/file-formats/json-project/overview.md index 3afe1ac24..efeac6215 100644 --- a/docs/file-formats/json-project/overview.md +++ b/docs/file-formats/json-project/overview.md @@ -69,7 +69,7 @@ A complete project definition looks like this: The `prefixes` object contains the prefixes of external ontologies that are used in the current file. All prefixes are composed of the prefix and a URI. The prefix is used as namespace, so one does not have to write the -fully qualified name of the referenced object each time it is used. Instead of writing a property called "familyName" +fully qualified name of the referenced object each time it is used. Instead of writing a property called `familyName` as `http://xmlns.com/foaf/0.1/familyName` one can simply write `foaf:familyName`. ```json @@ -166,8 +166,8 @@ The longname is a string that provides the full name of the project. `"descriptions": {"": "", ...}` -The description is represented as a collection of strings with language tags (currently, "en", "de", "fr", "it", and -"rm" are supported). +The description is represented as a collection of strings with language tags +(currently, `en`, `de`, `fr`, `it`, and `rm` are supported). @@ -197,8 +197,9 @@ The groups that were created here are then available in the XML file in the A project specific group definition has the following elements: - _name_ (mandatory): name of the group -- _descriptions_ (mandatory): description of the group with language tags in the form `"descriptions": {"": - "", ...}` (currently, "en", "de", "fr", "it", and "rm" are supported) +- _descriptions_ (mandatory): description of the group with language tags in the form + `"descriptions": {"": "", ...}` + (currently, `en`, `de`, `fr`, `it`, and `rm` are supported). - _selfjoin_ (optional): true if users are allowed to join the group themselves, false (default) if a `ProjectAdmin` has to add them - _status_ (optional): true (default) if the group is active, false if the group is inactive @@ -228,23 +229,23 @@ Example: This object contains user definitions. A user has the following elements: -- _username_: username used for login -- _email_: email that identifies the user, has to be unique within DSP -- _givenName_: first name of the user -- _familyName_: surname of the user -- _password_: password of the user -- _lang_: the default language of the user: "en", "de", "fr", "it", "rm" (optional, default: "en") -- _groups_ (optional): List of groups the user belongs to. The group names must be provided in one of the following forms: +- `username`: username used for login +- `email`: email that identifies the user, has to be unique within DSP +- `givenName`: first name of the user +- `familyName`: surname of the user +- `password`: password of the user +- `lang`: the default language of the user: `en`, `de`, `fr`, `it`, `rm` (optional, default: `en`) +- `groups` (optional): List of groups the user belongs to. The group names must be provided in one of the following forms: - `other_project_shortname:groupname` - `:groupname` (for groups defined in the current JSON project file) - `SystemAdmin` (the most powerful group, built-in into DSP) -- _projects_ (optional): List of projects the user belongs to. The project name has to be followed by a `:` and either +- `projects` (optional): List of projects the user belongs to. The project name has to be followed by a `:` and either `member` or `admin`. This indicates if the new user has admin rights in the given project or is an ordinary user. `myproject:admin` would add the user as admin to the project `myproject`. The project defined in the same JSON project file can be omitted, so only `:admin` or `:member` is enough. Note that in order to give a user `:admin` rights, he also needs to be a `:member` of the project. - If _projects_ is omitted, the user won't be part in any project. -- _status_ (optional): true (default) if the user is active, false if the user is deleted/inactive +- `status` (optional): true (default) if the user is active, false if the user is deleted/inactive Example: @@ -298,9 +299,9 @@ A node of a list may have the following elements: - `name` (mandatory): Name of the node. Has to be unique within the entire "lists" section. - `labels` (mandatory): Label with language tags in the form `{"": "