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:

 

Mode

Operation

Title (default)

The Title of the Person, if any. If the Person has no title defined, or the referenced entity is a Contact, then Mode defaults to SemiFormal.

Informal, SemiFormal, Formal, Listing

The first instance of a canonical name with a corresponding name-mode.

 

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:

 

Mode

Operation

Title (default)

The Title of the Animal, if any. If the Animal has no title defined then Mode defaults to SemiFormal.

Informal, SemiFormal, Formal, Listing

The first instance of a canonical name with a corresponding name-mode.

 

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:

 

Mode

Operation

Title (default)

The Title of the Place, if any. If the Place has no title defined then Mode defaults to SemiFormal.

Informal, SemiFormal, Formal, Listing

The first instance of a canonical name of a corresponding name-mode.

Hierarchical

Generates a Place-hierarchy-path. The ordering (coarse-to-fine or vice versa) and separating characters must be configurable in the software generating the output.

 

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:

 

Mode

Operation

Title (default)

The Title of the Group, if any. If the Group has no title defined then Mode defaults to SemiFormal.

Informal, SemiFormal, Formal, Listing

The first instance of a canonical name of a corresponding name-mode.

 

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:

 

Mode

Operation

Title (default)

The Title of the Event, if any

 

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:

 

Mode

Operation

Title (default)

The Title of the Resource, if any.

Small, Medium, Large

Generates an icon or image of the corresponding logical size, if the output media is capable. The physical size for each is controlled by the software generating the output.

SynchImage

Identifies an image (not displayed) to which transcription entities can be positionally related. See x/y attributes in Descriptive Mark-up.

SynchAudio

Identifies a recording to which transcription entities can be synchronised. See <time> in Descriptive Mark-up.

 

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.

 

Mode

Operation

Footnote (Default)

Endnote

Tablenote

Inserts a reference to a corresponding footnote, endnote, or tablenote using a superscript or bracketed character. On an interactive device, the character may be a live link.

Implied

Associates a Citation entity with the current sentence, but without it contributing to its text. This is useful where a NoteRef may be conflating two source references into a single sentence.

Inline

 

Inline reference, with no trailing punctuation. This mode is particular useful for creating complex citations, or adding a source reference to discursive notes.

Parenthetical

Parenthesised in-text reference, as supported by CMOS.

Title

Generates a reference to the expanded citation-title (if any) or the associated key name.

 

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.

 

Mode

Operation

Link (Default)

 

On an interactive device, this inserts a live link to the respective text. On a non-interactive device, such as printer output, then it generates a normal footnote reference as described below.

Inline

The note text is inserted inline and distinguished from the surrounding text. This usually means employing editorial brackets, [...]

Footnote

Endnote Tablenote

Inserts a reference to a corresponding footnote, endnote, or tablenote using a superscript character or symbol. On an interactive device, the superscript may be a live link.

 

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.

 

Mode

Operation

Footnote

Endnote

Tablenote

A reference to a corresponding footnote, endnote, or tablenote. Ref must identify marker character.

Marginalia

A reference to text added in a margin. Posn=’L|R|T|B’, Ref=’--‘ (line) or empty. Defaults: Post=’R’, Ref=’’.

Interlinear

Text added between lines.

Intralinear (Textual default)

Text added within a line. Posn=’T|B’ (above/below), Ref=’^|--‘ (caret/line). Defaults: Posn=’T’, Ref=’^’.

Noise (Audio default)

Untranscribable noise uttered by individual, e.g. sneeze, cough, sniff, yawn, whistle, laugh, swallow. Described via Descr.

Pause

Significant pause during recording of individual. Dur attribute indicates the number of hours, minutes, and seconds.

Gesture

Non-verbal action by individual, e.g. nod, applause, smile, head-shake, squint, frown. Described via Descr.

 

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.