Re: Style Issue

I've been aware of this thread over the winter break, but I haven't replied yet since I was busy with non-work stuff. I'll try not to duplicate anything else mentioned on the thread. Please forgive me if I do.

Instead of directly going into a lot of pros and cons, I'll outline what we're doing in the Shelley-Godwin Archive (SGA) through shared canvas with respect to style. Whatever we decide on style here will need to carry over to what we're doing with the SGA.

Because we're working with handwritten documents and we don't have bottomless pits of money, we don't have bounding boxes for the transcriptions. This breaks one of the basic principles of shared canvas (everything maps onto the canvas via bounding shapes), but we're working around that by creating a text-oriented zone that works in terms of textual coordinates. *much hand waving...*

We translate each section of the transcription into an annotation with a TextOffsetSelector body mapping the range of text in the TEI to the canvas target (possibly constrained if we know which section of the canvas should receive the text). We then model each of the different pieces of markup in the TEI (currently lines, additions, deletions) as highlight annotations targeting TextOffsetSelector ranges in the TEI.

For example, we might have the following simplified annotations:

_:textAnnotation1 a sc:ContentAnnotation, oa:Annotation ;
  oa:hasBody _:text1 ;
  oa:hasTarget _:spCanvas1 .

_:text1 a oa:SpecificResource ;
  oa:hasSource <teiFile> ;
  oa:hasSelector _:selector1 .

_:selector1 a oax:TextOffsetSelector ;
  oax:begin "..." ;
  oax:end "..." .

_:structuredAnnotation1 a oa:Annotation, oax:Highlight, sga:AdditionAnnotation ;
  oa:hasTarget _:textTarget1 .

_:textTarget1 a oa:SpecificResource ;
  oa:hasSource <teiFile> ;
  oa:hasStyle _:cssStyle ;
  oa:hasSelector _:selector2 .

_:cssStyle a oa:Style, cnt:ContentAsText ;
  cnt:chars "vertical-align: super;"
  dc:format "text/css" .

_:selector2 a oax:TextOffsetSelector ;
  oax:begin "..." ;
  oax:end "..." .

It's easy to process all of this into a set of spans that combine all of the style information from any overlapping annotations. I've put a screenshot of our current (alpha) viewer at http://mith.umd.edu/tmp/sga-shared-canvas-3Jan2013.png to illustrate what overlapping highlights end up looking like. The third line on the page has a deleted addition in the middle of a longer deleted section. The additions are marked as either superscript or subscript based on the CSS style added to the annotation. The strikethrough (barely visible when embedding HTML in SVG in Chrome) and bold/grey come from css classes not part of the OA/Shared Canvas RDF.

I suspect our use of style reflects a much earlier draft of the OAC specification. What would our RDF look like with the options under consideration? What additional code would we have to write to make use of the style information?

If we assume that we only attach class names to the annotation, then we can reduce the _:textTarget1 resource to the following triples (and making up the "oa:styledByClass" and "oa:styledByCSSDocument" predicates):

_:textTarget1 a oa:SpecificResource ;
  oa:hasSource <teiFile> ;
  oa:styledByClass "foo" ;
  oa:styledByCSSDocument <referenceToCSSDocument> ;
  oa:hasSelector _:selector2 .

Of course, we have to record the CSS somewhere that defines what is applied for the class, and we have to provide a CSS parser so that we can extract only the CSS that applies to this annotation based on class. Each annotation could reference a different stylesheet defining their class. This is an extra layer that we can work with, but it adds more code that we will require users download to their browser before they can view our project.

If we simply dump the CSS rules and classes into the HTML as-is, then we risk collisions with application stylesheets. The annotations are independent of the implementation of the client application used to visualize them, so we can't assume that they can share the same stylesheets any more than we can assume that two different annotations will share the same stylesheets.

The OA draft already assumes that we'll have an RDF/XML parser available (which we don't - we're using RDF/JSON so we don't have to load an additional JavaScript library). Do we also need to assume a CSS parser?

-- Jim

On Dec 20, 2012, at 11:15 AM, Robert Sanderson <azaroth42@gmail.com> wrote:

> 
> Dear all,
> 
> While writing up the new method of attaching Styles to Annotations, we ran into the following unanticipated issues.  We feel this makes the current solution for style unworkable, and propose a slight modification that should make things easier all round.
> 
> Issues:
> 
> 1.  Styles reference the resources in the graph by URI, using the CSS @document rule.  While this makes matching easy, it becomes impossible with the republishing method that is recommended in the specification.
> 
> For example, a system publishes an Annotation A with an embedded body URN:B.  URN:B is thus the URI that is in the Style.
> 
> A second system harvests the Annotation, republishes it at A2, and the body as a web resource at HTTP URI B2.  It should also assert that B2 equivalentTo URN:B.  So now the style refers to the equivalent resource, not the body itself and systems will always have to check both.
> This isn't the end, however, as this is likely to happen multiple times in a distributed system.
> The Style could be updated, but it might be a web resource that is maintained outside of the annotation system and these changes would not be reflected in the copies.  It also relies on consuming systems to understand the content of Styles, which seems above and beyond what they should be expected to do.
> 
> 
> 2.  As Styles refer to the URI of the resource, they cannot be re-used across multiple annotations.  This means that there necessarily must be one style per annotation, which is contrary to most uses of CSS and really to the web architecture in general.  So every system that has a style for its annotations must create a new style resource for each annotation, rather than just a default few.
> 
> 
> 3.  Following from 2, there is no reason to *not* embed the style if it is tied 1:1 to the Annotation. This defeats the purpose of some of the changes from the first draft, eg to make it a valid CSS resource rather than just the value block.  It also brings up a (lesser) documentation/learning issue that to understand Styles you need to understand the Content in RDF model, which otherwise is not necessary.
> 
> We consider the sum of these issues to be a show-stopper.
> Our proposal for how to adapt it is:
> 
> 1.  Keep the Style resource a valid CSS document attached to the Annotation, still using oa:styledBy, as in the current proposal.
> 
> 2.  Instead of using the complex @document url() rule construction, instead use the more familiar class name construction.
> 
> 3.  Have a property in the Annotation graph on the resources to be styled that records the class name.   Systems then match the property to the respective name in the CSS document.
> 
> This solves Issue 1 because the property can be reattached easily to the new resource, just like all of the other properties and relationships.  At the same time, we use only basic CSS constructions rather than the CSS Level 3 @document construction.
> 
> It solves Issue 2 because the class names can be re-used across multiple annotations.  I also makes it easier to swap styles across a range of annotations -- simply change the referenced CSS resource and they all change, rather than the current method (edit all of the embedded CSS blobs) or the first version (change the references on all of the Specific Resources).
> 
> It solves Issue 3 by solving Issue 2, as the style is not tied 1:1 with the Annotation.
> 
> Thus:
> _:Anno a oa:Annotation ;
>   oa:styledBy <Style1> ;
>   oa:hasTarget <SpTarget1> ;
>   oa:hasBody <Body1> .
> 
> <SpTarget1> a oa:SpecificResource ;
>   oa:hasSelector <Selector1> ;
>   oa:styleClass "red" ;
>   oa:hasSource <Target1> .
> ...
> 
> Where Style1 has the representation:
> .red { color : red }
> 
> This seems to capture the best parts of the current proposal while solving the issues that have come up with it.
> 
> Please let us know any thoughts or comments on this revised approach.
> 
> Many thanks,
> 
> Rob, Paolo and Herbert
>