Support web annotations

[ronaldtse]

Currently annotations are all placed at the bottom. There are some Annotation JS libraries that allow displaying these annotations at the right locations.

@pierrefortier would you be able to help with this?

[pierrefortier]

Hi @ronaldtse, could you be more specific/give me an example of this feature? I see the tag for the foreword annotation in the html. How would it be displayed/styled/placed? Would it be on hover or static? Thanks!

[ronaldtse]

Word and Google Docs, for example, allows placing comments next to the content, displayed as a side note. W3C has a web annotation specification but it is not currently supported by browsers.

However, this JS code: https://github.com/predict-r/annotation-model is implemented according to the W3C specification, and I think we can use it to perform what we need.

[ronaldtse]

We probably should have a "show all / show simple / hide all" annotation toggle just like Word?

[pierrefortier]

Ok great, thanks for the clarification. :)

I'll take a crack at this soon!

[pierrefortier]

@ronaldtse,

After a lot of testing I've added a plugin for annotating the page. It's from https://github.com/openannotation/annotator

Please let me know what you think. I haven't styled it or anything yet, I just wanted the basic functionality going first.

[ronaldtse]

@pierrefortier thanks now I can see the annotation plugin working (when I highlight it shows the annotator), but could we enable the existing annotations?

The document contains two existing annotations under mso-element:comment-list:

A Foreword shall appear in each document. The generic text is shown here. It does not contain requirements, recommendations or permissions.

and

For further information on the Foreword, see ISO/IEC Directives, Part 2, 2016, Clause 12.

I gather however that there is no locality information there for these comments -- @opoudjis could you help here? Thanks!

[opoudjis]

I never saw this.

They are not two annotations, they are two paragraphs in the one annotation; <div style="mso-element:comment" id="1"> contains a distinct annotation.

This is raw Word HTML, so there is indeed no distinct locality information; whatever is done in the pure HTML will presumably add more information to work from. This comment is identified in the div as id=1, and its corresponding comment span in the text is <span style="MsoCommentReference" target="1" class="commentLink" from="foreword" to="foreword">: the target attribute corresponds to the id attribute.

[opoudjis]

I don't think this is what we want at all.

We don't want a tool to allow users to annotate the HTML page generated from Asciidoctor, because we don't actually want them to enter annotations on the HTML. The annotations are meant to originate and persist in the Asciidoctor text input.

We only want something that gets divs with style as (currently) "mso-element:comment", and converts them into annotations. <span style="MsoCommentReference" target="1" class="commentLink" from="foreword" to="foreword"> identifies that the text with @id=1 is the annotation for the span ranging from @id=foreword to @id= foreword.

So we don't want to write annotations. These are read-only annotations, to be extracted out of the HTML.

[opoudjis]

@pierrefortier Instantiating the existing annotations in the document as calls to Annotator would work (though I'd rather you do that than me :-) --- but Annotator looks like overkill for this requirement.

Could you come up with something, instantiating some sort of annotation?

[ronaldtse]

@opoudjis it is not only the reading of annotation, but also the "writing of it". Currently when we distribute Metanorma documents (in HTML or PDF form), there is no method of allowing them to suggest changes (comments, direct edits).

We need to:

1. Allow annotation comments (better yet, suggest edits)
2. Allow serialization / export of those annotations
3. Apply exchanged annotations back to Metanorma Asciidoc...

[opoudjis]

This means mapping html back to asciidoctor-iso, and hoping that the users have not mangled the source irretrievably. In fact, you would only want to map the annotations back, not the html itself.

[ronaldtse]

Exactly, we could do some specific tagging in the HTML so that we can retrieve the annotations via the annotation JS that can be applied back to the source.

[opoudjis]

This means that we retain the annotator JS functionality. I'm not happy about it, given how huge the code is.

The task breaks down as follows, and these are really separate tickets:

• Change the encoding of annotations in the HTML to something HTML-friendlier
• Render existing annotations in the HTML into annotator
• Write a script that exports newly added annotations in the HTML into text (or JSON or XML)
• Write functionality to add those annotations back into Asciidoctor source.

We can assume that no new anchors will be added to the source; the alternative is a nightmare. That may mean that any added annotations will need to snap-to the existing anchors.

[ronaldtse]

Just for the record. We could potentially do Isodoc -> Word -> Apply annotations -> Isodoc annotations but this is just too tough. We'd rather do Isodoc -> HTML -> Apply annotations -> Isodoc annotations.

[opoudjis]

This task has been unactioned for a year, and it needs to come back. @pierrefortier or @strogonoff , it needs JS chops, and it preferably needs a JS library that doesn't take up lots of MB. @ronaldtse , please manage allocation. In addition, do not ask for write-back to Metanorma, that is a much bigger ask (and in my opinion not feasible), and it should not be holding up implementation of this.

[ronaldtse]

@opoudjis I talked to @strogonoff he will be looking at this.

[ronaldtse]

@opoudjis let’s remove the annotations from HTML until we have a solid annotation solution. Right now they just break the HTML. Thanks.

[strogonoff]

We discussed with Ronald and I’d take a look unless someone else is eager. Once I’m a bit free from ITU stuff

…

On 7 Aug 2019, at 7:28 AM, Nick Nicholas ***@***.***> wrote: This task has been unactioned for a year, and it needs to come back. @pierrefortier or @strogonoff , it needs JS chops, and it preferably needs a JS library that doesn't take up lots of MB. @ronaldtse , please manage allocation. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[opoudjis]

Unactioned for two years. I am transferring this to somewhere visible (isodoc) and unassigning myself.