Skip to content

Commit

Permalink
Merge pull request #593 from VisLab/develop
Browse files Browse the repository at this point in the history 
Minor typo and link corrections
  • Loading branch information
@VisLab
VisLab authored May 30, 2024
2 parents 5538c30 + d929e9b commit 0d8303e
Show file tree
Hide file tree
Showing 5 changed files with 66 additions and 63 deletions.
8 changes: 4 additions & 4 deletions docs/source/03_HED_formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Both formats must be available and synchronized in the
Regardless of the format, a valid HED schema must have the following sections in this order:

````{Admonition} Required sections of a HED schema (in the required order):
| Section | Mediawiki format | XML format |
| Section | MediaWiki format | XML format |
|------- | --------- | ---------- |
| Header line | `HED version="8.0.0"` | `<HED version="8.0.0">` |
| Prologue | `'''Prologue'''` | `<prologue> ... </prologue>` |
Expand Down Expand Up @@ -293,9 +293,9 @@ Units and unit modifiers follow the naming conventions of the units they represe
Case is preserved for unit modifiers, as uppercase and lowercase versions often have distinct meanings. The case for unit symbols is also maintained.


### 3.1.4. Mediawiki schema format
### 3.1.4. MediaWiki schema format

[**Mediawiki**](https://www.mediawiki.org/wiki/Cheatsheet) is a markdown-like format that was
[**MediaWiki**](https://www.mediawiki.org/wiki/Cheatsheet) is a markdown-like format that was
selected as the HED schema editing format because of its flexibility
and ability to represent nested or hierarchical relationships.

Expand Down Expand Up @@ -403,7 +403,7 @@ everything after the asterisks, including the `#` placeholder, enclosed by `<now


Additional details and rules can be found in appendix
[**A.2 Mediawiki file format**](./Appendix_A.md#a2-mediawiki-file-format)
[**A.2 MediaWiki file format**](./Appendix_A.md#a2-mediawiki-file-format)

### 3.1.5. XML schema format

Expand Down
2 changes: 1 addition & 1 deletion docs/source/07_Library_schemas.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ containing only the information specific to the library schema.
The following example shows the header for the `.mediawiki` developer's version
of a partnered library schema.

````{admonition} Mediawiki header for TESTLIB library 2.0.0 partnered with 8.2.0 (unmerged).
````{admonition} MediaWiki header for TESTLIB library 2.0.0 partnered with 8.2.0 (unmerged).
```html
HED library="testlib" version="2.0.0" withStandard="8.2.0" unmerged="true"
```
Expand Down
107 changes: 55 additions & 52 deletions docs/source/08_HED_ontology.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,26 +69,26 @@ In this document we use OWL Manchester format (`.omn`) for readability.

The HED vocabularies have 4 different formats as shown in the following table:

| Format | Content | Uses | Editing |
| ------ | ------- | ---- | ------- |
| Mediawiki | Schema | Schema development<br/>Schema updating | Manual editing<br/>Updated from spreadsheet |
| XML | Schema | Annotation tools<br/>Validation tools<br/>Analysis tools | Generated from MediaWiki |
| Format | Content | Uses | Editing |
|-------------| ------- | ---- | ------- |
| MediaWiki | Schema | Schema development<br/>Schema updating | Manual editing<br/>Updated from spreadsheet |
| XML | Schema | Annotation tools<br/>Validation tools<br/>Analysis tools | Generated from MediaWiki |
| Spreadsheet | Complete | Schema development<br/>Schema updating<br/>Ontology updating | Manual editing<br/>Updated from MediaWiki<br/>Updated from OWL |
| OWL | Complete | Ontology updating<br/>Semantic validation<br/>Documentation generation<br/>Semantic tools | Manual editing<br/>Updated from spreadsheet |
| OWL | Complete | Ontology updating<br/>Semantic validation<br/>Documentation generation<br/>Semantic tools | Manual editing<br/>Updated from spreadsheet |

The HED schema, which contains the core HED vocabulary and captures the "annotator's view" of HED,
can be completely represented in the HED Mediawiki, XML, or spreadsheet formats.
can be completely represented in the HED MediaWiki, XML, or spreadsheet formats.
The HED schema is used for annotation, validation, searching, and most analyses.
Tools access the HED schema in its XML format, but schema developers usually create
and update the schema in Mediawiki format, which is easier to read and displays as formatted
and update the schema in MediaWiki format, which is easier to read and displays as formatted
MarkDown on GitHub.
Alternatively schema developers may opt to create or update schemas from the HED spreadsheets.

#### 8.1.4.1. The Mediawiki format
The Mediawiki format is line-oriented with each non-blank line corresponding to a HED tag or other HED entity
#### 8.1.4.1. The MediaWiki format
The MediaWiki format is line-oriented with each non-blank line corresponding to a HED tag or other HED entity
such as a unit class or schema attribute definition.
See [**A.2. Mediawiki file format**](./Appendix_A.md#a-2-mediawiki-file-format)
for a detailed description of the Mediawiki format.
See [**A.2. MediaWiki file format**](./Appendix_A.md#a2-mediawiki-file-format)
for a detailed description of the MediaWiki format.

#### 8.1.4.2. Spreadsheet files

Expand Down Expand Up @@ -147,9 +147,9 @@ the Dublin Core or the RDF schema (e.g., `dc:comment`) and the HED ontology fram
include them in the ontology. However, these columns do not impact the HED schema.


#### 8.1.4.4. Spreadsheet <--> Mediawiki
#### 8.1.4.4. Spreadsheet <--> MediaWiki

Each non-blank line in a HED Mediawiki file corresponds to a single HED entity such as a HED tag.
Each non-blank line in a HED MediaWiki file corresponds to a single HED entity such as a HED tag.
Similarly, each row in a HED spreadsheet file corresponds to a single HED entity.
The fields of the HED MediaWiki format have a specific mapping to columns in a HED spreadsheet
as illustrated in the following example:
Expand All @@ -162,15 +162,18 @@ but the above diagram has formatted the information so that it will fit within i
The mapping of the spreadsheet row and column values to a line in the MediaWiki is further explained in the
following table:

| Spreadsheet<br/>column | Row value | MediaWiki format |
| ----------- |:------------------:| ------- |
| **hedId** | *xxx* | {hedId=*xxx*, ... other attributes in comma separated list} |
| **Level** | 0 | This row corresponds to a top-level HED tag. **EX:** `'''tag'''`. |
| Spreadsheet<br/>column | Row value | MediaWiki format |
| ----------- |:------------------:|-------------------------------------------------------------------------------------------------------------------|
| **hedId** | *xxx* | {hedId=*xxx*, ... other attributes in comma separated list} |
| **rdfs:label** | *yyy* | The tag's unique name is *yyy*. |
| **Level** | 0 | This row corresponds to a top-level HED tag. **EX:** `'''tag'''`. |
| **Level** | *n* | For level *n* > 0, *n* asterisks appear in front of `tag`.<br/>Example: `* tag` when *n* = 1. **EX:** `** tag` when *n*=2. |
| **rdfs:label** | *yyy* | The tag's unique name is *yyy*. |
| **omn:SubClassOf** | *zzz* | The tag's parent tag in the HED hierarchy is *zzz*. |
| **Attributes** | *uuu*, *vvv*, ... | List appearing in curly braces: {hedId=*xxx*, *uuu*, *vvv*, ...} |
| **dc:description** | *www* | The contents of the square braces: [*www*]. |
| **omn:SubClassOf** | *zzz* | The tag's parent tag in the HED hierarchy is *zzz*. |
| **Attributes** | *uuu*, *vvv*, ... | List appearing in curly braces: {hedId=*xxx*, *uuu*, *vvv*, ...} |
| **dc:description** | *www* | The contents of the square braces: [*www*]. |

Note: Attributes that have boolean values are true if the attribute is present and false if absent.
Non-boolean attributes are specified using "attribute-name=value".

HED schema developers can develop in either HED MediaWiki or HED spreadsheet (tab-separated-value) file format and
can use tools to update the representations.
Expand Down Expand Up @@ -306,7 +309,7 @@ HED schema must satisfy the **is-a** relationship with its parent in the HED sch
The examples of this section use the `Action` tag and its child `Communicate`
to illustrate how subclassing is represented in the various HED formats.

#### 8.2.2.1. Mediawiki tag format
#### 8.2.2.1. MediaWiki tag format

The **MediaWiki** representation uses ordering and asterisks to mark parentage relationships.
In other words, the HED MediaWiki schema tree is given in depth-first search order.
Expand All @@ -326,7 +329,7 @@ The `Communicate` tag is a child (subclass) of `Action`.
```
In this example `Action` is level 0 (top-level) and `Communicate` is level 1.
Mediawiki uses ordering to determine subclasses.
MediaWiki uses ordering to determine subclasses.
Since `Action` is the closest preceding tag whose level is one less than
that of `Communicate`, so `Action` is the parent tag of `Communicate`.
Expand Down Expand Up @@ -470,34 +473,34 @@ The following table lists schema attributes with their types (A=`AnnotationPrope
and O=`ObjectProperty`), domains and ranges.

| Attribute | Type | Domain | Range | Handling
| --------- | ---------- | --------- | ---------- | ------|
| `allowedCharacter` | D | `unitDomain`<br/>`unitModifierDomain`<br/>`valueClassDomain` | string | |
| `conversionFactor` | D | `unitDomain`<br/>`unitModifierDomain` | `numericRange` | |
| `defaultUnits` | O | `unitClassDomain` | `unitRange` | |
| `deprecatedFrom` | D | `elementDomain` | `stringRange` | |
| `extensionAllowed` | | `tagDomain` | `boolRange` | |
| `hedId` | A | `elementDomain` | `stringRange` | Tools: Assign and verify. |
| `inLibrary` | D | `elementDomain` | `stringRange` | |
| `isPartOf` | O | `tagDomain` | `tagRange` | |
| `relatedTag` | O | `tagDomain` | `tagRange` | |
| `requireChild` | A | `tagDomain` | `boolRange` | Tools: Verify. |
| `reserved` | D | `tagDomain` | `boolRange` | |
| `rooted` | A | `tagDomain` | `tagRange` | Tools: make tag subclass of tag in range. |
| `SIUnit` | D | `unitDomain` | `boolRange` | |
| `SIUnitModifier` | D | `unitModifierDomain` | `boolRange` | | |
| `SIUnitSymbolModifier` | D | `SIUnitSymbolModifier` | `boolRange` | |
| `suggestedTag` | O | `tagDomain` | `tagRange` | |
| `tagGroup` | D | `tagDomain` | `boolRange` | |
| `takesValue` | A | `tagDomain` | `boolRange` | Only placeholders |
| `topLevelTagGroup` | D | `tagDomain` | `boolRange` | |
| `unique` | D |`tagDomain` | `boolRange` | |
| `unitClass` | O | `tagDomain` | `unitRange` | |
| `unitPrefix` | D | `unitDomain` | `boolRange` | |
| `unitSymbol` | D |`unitDomain` | `boolRange` | |
| `valueClass` | O | `tagDomain` | `valueClassRange` | |


#### 8.2.3.4. Mediawiki attribute format
| --------- |------| --------- | ---------- | ------|
| `allowedCharacter` | D | `unitDomain`<br/>`unitModifierDomain`<br/>`valueClassDomain` | string | |
| `conversionFactor` | D | `unitDomain`<br/>`unitModifierDomain` | `numericRange` | |
| `defaultUnits` | O | `unitClassDomain` | `unitRange` | |
| `deprecatedFrom` | D | `elementDomain` | `stringRange` | |
| `extensionAllowed` | D | `tagDomain` | `boolRange` | |
| `hedId` | A | `elementDomain` | `stringRange` | Tools: Assign and verify. |
| `inLibrary` | D | `elementDomain` | `stringRange` | |
| `isPartOf` | O | `tagDomain` | `tagRange` | |
| `relatedTag` | O | `tagDomain` | `tagRange` | |
| `requireChild` | A | `tagDomain` | `boolRange` | Tools: Verify. |
| `reserved` | D | `tagDomain` | `boolRange` | |
| `rooted` | A | `tagDomain` | `tagRange` | Tools: make tag subclass of tag in range. |
| `SIUnit` | D | `unitDomain` | `boolRange` | |
| `SIUnitModifier` | D | `unitModifierDomain` | `boolRange` | | |
| `SIUnitSymbolModifier` | D | `SIUnitSymbolModifier` | `boolRange` | |
| `suggestedTag` | O | `tagDomain` | `tagRange` | |
| `tagGroup` | D | `tagDomain` | `boolRange` | |
| `takesValue` | A | `tagDomain` | `boolRange` | Only placeholders |
| `topLevelTagGroup` | D | `tagDomain` | `boolRange` | |
| `unique` | D |`tagDomain` | `boolRange` | |
| `unitClass` | O | `tagDomain` | `unitRange` | |
| `unitPrefix` | D | `unitDomain` | `boolRange` | |
| `unitSymbol` | D |`unitDomain` | `boolRange` | |
| `valueClass` | O | `tagDomain` | `valueClassRange` | |


#### 8.2.3.4. MediaWiki attribute format

In the MediaWiki format, schema attributes appear in the `Schema Attributes` section of the schema.

Expand All @@ -509,7 +512,7 @@ In the MediaWiki format, schema attributes appear in the `Schema Attributes` sec
under this tag. This tag is propagated to child nodes except for
hashtag placeholders.]</nowiki>
```
Note: this example has line breaks added to fit on the page. Each element in Mediawiki must appear on one line.
Note: this example has line breaks added to fit on the page. Each element in MediaWiki must appear on one line.
````
The `extensionAllowed` attribute has a unique `hedId` value `HED_0010307`. The `tagDomain` attribute indicates that
`extensionAllowed` is only a schema attribute of HED tags.
Expand Down
10 changes: 5 additions & 5 deletions docs/source/Appendix_A.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -537,9 +537,9 @@ their role and to facilitate mapping to the HED ontology.
````
See [**property example**](#a255-schema-properties) for an example in MediaWiki format and its
https://hed-specification.readthedocs.io/en/latest/Appendix_A.html#a-3-5-5-schema-properties
## A.2. Mediawiki file format
See [**property example**](#a255-schema-properties) for an example in MediaWiki format.
## A.2. MediaWiki file format
The rules for creating a valid `.mediawiki` specification of a HED schema are given below.
The format is line-oriented, meaning that all information about an individual entity
Expand Down Expand Up @@ -640,7 +640,7 @@ directory of the [**hed-schemas**](https://github.com/hed-standard/hed-schemas)
A warning is generated when unknown header attributes are translated as attributes of the `HED` line
during `.mediawiki` file validation.
### A.2.3. Mediawiki prologue and epilogue
### A.2.3. MediaWiki prologue and epilogue
The prologue is an optional paragraph of text appearing after the *header*.
The prologue is used by tools for help and display purposes.
Expand All @@ -656,7 +656,7 @@ The epilogue appears directly before the ending line of the file.
Both the prologue and epilogue may contain commas and new lines in addition
to the characters specified by the [`textClass`](./Appendix_A.md#a13-value-classes).
### A.2.4. Mediawiki schema section
### A.2.4. MediaWiki schema section
The beginning of the actual specification of the HED vocabulary is marked by the *start-line*:
Expand Down
2 changes: 1 addition & 1 deletion docs/source/Appendix_B.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -474,7 +474,7 @@ schema attributes, properties and epilogue) are not in the correct order and hen
**b.** A HED version specification does not have the correct syntax for the schema file format.
**c.** A HED schema version does not comply with semantic versioning.

### B.2.3. Mediawiki format errors
### B.2.3. MediaWiki format errors

#### WIKI_DELIMITERS_INVALID

Expand Down

0 comments on commit 0d8303e

Please sign in to comment.