Semantic Mark-up

The following elements contribute to support for semantic mark-up in narrative text. A number of these are used for marking-up transcribed information (e.g. a reference to a person), and these are mirrored in the support for Properties and the Source entity. A number also support the generation of marked-up references in new works created by the author, including narrative essays and narrative reports. The difference being that they generate a marked-up reference as opposed to marking-up a prior reference.

PERSON_REF=

<PersonRef [Key=’key’ | DetKey=’key’] [Mode=’mode’]>

name-orig-text

[ TEXT_SEG ] ...

</PersonRef>

If the name text is provided then this marks-up that text as a person reference. This may be a personal name but not always (e.g. “My grandfather”). If the Key attribute is also specified then it links that person reference to an actual conclusion Person (or Contact) entity. If a DetKey is specified them it allows the reference to be analysed in a Source entity. The Mode attribute is ignored in these instances.

If the name text is not provided then this element generates a reference to the Person entity identified by the mandatory Key attribute. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/person-name-mode and http://stemma.parallaxview.co/name-mode namespaces:

Fall-back sequence: Listing, {Formal, SemiFormal, Informal}, Title, Key — curly brackets indicating a circular choice.

ANIMAL_REF=

<AnimalRef [Key=’key’ | DetKey=’key’] [Mode=’mode’]>

name-orig-text

[ TEXT_SEG ] ...

</AnimalRef>

If the name text is provided then this marks-up that text as an animal reference. This may be a name but not always (e.g. “My dog”). If the Key attribute is also specified then it links that animal reference to an actual conclusion Animal entity. If a DetKey is specified them it allows the reference to be analysed in a Source entity. The Mode attribute is ignored in these instances.

If the name text is not provided then this element generates a reference to the Animal entity identified by the mandatory Key attribute. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/animal-name-mode and http://stemma.parallaxview.co/name-mode namespaces:

Fall-back sequence: Listing, {Formal, SemiFormal, Informal}, Title, Key.

PLACE_REF=

<PlaceRef [Key=’key’ | DetKey=’key’] [Mode=’mode’]>

place-orig-text

[ TEXT_SEG ] ...

</PlaceRef>

If the place text is provided then this marks-up that text as a place reference. If the Key attribute is also specified then it links that place reference to an actual conclusion Place entity. If a DetKey is specified them it allows the reference to be analysed in a Source entity. The Mode attribute is ignored in these instances.

If the place text is not provided then this element generates a reference to the Place entity identified by the mandatory Key attribute. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/place-name-mode and http://stemma.parallaxview.co/name-mode namespaces:

Fall-back sequence: Hierarchical, Listing, {Formal, SemiFormal, Informal}, Title, Key.

GROUP_REF=

<GroupRef [Key=’key’ | DetKey=’key’] [Mode=’mode’]>

group-orig-text

[ TEXT_SEG ] ...

</GroupRef>

If the group text is provided then this marks-up that text as a group reference. If the Key attribute is also specified then it links that group reference to an actual conclusion Group entity. If a DetKey is specified them it allows the reference to be analysed in a Source entity. The Mode attribute is ignored in these instances.

If the group text is not provided then this element generates a reference to the Group entity identified by the mandatory Key attribute. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/group-name-mode and http://stemma.parallaxview.co/name-mode namespaces:

Fall-back sequence: Listing, {Formal, SemiFormal, Informal}, Title, Key.

EVENT_REF=

<EventRef [Key=’key’ | DetKey=’key’] [Mode=’mode’]>

event-orig-text

[ TEXT_SEG ] ...

</EventRef>

If the event text is provided then this marks-up that text as an event reference. If the Key attribute is also specified then it links that event reference to an actual conclusion Event entity. If a DetKey is specified them it allows the reference to be analysed in a Source entity. The Mode attribute is ignored in these instances.

If the event text is not provided then this element generates a reference to the Event entity identified by the mandatory Key attribute. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/event-mode namespace:

Fall-back sequence: Title, Key.

RESOURCE_REF=

<ResourceRef Key=’key’  [Mode=’mode’] [Align=’L|R|C’]>

[ PARAM_VALUE  ] ...

[ TEXT_SEG ] ...

</ResourceRef>

Generates a reference to the Resource identified by the specified Key and Parameters. Default alignment is L (left). Any enclosed Class=’Caption’ text segments are used as an image caption, or if none then any similar segments in the Resource entity itself. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/resource-mode namespace:

Fall-back sequence: {Large, Medium, Small}, Title, Key.

CITATION_REF=

<CitationRef Key=’key’ [Mode=’mode’]>

[ PARAM_VALUE ] ...

[ PARENT_CITATION_LNK ]

[ TEXT_SEG ] ...

</CitationRef>

Generates a reference to the Citation identified by the specified Key and Parameters. The Mode attribute controls the generated reference using the following controlled vocabulary from the http://stemma.parallaxview.co/citation-mode namespace.

Pre-formed (preferred) citation strings may be defined by enclosed Class=’Footnote | Endnote | Tablenote’ text segments, as appropriate. When a citation string is generated from the accumulated parameters, a shortened form may be used if this is a subsequent reference (in the same Narrative element) to the same source, and with the same values for Parameters having WhereIn=’0’.

If no hand-crafted form is provided then the corresponding <DisplayFormat> for the Citation entity (and any chain parents) is used. Otherwise, an external citation-template system is assumed to be available.

The actual style of the reference (e.g. EE, or CMOS) should be a configurable option of the viewing software.

This selection of citation modes is designed to provide features from which various citation forms can be constructed; both traditional ones and ones more applicable to interactive displays. They are not presented as a stylistic gallery.

NOTE_REF=

<NoteRef  [Mode=’mode’]>

[ orig-text ]

[ TEXT_SEG ] ...

</NoteRef>

Creates a general note or annotation for a specific piece of text. The note text is formed from the collected <Text> elements.

If no original text is embraced then a live link cannot be supported and that mode is converted to a footnote reference instead.

Again, the output is controlled by the Mode parameter. The following values are part of the controlled vocabulary associated with the http://stemma.parallaxview.co/note-mode namespace.

ANOM_REF=

<Anom [Mode=’mode’] [Posn=’posn’] [Ref=’ref-mode’] [Dur=’[[hh:]mm:]ss’] [Descr=’description’]>

narrative-text

[ TEXT_SEG ] ...

</Anom>

Represents a transcription anomaly at the current position. For Marginalia, Interlinear, and Intralinear, the narrative-text represents the equivalent <Text> value to place outside the main body of text. For Noise and Gesture, narrative-text is the spanned text, and ‘Descr’ must describe the associated anomaly. No prescribed taxonomy is provided since the identification, interpretation, and description may be subjective. Any other collected <Text> contributions are deemed to be explanatory text.

Again, the output is controlled by the Mode parameter. The following values are part of the controlled vocabulary associated with the http://stemma.parallaxview.co/anomaly-mode namespace.

ALT_REF=

<Alt [Value=’alt-value’]  [Mode=’note-mode’] [Sic=’read-as’]>

orig-text

[ TEXT_SEG ] ...

</Alt>

Marks a reference with an alternative spelling, wording, or meaning. If the Value attribute is specified then it provides an alternative piece of text. At least one of the Value attribute, explanatory text, or the Sic attribute must be specified. The note-mode is identical to that documented for the NoteRef mark-up.

When an explanation is ‘Inline’ then it may explicitly include the Latin word sic (“thus”). However, in other cases, it may still be preferred to have sic follow inline, possibly with the alternative. The attribute Sic=’’ will generate the suffix “[sic]”, while Sic=’, read: ’ (or other separating text) would generate “[sic, read: alternative]”. For instance:

<Alt Sic=’’>jurney</Alt>

generates “jurney [sic]”

<Alt Value=’journey’ Mode=’Inline’>jurney</Alt>

generates “jurney [journey]”

<Alt Value=‘journey’ Sic=’, should be: ‘  Mode=’Inline’>jurney</Alt>

generates “jurney [sic, should be: journey]”

LINK_REF=

<Link URL=’url’>

hyperlink-narrative-text

[ TEXT_SEG ] ...

</Link>

Inserts a reference to an external location via a hyperlink. Embraced text is highlighted in the configured way which will usually be underlined and coloured blue. If the element embraces a ResourceRef then it allows an image to be hyperlinked.

DATE_REF=

<DateRef  [DetKey=’key’] [Value=’std-date’] [Mode=’mode’]>

date-orig-text

[ DATE_ENTITY ]

[ TEXT_SEG ] ...

</DateRef>

If the original date text is provided then this marks-up that text as a date reference. If the DATE_ENTITY sub-structure or the Value attribute is also specified then it links that date reference to an actual conclusion date. The Mode attribute is ignored in this instance. If a DetKey is specified then it allows the reference to be analysed in a Source entity.

If the date text is not provided then this element generates a formatted reference to the date defined by the DATE_ENTITY sub-structure or the Value attribute.  The Mode attribute controls the formatting and must take one of the values: Short, Medium (default), Long, or Full. These values are part of the controlled vocabulary associated with the http://stemma.parallaxview.co/date-mode namespace.

The DATE_ENTITY and the Value attribute are mutually exclusive. The formatting associated with these Mode values should be a configurable property of the software manipulating the data, and should honour the regional settings of the end-user. The interpretation of these values is well-established for the Gregorian calendar. For other calendars, the support of a Date Authority may be required.

<Subs> narrative-text </Subs>

Allows the substitution of parameter values using their normal ${name} syntax. By default, this substitution syntax is not recognised in <Text> elements.

<Mark DetKey=’key’> narrative-text </Mark>

Marks the embraced text as accessible via the given detail-key within a Source entity. This allows it to be discussed, analysed, and built into a stepwise proof argument.

<MarkRef DetLnk=’key’/>

Reproduces a copy of the identified text that was previously marked with a <Mark> element. The choice of quotation style (inline or separate paragraph) is controlled outside of the element. For instance:

<p>The report stated that “<MarkRef DetLnk=’dsKey’/>”.</p>

or

<p>The report stated that:</p>

<p indent=’1’><MarkRef DetLnk=’dsKey’/></p>

Intrinsic Methods

A number of intrinsic methods may be used in the Value and Key attributes of the semantic mark-up elements, depending on the contextual validity. These will eventually be incorporated in the specification for a run-time object model that can interrogate and manipulate STEMMA data programmatically.

Each entity has a static constructor that takes the associated key as an argument. All entity objects have a default implicit Key() method that returns the entity key.

The following Event methods are defined:

std-date = Event (event-key).Start()

std-date = Event (event-key).End()

place-object = Event (event-key).Place()

Hence, Event(key).Place() can be used where the Key value of a Place entity is required.

Methods of the following general form are available for all subject-entities (for Person, Animal, Place, and Group), and Contact, are defined:

person-name = Person(person-key).Name(name-mode)

The name-mode term must be from the http://stemma.parallaxview.co/name-mode namespace.

Use of these methods retains the context of their arguments in order to support drill-down operations. For instance,

<PersonRef Key=’pJohnSmith’/> was born at <PlaceRef Key=’w12BackRoad’/> on <DateRef Mode=’Long’ Value=’Event(eBirthJohnSmith).Start()’/>.

This might generate the following output:

John B. Smith was born at 12 Back Road, Smartville on 21 February 1920.

When clicking on such a derived date or place then the software should remember which Event they were derived from.