[Major revision] Updates to <descriptiveNote> and sub-element <p> (with <reference> and <span>)

[kerstarno]

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: <descriptiveNote>, <p>

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): <descriptiveNote> is removed from <repository>, <repositorhist> (which has been replaced with <biogHist> which only uses <p> directly, see #126), <building>, <computerPlaces>, <researchServices>, <internetAccess>, <refreshment>, <exhibition>, <toursSessions>, <otherServices>, <resourceRelation> and <eagRelation> (both replaced with <relation>, see #107)

  Add to

• Parent element(s): <descriptiveNote> is added to <sources>, <identity>, <otherRepositoryType> and <otherRepositoryTypes> (both new, see #129), <place> and <places> (both new, see #123), <function> and <functions> and <legalStatus> and <legalStatuses> (all new, see #135) and <mandate> and <mandates> and <existDates> (all new, see #125), <library>, <searchroom>, <relations> (see #103) and <relation> (see #107)
• Parent element(s): <p> is directly available in <biogHist> (see #126) and in <structureOrGenealogy> (see #136)

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: <descriptiveNote> is now optional in all contexts within EAG 3.0

Change in content model (elements)

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

Remove

Sub-element(s): n/a Attributes (with default values, if applicable): remove @xml:lang and @source from <p> (replaced with @languageOfElement and @sourceReference respectively)

Add

• Sub-element(s): add sub-elements <reference> and <span> to <p>, both optional and repeatable (0..n)
  • <reference> allows for text and for <span> (0..n) and for the attributes @audience with values "external" or "internal" (0), @id (0), languageOfElement (0), @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0), @href (0), @linkRole (0), @linkTitle (0) and an option to add attributes from any other namespace.
  • <span> allows for text and for the attributes @audience with values "external" or "internal" (0), @id (0), languageOfElement (0), @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0), @style (0) with the data type normalizedString, @localType (0), @localTypeDeclarationReference and an option to add attributes from any other namespace
  • @style is meant to allow for the inclusion of any CSS formatting values from font style to colour to text alignment (which would mainly be a recommendation made in the EAG 3.0 Tag Library, but would not be prescribed by the schema)
• Attributes (with default values, if applicable): add @audience with values "external" or "internal" (0), @id (0), languageOfElement (0), @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0), and an option to add attributes from any other namespace to <descriptiveNote>
• Attributes (with default values, if applicable): add @audience with values "external" or "internal" (0), @id (0), languageOfElement (0) - replaces @xml:lang, @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0) - replaces @sourceReference, and an option to add attributes from any other namespace to <p>

New element / attribute

Give the name of the new element / attribute. Include the tag name and the full name. Name: <reference> (in <conventionDeclaration>, <localTypeDeclaration>, and <rightsDeclaration> a replacement for <citation>, see #119), <span>

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):

• <reference> is available in <p> (0..n), <eventDescription> (0..n), <source> (1..n) - replaces <sourceEntry> (see #97), <conventionDeclaration> (1..1), <localTypeDeclaration> (1..1), <rightsDeclaration> (1..1) - replaces <citation> in the previous three elements (see #119), <abstract> (0..n), <chronItem> (0..n), <event> (0..n), <chronItemSet> (0..n), and <item> (0..n) - all new (see #126)
• <span> is available in <p> (0..n), <reference> (0..n), <eventDescription> (0..n), <head> (0..n), <abstract> (0..n), <event> (0..n), and <item> (0..n) - the last four are all new (see #126)

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.

• <reference> allows for text and for <span> (0..n) and for the attributes @audience with values "external" or "internal" (0), @id (0), languageOfElement (0), @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0), @href (0), @linkRole (0), @linkTitle (0) and an option to add attributes from any other namespace.
• <span> allows for text and for the attributes @audience with values "external" or "internal" (0), @id (0), languageOfElement (0), @scriptOfElement (0), @target (0),@conventionDeclarationReference (0), @maintenanceEventReference(0), @sourceReference (0), @style (0), @localType (0), @localTypeDeclarationReference and an option to add attributes from any other namespace*

[kerstarno]

For conversion, the following use cases apply:

1. Elements that use <descriptiveNote> in EAG 2012 and also use it in EAG 3.0 In these cases, the main aspect of the conversion relates to the sub-element <p> and its attributes @xml:lang and @source if used. @xml:lang is replaced with @languageOfElement (the value stays the same). The value of @source is transferred to a new <source><reference> under <control><sources>. The new <source> element gets an @id added and the existing <p> element then uses @sourceReference to point to the new <source>.

I.e.

<descriptiveNote>
  <p xml:lang="[language of p]" source="[source of p]">p</p>
</descriptiveNote>

becomes

<control>
  [...]
  <sources>
    <source id="source1">
      <reference>source of p</reference>
    </source>
  </sources>
  [...]
</control>
[...]
<descriptiveNote>
  <p languageOfElement="[language of p]" source="#source1">p</p>
</descriptiveNote>

2. Elements that use <descriptiveNote> in EAG 2012, but use <p> directly in EAG 3.0 In these cases, e.g. as part of the change from <repositorhist> to <biogHist>, the same happens as in case 1, but the wrapper <descriptiveNote> is removed. See #126 for an encoded example.

3. Elements that use <descriptiveNote> in EAG 2012, but can have text directly in EAG 3.0 In these cases (<building>, <researchServices>, <internetAccess>, <refreshment>, <exhibition>, <toursSessions>, <otherServices>), the text of <descriptiveNote><p> as well as its attributes get transferred to the respective element directly. If <descriptiveNote> in EAG 2012 includes several <p> elements, a new iteration of the respective element will be created for each of these <p> elements.

E.g.

<researchServices>
  <descriptiveNote>
    <p xml:lang="[language of p1]" source="[source of p1]">p1</p>
    <p xml:lang="[language of p2]" source="[source of p2]">p2</p>
  </descriptiveNote>
</researchServices

becomes

<control>
  [...]
  <sources>
    <source id="source1">
      <reference>source of p1</reference>
    </source>
    <source id="source2">
      <reference>source of p2</reference>
    </source>
  </sources>
  [...]
</control>
[...]
<researchServices languageOfElement="[language of p1]" source="#source1">p1</researchServices>
<researchServices languageOfElement="[language of p2]" source="#source2">p2</researchServices>

It might be useful to consider including a comment into the converted file to suggest combining the content of two elements like these in case they were meant to belong to one entry initially (with repeated <p>-s mainly being used for formatting a longer text) rather than describing two different instances of, in this example here, research services.

4. Elements where <descriptiveNote> is removed in EAG 3.0 without an encoding alternative In these cases (<repository>, <computerPlaces>), the conversion would comment the <descriptiveNote> out and add a note that the text, if intended to be kept, needs to be moved into an appropriate alternative element by hand. For <computerPlaces>, the suggestion could be made to move it to the grandparent element <searchroom>, for which <descriptiveNote> is now available.