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.
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.
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
{
"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.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
{
"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
}
}
}