Marking up “issues” in a HTMLBook document
Closed this issue · 6 comments
Background: When running a book manuscript through Bookalope, it checks for a multitude of issues (e.g. spelling, punctuation, typographical problems, …) and marks them up internally. The user may view these issues through the web interface.
After a lengthy conversation with @Biladew, it seems useful for Bookalope to mark up these issues in the exported HTMLBook document as well.
Proposal: Introduce a way to mark up content issues in some way in HTMLBook:
- To maintain compatibility with HTML, introduce a new data type for spans, e.g.
<span data-type="issue">. This would also require an additional attribute, e.g.issue-type="…". - Introduce a new tag element, e.g.
<issue data-type="…">.
To classify the issue itself, the former approach would require a second attribute issue-type, whereas the latter approach would use the existing data-type attribute for that.
No inner markup should be allowed inside of an issue element, only text.
Overlapping issues can not be marked up in this manner. Overlapping could be handled by Canonical Fragment Identifiers but that may be beyond the scope of HTMLBook.
During further processing of the HTMLBook document, such issue markup can then be either ignored or stripped out completely.
Why do you want to create a valid HTMLBook that has issues? It is kind-of elegant to invalidate elements by adding an issue type to it.
@GitBruno These are not issues with the structure of the document, if I understand correctly, but with the content. If this is the case it doesn't make sense to fail validation since it is a structurally valid book.
@jenstroeger I would rather go with <div data-type="issue">content</div> as it is a semantically neutral way to present the issue to the reader. Perhaps attaching an ID to the issue would allow you to cross-reference related instances.
My concern is that, If you create an issue element, the first thinking is that this is used to mark Github issues or some sort of bug tracking system and not the lightweight internal content reporting issue that you want.
In that case it rather sounds like a comment:
The good news is that the class attribute is free to be used for whatever user-defined semantics and there are no restrictions on values. So you can add a class called issue to the comment:
<p>This is a paragraph of text <span data-type="comment" class="issue">Full stop missing</span></p>
@jenstroeger Are you able to close this issue now?
@GitBruno, I think your proposal is a good suggestion, so yes, closing this issue. Thank you!