Commit a2b049dd authored by mmarkus1's avatar mmarkus1
Browse files

Add docs directory and first draft for documentations

parent 5f8477b5
# Readme for LIDO Application Profiles - Accompanying texts
This document provides guidelines for the creation and editing of accompanying texts for LIDO Application Profiles by the LIDO working group *LIDO AG*. The application profile schema allows the use of accompanying texts so that shared or more often used texts can be outsourced. This increases the overview and avoids duplication of work. There are generally two types of accompanying texts:
- general accompanying texts of LIDO in `1.1/accompanying-texts/`
- application profile specific accompanying texts in `applications-profiles/name-of-your-application-profile/accompanying-texts/`
## Usage
To add a new accompanying text, you need to create a new *.xml file in one of the above mentioned folders. Please start with the following frame:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml"
schematypens="http://purl.oclc.org/dsdl/schematron"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0" xmlns:lido="http://www.lido-schema.org">
<teiHeader>
<fileDesc>
<titleStmt>
<title>Title</title>
</titleStmt>
<publicationStmt>
<p>Information about publication or distribution</p>
</publicationStmt>
<sourceDesc>
<p>Information about the source</p>
</sourceDesc>
</fileDesc>
</teiHeader>
<text>
<body>
<div xml:id="Enter-Your-ID-Here">
<div xml:lang="Enter-Your-Language-Here">
<head n="1">Title</head>
<p>
YOUR TEXT HERE
</p>
</div>
</div>
</body>
</text>
</TEI>
```
To integrate the file and thus the accompanying text into a profile, proceed as follows:
1. Choose a unique ID and replace "Enter-Your-ID-Here"
2. Write your desired accompanying text with all options available [**see application-profiles-documentation.md**](../docs/application-profiles-documentation.md) and replace "YOUR TEXT HERE"
3. Integrate the file and the unique ID in the schema file (.xsd) where you want it as follows:
```xml
<xs:annotation xml:id="accompanying-texts">
<xs:documentation>
<xi:include href="accompanying-texts/YOUR-FILE-NAME.xml" xpointer="Your-ID-Here"/>
</xs:documentation>
</xs:annotation>
```
The automated process of publication will include the accompanying texts in the appropriate language of the documentation.
# Readme for LIDO Application Profiles
This document provides guidelines for the creation and editing of LIDO Application Profiles by the LIDO working group *LIDO AG*. The document explains the key structure and component of a LIDO Application Profile and walks through the process of developing a profile. The document is aimed at designers of application profiles.
## Usage
All application profiles are in the `applications-profiles/` folder. Each application profile has its own folder. Please keep the given structure to create or update an application profile:
- `applications-profiles/name-of-your-application-profile/`
- `applications-profiles/name-of-your-application-profile/schema-file.xsd`
- `applications-profiles/name-of-your-application-profile/img/`
- `applications-profiles/name-of-your-application-profile/accompanying-texts/`
- `1.1/accompanying-texts/`
### Schema file
The XML Schema Definition file (.xsd) is the main component of an application profile. It specifies how to formally describe the elements and how to use them (documentation) in the scope of the application. The following applies: The entire scheme is always LIDO valid. Typically, the focus is on documentation in order to support users when using a profile. Please visit [**application-profiles-documentation.md**](../docs/application-profiles-documentation.md) to learn how to create and update such an documentation.
A manual will be automatically generated from the schema file. It is important that the given structure and format in the schema file are adhered to. For more information about this automated generation visit [**lido-publication**](https://gitlab.gwdg.de/lido/lido-publication).
### Image folder
To use images in the documentation read [**application-profiles-documentation.md**](../docs/application-profiles-documentation.md). All images used must be in this folder.
### Accompanying texts
The schema allows the use of accompanying texts so that shared or more often used texts can be outsourced. This increases the overview and avoids duplication of work. Please create one file for each accompanying texts and visit [**application-profiles-accompanying-texts.md**](../docs/application-profiles-accompanying-texts.md) to learn how to use them.
# Documentation
This document provides guidelines for the creation and editing of LIDO documentation by the LIDO working group *LIDO AG*. This includes the documentation of elements, complex types and attributes using TEI elements. The serialization of the PDF and HTML documentation is based on these elements and should therefore be adhered to.
## Usage
### General
The documentation in the form of TEI elements takes place within xs: documentation directly below the element/complexTypes/Attribute, e.g.
```xml
<xs:annotation>
<xs:documentation>
<tei:ab type="definition">Holds the metadata of an object/work.</tei:ab>
</xs:documentation>
</xs:annotation>
```
All tei:ab (anonymous block) are bundled within one xs:documentation.
```xml
<xs:annotation>
<xs:documentation>
<tei:ab type="definition">Holds the metadata of an object/work.</tei:ab>
<tei:ab type="note">Use this element as root for the delivery of content through OAI-PMH.</tei:ab>
</xs:documentation>
</xs:annotation>
```
### How to describe an element
To describe an element/complexType/Attributes, use xml tei:ab[@type = 'description'].
```xml
<xs:element name="objectPublishedID" type="lido:identifierComplexType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="description">A unique, published identification of the described object/work.</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
### Notes for creating digital objects
With tei:ab[@type = 'howToRecord'], general information regardin the documentation of an element/complexTypes/attribute is given.
**Attention (do not use in production)**: It is currently unclear whether this documentation category should continue to be used.
```xml
<xs:element name="objectPublishedID" type="lido:identifierComplexType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="howToRecord">
May link to authority files maintained outside of
the contributor's documentation system or may be an identifier for the
object published by its repository, e.g. composed of an identifier for
the repository and an inventory number of the object. Preferably a
dereferenceable URL.
</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
### General notes
General information about an element/complexType/attribute that does not relate directly to the creation of digital objects can be included in tei:ab[@type = 'note'].
```xml
<xs:complexType name="materialsTechSetComplexType">
<xs:annotation>
<xs:documentation>
...
<tei:ab type="note">
Indicates the substance or material used as well as any
implement, production or manufacturing technique, process or methods
deployed.
</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:complexType>
```
### Title
For all xs:element, a title is assigned analogously to LIDO v1.0, which is recorded in tei:ab[@type = 'title']. ComplexTypes and attributes are not given a title.
```xml
<xs:element name="relatedWorkSet" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="title">Related Work Set</tei:ab>
</xs:documentation>
</xs:annotation>
</xs:element>
```
### Recommended data values
Recommended data values, especially references to controlled vocabularies, are given with tei:ab[@type = 'dataValues'].
```xml
<xs:element name="relatedWorkSet" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="dataValues">TODO</tei:ab>
</xs:documentation>
</xs:annotation>
</xs:element>
```
### Equivalences to other schemes
Tei:ab[@type = 'equivalents'] documents the other schema elements/complexTypes/attributes to which this element is equivalent. tei:label refers to the schema, while tei:item contains the equivalent element.
Correspondences are listed for CDWA Lite, museumdat, SPECTRUM and CIDOC CRM. If the present LIDO element has no correspondence in the named schemes, the value [none] is used.
```xml
<xs:element name="objectPublishedID" type="lido:identifierComplexType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
...
<tei:ab type="equivalents">
<tei:list>
<tei:label>CDWA Lite</tei:label>
<tei:item>[none]</tei:item>
<tei:label>museumdat</tei:label>
<tei:item>[none]</tei:item>
<tei:label>SPECTRUM</tei:label>
<tei:item>[none]</tei:item>
<tei:label>CIDOC CRM</tei:label>
<tei:item>[none]</tei:item>
</tei:list>
</tei:ab>
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
### Further readings
Tei: ab[@type = 'furtherReading'] is used to create links to which users can find further information about an element. It can be repeated several times.
```xml
<xs:element name="actor" type="lido:actorComplexType">
<xs:annotation>
<xs:documentation>
<tei:ab type="furtherReading">
<tei:ref target="https://www.getty.edu/research/publications/electronic_publications/cdwa/28person.html#lifeRoles">
CDWA Full 28.10 Life Roles
</tei:ref>
</tei:ab>
</xs:documentation>
</xs:annotation>
</xs:element>
```
### References and links
Tei:ref is used to reference other elements within the LIDO schema. The target attribute indicates the element that is referenced in the schema by using # and the name of the element as a reference.
```xml
<xs:element name="displayMaterialsTech" type="lido:textComplexType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="definition">
Display element for materials/techniques,
corresponding to the following <tei:ref target="#materialsTech">materialsTech element</tei:ref>.
</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
tei:ref can also be used for web links. In this case, only the URL is listed in @target.
tei:ref kann auch für Weblinks verwendet werden. In diesem Fall wird in @target lediglich die URL angeführt.
```xml
<xs:element name="gml" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
...
<tei:ab type="note">
For further documentation on GML refer to
<tei:ref target="http://www.opengis.net/gml/">http://www.opengis.net/gml/</tei:ref>.
</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
### Multilingualism
Tei:ref is used to reference other elements within the LIDO schema. The target attribute indicates the element that is referenced in the schema by using # and the name of the element as a reference.
```xml
<xs:element name="displayMaterialsTech" type="lido:textComplexType" minOccurs="0" maxOccurs="unbounded">
<xs:annotation>
<xs:documentation>
<tei:ab type="definition">
Display element for materials/techniques,
corresponding to the following <tei:ref target="#materialsTech">materialsTech element</tei:ref>.
</tei:ab>
...
</xs:documentation>
</xs:annotation>
...
</xs:element>
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment