Referencing parts of the manuscript

A <locus> element can be used almost everywhere (see content model) to indicate the physical location of a content item or other unit of interest which can be delimited with reference to a defined portion of text. <locus> contains always either two attributes @from and <to> or the attribute @target with one or more references listed which are not a range. Please do not use other numbering systems or spaces within these attributes.

Besides the basic referencing structures (<div>) you may refer to parts of the text of the manuscript using references to <pb>, <cb> and <lb>. Although for these to be resolvable the text needs to be present and encoded, their semantic value with reference to the selected passage remains even when the actual elements (<pb>, <cb> and <lb>) and text are not present and the reference is intended to the material object. This means that references according to the following system can be used in <locus> even when the record does not contain any <pb>, <cb> and <lb>. Below are possible references (the element is followed by an attribute [@ …]):

  1. a folio, e.g. 1 (<div[@type='folio'][@n]>)
  2. a page, e.g. 1r (<pb[@n]>)
  3. a column, e.g. 1va (<pb[@n]>,<cb[@n]>)
  4. a line, e.g. 2.1 (<div[@type='folio'][@n]>,<lb[@n]>). Note that this is the same very generic referencing system of any numbered division declared in the document, it can refer to a line in a folio, but also to a chapter in a book or a day in a month, depending on what is declared in the file.
  5. A line, e.g. 2 (<lb[@n]>), if the folio structure is not present.
  6. A line, eventually in a specific page and column, e.g. 2ra1 (<pb[@n]>,<cb[@n]>, <lb[@n]>)
This assumes consistent numbering.

It is possible to use the same syntax for a reference to a page in one of a more defined paging systems, e.g. based on different editions. e.g. 1[frisk] (<pb[@n][@corresp]>).


            <locus from="1v1" to="2ra6">the text begins on 1v in line 1 and ends on 2ra in line 6
            </locus>
         

Example 1

A list of individual references at page level (without line indication) can be given in @target


            <locus target="#28v #33r #49r #50v #55v #82r #82v #83r #83v #84v #85r"></locus>
         

Example 2

Please DO NOT use unknown as a value for any of these attributes. Simply do not enter the attribute if its value is not known.


            <locus from="20r"></locus>
         

Example 3

NOT <locus from="20r" to="unknown">

A manuscript's existing foliation should not be shifted - it is possible to point to folia not included in the foliation by assigning individual leaf numbers. This will lead to the inability to calculate the foliation, but the semantic will be valid and if encoded the reference may be resolvable.

 Two folios between <locus target="#66"></locus>
            and <locus target="#67"></locus>, <locus target="#66i"></locus> and <locus target="#66ii"></locus>, are so
            badly mutilated that only small corners - each not containing more than fragments of 4
            letters - are preserved which have not been taken into account for the foliation of the
            manuscript. 

Example 4

While <l>, <lb>, <pb> and <cb> all need to have @n, <div>s not always have this attribute and sometimes have @corresp, sometimes @subtype or an @xml:id or a combination of these. For canonical referencing of structures in the text encoded with <div>s, any of the basic values or combinations detailed in referencing can be used.

This simply means, for example, in the Beta maṣāḥǝft web application and related services that the text view when listing available references to passages for EMIP01859, e.g. at the third level of depth, will show 1.1.1 but you can use to refer to that same passage a number or alternative references e.g. EMIP01859.month1.day1.NAR0019SBarkisos, EMIP01859.1.day1.1, etc. BLorient718.1.1 can be used as an alternative to BLorient718.1ra1 or BLorient718.1.1ra1, but note the different semantic flavouring.

In real life daily encoding fun, you need to either use the existing references as offered in the text view or in the DTS Navigation API, or know the structure of the XML to build one option which you like more and is valid according to the guidance offered here. The canonical reference displayed in the text view will be the better one available at the time of loading the page. Here are some more examples of these references:

  1. BLorient718.1 gives the folio 1.
  2. BLorient718.1r gives the recto of folio 1.
  3. BLorient718.1ra gives column a on the recto of folio 1.
  4. BLorient718.1ra1 gives the first line of column a on the recto of folio 1.
  5. BLorient718.1ra1-1ra3 gives line 1 to 3 of column a on the recto of folio 1.
  6. BLorient718.1ra1-2vb6 gives from line 1 of column a on the recto of folio 1 to line 6 of column b on the verso of folio 2. BLorient718.1.1 can be used to point to a line, if this is uniquely identified with @n.
  7. EMIP01859.month1.day1 is also a valid reference and will fetch the element in the manuscript transcription associated with the specified structure of type and names.
  8. EMIP01859.1.1.1 is also a valid reference and will fetch the nested structured marked with n.
  9. EMIP01859.month1.day1.NAR0019SBarkisos is also a valid reference and will fetch the element in the manuscript transcription associated with the specified narrative unit. If you want to fetch passages connected to a narrative unit without specifying the manuscript, add the narrative unit ID instead.
  10. EMIP01859.NAR0019SBarkisos is also a valid reference and will fetch the element in the manuscript transcription associated with the specified narrative unit. If you want to fetch passages connected to a narrative unit without specifying the manuscript, add the narrative unit ID instead.
  11. IVEf921 is a letter only encoded into a <div type="edition">. You can point to a line in it by saying IVEf921.1 but this will not be resolvable. The moment you add a <pb> or a <lb>, this will become resolvable and a request for that part of text will return that part of text.
  12. RIE193 is an inscription with <div>s. you can point to specific ones.

It is not possible to canonically reference a part of text transcribed e.g. in an <incipit> inside <msContents>, but don't panic, you have your @xml:id! Anchors, informally referred to as "sub-IDs" are a perfectly valid, standard way of referring to an element with an @xml:id, but they are not canonical citation of the structure of the text in one of its manifestations. With a canonical reference you are referring to the text in one of its abstractions using a canonical model, which you may have encoded; with an anchor pointing to an @xml:id you are referring to that specific element node in an XML tree.

Inside locus these can be used to refer internally to a piece of text transcription. this use in @from @to and @target follows the usual conventions, i.e. does not need the manuscript ID.


               <locus from="1r" to="2ra" facs="004"></locus>
               <locus from="1ra1" to="34vb4"></locus>
               <locus target="#1ra1 #34vb4"></locus>
               <locus from="1r" to="2ra" corresp="#fol1"></locus>
            

Example 5

You may wish to use your text for a reference


            <locus from="1ra1" to="34vb4">1ra up until the fourth line of column b on the verso of
               folio 34</locus>
            <locus from="1r11" to="1r18">f. 1r lines 11-18</locus>
         

Example 6

If <locus> is not for you, or you do not want to use a folio/page/column/line reference string, for example, because you have an inscription or a scroll or a shred of pottery, you may opt for a simple <ref>, where you use the reference in full according to the structure you have encoded in the file.


               <ref type="mss" corresp="MSid123.section1.column2.text3.4-5"></ref>
            

Example 7

For a formal citation of a passage, you may use a canonical reference in @cRef .

               <ref cRef="betmas:MSid123.section1.column2.text3.4-5"></ref>
            

Example 8

Some manuscripts are paginated instead of being foliated. You will have in such cases most probably to be consistent and provide inside <extent> a <measure unit="page">. This will then alter the behaviour of the visualization and use p. and pp. instead of f. and ff.. However, the values you may enter inside @from, @to or @target are still the foliation references, so, 1v, not 2, 2v, not 4.

The markup in <locus> of a paginated manuscript will look like in the following example


            <locus from="1ra" to="6vb">1-12</locus>
         

Example 9

However, you may use the equivalent markup for a generic reference instead (see also references to text passages).


            <ref corresp="PaginatedMSid123.1-12">1-12</ref>
         

Example 10

This page is referred to in the following pages

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