5.1 Text Stream Position
The TextStreamPosition specifier describes an inter-character position in a text stream by recording the
number of characters that precede the position.
The property value is used to record this character count.
A value of 0 would describe the position immediately before the first character, a value of 1 would describe the position immediately after the first character and before the second character (i.e., the position between the first two characters of the stream), and so on.
For example, if the text stream was “abcdefghijklmnopqrstuvwxyz” and the value was 7, then the position referenced would be the position between "g" and "h". If n is the length of the text stream, then a value equal to n denotes the position immediately following the last character in the text stream.
In some situations, it is important to preserve which side of a position a location reference points to.
For example, when resolving a text stream position in a dynamically paginated environment, it could make a difference if a position is attached to the content before or after the location being referenced (e.g., to determine whether to display the verso or recto side at a page break).
In a TextStreamPosition object, the bias property MAY be used to attach a position reference to the character preceding the position identified by the value property ("bias": "before") or to the character following the position ("bias": "after").
For example, if the text stream was “abcdefghijklmnopqrstuvwxyz”, the value was 7, and the bias was before, then the position referenced would be the position between "g" and "h" and would be attached to "g".
Note
The property bias is only meaningful when some type of break (e.g., a page break or line break) falls or might fall at the position specified by the TextStreamPosition specifier.
Example Use Case: George notices that a letter is missing between characters 322 and 323 in the text of an HTML file he is reading and decides he wants to mark the position of the missing letter by generating a TextStreamPosition specifier so that the letter can be inserted later during editing.
He also wants to ensure that if a hyphen and line break should be dynamically inserted in this position the missing character would follow the break, and so he uses the bias property to associate the position reference with the character that follows the position being referenced (i.e., character 323).
Editor's note
Is this a valid example as regards bias?
Or is this kind of situation better handled by an application rather than conflating a side-bias property with the position reference.
If not compelling enough, we need a better more concrete, real-world use case for side-bias!
Otherwise we should drop side-bias.
Issue 9: Use cases for Position (not satisfied by Selector) - are there any? From Section 3.1.4 (Character Offset) of EPub 3.1 CFI:
"For XML character data, the offset is zero-based and always refers to a position between characters, so 0 means before the first character and a number equal to the total UTF-16 length means after the last character. A character offset value greater than the UTF-16 length of the available text must not be specified."
And from Section 3.1.9 (Side-Bias) of EPub 3.1 CFI:
"In some situations, it is important to preserve which side of a location a reference points to. For example, when resolving a location in a dynamically paginated environment, it would make a difference if a location is attached to the content before or after it (e.g., to determine whether to display the verso or recto side at a page break)."
Assuming these are real feature requirements, I don't think we have anything precisely equivalent in Web Anno data model. Putting aside for a moment whether something called a fragment identifier can be used to specify a location, how might we be able to address a need for these functionalities?
Regarding the first bit, I do note that in Web Anno we do not specify a meaning for a TextPositionSelector or DataPositionSelector having the same value for both start and end. We do talk about "Position 0 would be immediately before the first character[/byte]". So in this doc could we specify an interpretation that if the document was "abcdefghijklmnopqrstuvwxyz", the start was 4, and the end was 4, we are specifying the location immediately before the character 'e'? For completeness should we specify what to do if end (or start) is greater than the length of the normalized text?
Regarding the second bit, side-bias, I have no idea other than to suggest that this is not something a locator or fragment identifier should have to worry about - it's something the consumer of the locator should be responsible for.
Issue 29: Use cases for side bias - are there any? From Section 3.1.9 (Side-Bias) of EPub 3.1 CFI:
"In some situations, it is important to preserve which side of a location a reference points to. For example, when resolving a location in a dynamically paginated environment, it would make a difference if a location is attached to the content before or after it (e.g., to determine whether to display the verso or recto side at a page break)."
No one has come forward with a use case justifying this feature. If no use case is available in a timely fashion (before the end of November 2017), the feature will be removed from FPWD. Can always be added back if a use case subsequently emerges.
This issue was split off from issue #9.
Model
| Term | Type | Description |
|---|
| type |
Relationship |
The class of the Position specifier.
A Text Stream Position specifier MUST have exactly 1 type and the value MUST be
TextStreamPosition. |
| value |
Property |
The count of characters in the text stream preceding the Locus (of interest).
Each TextStreamPosition MUST have exactly 1 value property, and it MUST be a non-negative integer
less than or equal to the number of characters in the text stream. |
| bias |
Property |
This property is used to associate a position reference with either the character that
preceeds it or follows it.
Each TextPositionSelector MAY include 0 or 1 bias properties, and the value
of bias MUST be either before or after. |
The text MUST be selected and normalized in the same way as for the Text Quote Selector before counting the number of characters to determine the value to be used.
Example
Example 13: TextStreamPosition
{
"scope": "https://dauwhe.github.io/html-first/MobyDick.wpub",
"source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
"position": {
"type": "TextStreamPosition",
"value": 322,
"bias": "after"
}
}5.2 Data Stream Position
Similar to the TextStreamPosition specifier, the DataStreamPosition specifier describes a position between two bytes in a byte stream representation of a resource by recording the number of bytes that precede the position.
The property value is used to record this byte count.
A value of 0 would describe the position immediately before the first byte, a value 1 would describe the position immediately after the first byte and before the second byte (i.e., the position between the first two bytes of the stream), and so on.
If n is the length of the byte stream, then a value equal to n denotes the position immediately following the last byte in the stream.
Example Use Case: Paul's data processing application fails after processing the first 401 bytes of a resource's byte stream representation.
Before exiting, the application generates a DataStreamPosition object to record the position where processing was interrupted.
This will facilitate resumption of processing after the processing bug is resolved.
Model
| Term | Type | Description |
|---|
| type |
Relationship |
The class of the Position specifier.
A Data Stream Position specifier MUST have exactly 1 type and the value MUST be
DataStreamPosition. |
| value |
Property |
The count of bytes in the byte stream preceding the Locus (of interest).
Each DataStreamPosition MUST have exactly 1 value property, and it MUST be a non-negative integer
less than or equal to the number of bytes in the stream. |
Example
Example 14: DataStreamPosition
{
"source": "https://example.org/MyData.json",
"position": {
"type": "DataStreamPosition",
"value": 401
}
}5.3 Using Position to Refine
Unlike Selector and State specifiers, a Position specifier can not be refined (since it identifies a point in a stream rather than a part of a resource or a representation of a resource).
However, it may be easier, more reliable, more accurate, or less brittle to resolve a Position specifier in the context of a part of a resource defined by a Selector and/or a representation of a resource described by a State.
Thus a Position specifier may be used to refine a Selector or State (including refined Selectors or States), as long as the Position specifier is the final refinement step processed.
Example Use Case: Deren is one of several people who are collaboratively editing an HTML file.
He needs to generate a TextStreamPosition specifier identifying a position where the word "Mister" needs to be inserted in one of the paragraphs he alone has been assigned to edit.
He doesn't want to specify a text character count within the text stream representation of the entire HTML file, since he knows other edits are in progress that could affect that character count.
So instead he uses a CssSelector to select the paragraph of interest and then refines this selection with a TextStreamPosition specifier to reference the position within the paragraph where the insertion is needed.
Example
Example 15: Refinement by Position Specifier
{
"scope": "https://dauwhe.github.io/html-first/MobyDick.wpub",
"source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
"selector": {
"type": "CssSelector",
"value": "p:nth-child(2)",
"refinedBy": {
"type": "TextStreamPosition",
"value": 8
}
}
}