References

Internal References

Any @xml:id within the file can be pointed to with an element <ref> with a @target attribute. Oxygen will not let you enter a double ID, and will pull up a list of @xml:id when you attempt to enter @target or @corresp.


<ref target="#p1"></ref>

Example 1

This example will point to the <msPart xml:id="p1">. You can also use this with content, especially where the text of the link is different from the standard label of the node you want to link to, e.g.


<p>this happens also in <ref target="#q14">the final quire</ref></p>

Example 2

This second method preserves your text and creates a link. However, please note that multiple references will be split into several links, so having something like


<p>this happens also in <ref target="#q14 #q15">the final quires</ref></p>

Example 3

will not return the text in the element, but the values of the targets. You can split that reference like


<p>this happens also in <ref target="#q14 #q15"></ref>, the final quires</p>

Example 4

References to other entities in BM

If you are adding a reference, please simply mark it up using <placeName>, <persName>, etc. If you want to refer to another entity in the project but you don’t want to mark up the entity you can use <ref> with @corresp as follows (see also the summary on ref and corresp). This is intended to be useful especially for pointing directly to a particular part of a manuscript description, e.g. a hand or a quire or a part. This should also be used to refer to specific works.


<ref type="mss" corresp="ESap001">AP-001</ref>
<ref type="work" corresp="LIT4018Mashafa"></ref>

Example 5

In @corresp, don’t start with a # but use it if you are referring to a specific part of the quoted manuscript:


This manuscript is in the same hand as <ref type="hand" corresp="ESap002#h2"></ref>

Example 6

Please specify the @type for each reference. Allowed values are encoded in the schema.

References to text passages

In manuscript and work records, you may use references to parts of a text, like <locus>, also when we do not yet have this text transcription at all. These references are valuable information connecting to a real word artefact. You do not need to have somewhere a <div> or any other element, you are adding a structured string which refers to the actual real-life object, as you would do in any text. However, for these references to be resolvable to a fragment of text (i.e. for you to be able to let the machine retrieve that piece of text you are referring to), this text needs to be present and for all the cases in which a reference can be constructed but there is no text, at least the text's structure must be declared by encoding it. So, if you change the structure of a text edition, translation or transcription which have made up (that is, it cannot have a real word resolution allowing you to go to folio 1 recto column b line 4 of the real object), please make sure that any pointer to that is still valid. For example, you decide to add a <div> in between your <div> with @type edition and a series of previously existing <div>s. You are also now making any reference to this invalid, and you need to fix it.

General Structure of references

ID_(ED|TR)_(@xml:id).1.2.3

This is made of three main parts. The first part (ID) is separated from the second ((ED|TR)_(@xml:id)) by _ . The second part is separated from the third (1.2.3) by .. The first part is also the main ID of the record. The second part is mapped to a parameter "edition", which is implementation-specific. The last part is mapped to Distributed Text Services navigation and document parameters ref, start and end and are resolved in the application (i.e. if you point your browser there, it will return that passage precisely if available) based on our implementation of the specification, which is surfaced in the text view.

You can have the first part of the reference alone, to point to the entire text, or you can have a pointer to an edition (first and second part, e.g. TUid123text_TR_translation) or to a passage without specifying the edition (first and third part, e.g. TUid123text.1.2.3) which will return as many versions as the editions (most of the time, one) or a reference to text, edition and passage with all three parts (e.g. TUid123text_TR_translation.1.2.3).

The following section provides details on each part of these references.

First part (identifier)

ID

This is the ID of the manuscript or textual unit, as normally used. Anchors are inconsistent with the aim of this structured referencing system and alternative to it. The following example is what is discussed here, as a pointer to a specific passage in the text TUid123 at a subdivision named 1 which is child of another subdivision named 1. It could be a verse in a chapter or a chapter in a book.

<ref type="work" corresp="TUid123.1.1"></ref>

Example 7

Please note the difference between this reference, and the more generic reference as discussed above to an anchor (the @xml:id on an element which is unique in that file).

Second part (editions transcriptions and translations)

_(ED|TR)_(@xml:id)

This second, optional part of a reference identifies the translation or edition, with its type, which is ED for edition and TR for translation and finally, after the second underscore the @xml:id of the edition/translation, which is especially important if there are more than one edition or translation. If this section of the reference is not provided, the default is <div[@type='edition']>.

For example, at the time of writing Lǝfāfa ṣǝdǝq has two <div[@type='edition']>, one with and one without @xml:id. LIT1758Lefafa_ED_ can be used for the edition in the <div[@type='edition']> without @xml:id LIT1758Lefafa_ED_editionBudge for the edition in the <div> with an @xml:id.

It is important that there are not two or more <div> of the same type without an @xml:id to distinguish them.

If I want to point to the translation of the Periplus of the Erythraean Sea, even if it had an @xml:id, I can use LIT2170Peripl_TR_.

For these records, if no edition is specified, all available references (i.e. double or triple) will be valid references and will be returned.

Third part (reference)

This part, introduced by a . is a reference to a specific passage or range within the selected text and edition/translation. Each level is separated by a dot. Levels of the citations depend on the encoded text, they are not fixed, each position in the reference is only relevant to that text and how it is encoded and accordingly structured. <div>, <l>, <pb>, <cb> and <lb> are the structuring elements. <div>s can be nested and each nested level will be a citation level. <pb>, <cb> and <lb> are all empty elements whose hierarchy is only dependent on their position, i.e. a column of a page starts at the <cb> which occurs after that <pb>.

The levels in this text reference can be constructed as a series of sub references. Each level is separated by a dot, e.g. 1.1. The value for each level is extracted from

  1. a @n
  2. an @xml:id
  3. a @corresp
  4. a concatenation of @subtype and @n.

The total number of levels cannot be greater than the citation depth, that is the number of nested countable structures. If there is a <div> with <lb>s in it only, I will only have 2 levels, I cannot point to 1.1.1, because the last level of my reference will not match anything.

Support for <pb> for multiple citations structures exists, like in the following example from Periplus of the Erythraean Sea:


                        <pb n="1" corresp="#frisk"></pb>
                        <pb n="51" corresp="#casson"></pb>
                        <pb n="257" corresp="#mueller"></pb>
                        <pb n="9r" corresp="#L"></pb>
                     

Example 8

Each reference can be pointed to and retrieved as 1.1[frisk], 1.51[casson], 1.257[mueller], 1.9r[L] as far as the nodes are there and there is a corresponding bibliography item with @xml:id.

More detailed information and examples are available in the following two pages.

  1. Adding precise references to places in the manuscript transcription
  2. Adding precise references to places in text editions

A note on the way in which the Beta maṣāḥǝft application uses these references, which is entirely application dependent. The structure described above is mapped to parameters, so that your request for https://betamasaheft.eu/LIT1758Lefafa_ED_editionBudge.2 is redirected to https://betamasaheft.eu/works/LIT1758Lefafa/text?edition=_ED_editionBudge&ref=2

External links

You can also use @target to point to external resources. In this case, please enter the full URL, starting with http.

To link to a manuscript in vHMML, please, use the provided permalink in the metadata.


 <ref type="mss" target="https://w3id.org/vhmml/readingRoom/view/133001"></ref>

Example 9

Revisions of this page

  • Pietro Maria Liuzzo on 2018-04-30: first version of guidelines from Wiki
  • Pietro Maria Liuzzo on 2020-06-16: introduced text and example for referencing based on DTS navigation and document support