search

ArchivesPortalEuropeFoundation / EAG2012

Maintenance of EAG2012, the Encoded Archival Guide for describing institutions with archival holdings
5 stars 1 forks source link

[Major revision] Updates to <sources> and its sub-elements #122

Open kerstarno opened 1 year ago

kerstarno commented 1 year ago

Provide a general summary of the issue in the Title above. Delete the part of the issue template that does not apply depending on whether you describe a change to an existing element / attribute or the addition of a new one.

Creator of issue

State your name, organisation and ways to reach you. Name: Kerstin Arnold Organisation: Archives Portal Europe Foundation, Working Group on Standards Email: standards@archivesportaleurope.net GitHub username (if applicable): @kerstarno

Changes to existing element / attribute

Give the current name of the element / attribute. Include the tag name and the full name. Name: <sources>, <source>, <sourceEntry>, <objectBinWrap>, and <objectXMLWrap>

Change in name

Indicate any changes in name. New name: <sourceEntry> is renamed to/replaced by <reference>

Change in context

List all parent elements to which the element / attribute should be added. Furthermore, list all parent elements from which the element / attribute should be removed.

Remove from

Parent element(s): <sourceEntry> from <source>; <objectBinWrap> from <source>; @lastDateTimeVerified from <source>

Add to

Parent element(s): <descriptiveNote> (0..1) to <sources>; <reference> (1..n) to <source> (replaces <sourceEntry>); <citedRange> (0..n) to <source> (new); @base (0), @audience with values "external" and "internal" (0), @id (0), @languageOfElement (0), @scriptOfElement (0), @target (0), and an option to include attributes from any other namespace to <sources>; @audience with values "external" and "internal" (0), @id (0), @languageOfElement (0), @scriptOfElement (0), @target (0), and an option to include attributes from any other namespace, @linkRole (0), @linkTitle (0), @valueURI (0), @vocabularySource (0), @vocabularySourceURI to <source>

Change in availability

For elements, give an indication of their changed availability within each affected parent element ("1..1" for required but not repeatable, "1 (or another number)..n" for required and repeatable, "0..1" for optional but not repeatable", "0..n" for optional and repeatable). For added attributes, indicate their changed availability with "1" for required or "0" for optional within each affected parent element. Changed availability: While <sourceEntry> was optional and not repeatable with <source>, <reference> now is required and repeatable; for conversion from EAG 2012 to EAG 3.0, an empty <reference/> would need to be added for validation reasons if <sourceEntry> doesn't exist.

Change in content model (elements)

List all sub-elements and attributes that should be removed from or added to the element's content model.

New element / attribute

Give the name of the new element / attribute. Include the tag name and the full name. Name: <citedRange> (Cited Range)

Context and availability

List all parent elements to which the element / attribute should be added. For elements, give an indication of their availability within each parent element ("1..1" for required but not repeatable, "1 (or another number)..n" for required and repeatable, "0..1" for optional but not repeatable", "0..n" for optional and repeatable). For attributes, indicate their availability with "1" for required or "0" for optional within each parent element. Parent element(s): <source> (0..n)

Content model (elements)

List all sub-elements and attributes of the new element. For sub-elements, give an indication of their availability ("1..1" for required but not repeatable, "1 (or another number)..n" for required and repeatable, "0..1" for optional but not repeatable", "0..n" for optional and repeatable). For attributes, indicate their availability with "1" for required or "0" for optional. Sub-element(s): [text] Attributes (with default values, if applicable): @audience with values "external" and "internal" (0), @id (0), @languageOfElement (0), @scriptOfElement (0), @target (0), and an option to include attributes from any other namespace, @unit (here without any predefined values, but data type token) (0)

Example for usage of the new / changed element (including potential attributes)

Describe how the new / changed element should be used. Write your text after the "Text:" below. Text: <citedRange> is used as an optional child element of <source> that identifies precisely where supporting evidence was found within the source. The attribute @unit can be used with any text to e.g. state a "page number" or a "chapter number" or similar units to specify the cited part of a source.

Example of XML code

Provide a sample encoding in XML of the new / changed element (with potential attributes). Write your text after the "Example:" below. Example:

<source>
  <reference>The autobiography of Jane Smith</reference>
  <citedRange unit="pageNumber">10-15</citedRange>
</source>
kerstarno commented 1 year ago

For conversion, the current encoding

<sources>
  <source href="link to source 1" lastDateTimeVerified="[YYYY-MM-DD of source 1]">
    <sourceEntry xml:lang="language of sourceEntry" scriptCode="script of sourceEntry" transliteration="transliteration rule for sourceEntry" source="source of sourceEntry">sourceEntry</sourceEntry>
    <objectBinWrap>[binary data for objectBinWrap of source 1]</objectBinWrap>
    <objectXMLWrap>[some other namespace XML encoding for objectXMLWrap of source 1]</objectXMLWrap>
    <descriptiveNote>
      <p>p of descriptiveNote</p>
    </descriptiveNote>
  </source>
  <source href="link to source 2" lastDateTimeVerified="[YYYY-MM-DD of source 2]">
    <objectXMLWrap>[some other namespace XML encoding for objectXMLWrap of source 2]</objectXMLWrap>
    <descriptiveNote>
      <p>p of descriptiveNote</p>
    </descriptiveNote>
  </source>
</sources>

becomes

<sources>
  <source href="link to source 1">
    <reference languageOfElement="language of sourceEntry" scriptOfElement="script of sourceEntry" conventionDeclarationReference="#conDec1" sourceReference="#source3">sourceEntry</sourceEntry>
    <descriptiveNote>
      <p>p of descriptiveNote</p>
    </descriptiveNote>
    <objectXMLWrap>[some other namespace XML encoding for objectXMLWrap of source 1]</objectXMLWrap>
  </source>
  <source href="link to source 2">
    <reference/>
    <descriptiveNote>
      <p>p of descriptiveNote</p>
    </descriptiveNote>
    <objectXMLWrap>[some other namespace XML encoding for objectXMLWrap of source 2]</objectXMLWrap>
  </source>
  <source id="source3">
    <reference>source of sourceEntry</reference>
  <source>
</sources>
<conventionDeclaration id="conDec1">
  <reference>transliteration rule for sourceEntry</reference>
</conventionDeclaration>

For the detailed conversion of <descriptiveNote> see examples in other issues, e.g. #116.