Stream: IG creation
Topic: Including non-XHTML pages
Chris Moesel (Mar 22 2018 at 16:44):
We have a tool that generates javadoc-style documentation for our logical models. We'd like to include that documentation in our published IG. I've put it in a subfolder of pages and linked to it from the navbar.html.
It all works well, but when the IG publisher validates all HTML in the IG, it reports errors on our custom documentation because it is not XHTML (it is HTML 5). Is there any way around this? We don't plan to change our other tool to produce XHTML.
Chris Moesel (Mar 22 2018 at 16:44):
... 3048 html files, 134 pages invalid xhtml (4%) (00:05:44.0125sec)
Lloyd McKenzie (Mar 22 2018 at 20:50):
The reason for requiring XHTML is we can look for links and check that they're valid.
Chris Moesel (Mar 22 2018 at 21:10):
Is it possible to demote this error to a warning (via config or something)? Checking for valid links is a good practice, but I'm not sure an error is warranted just because the tool doesn't know how to link-check HTML 5 pages.
Grahame Grieve (Mar 22 2018 at 21:11):
checking for security issues - which we also do - is not optional
Grahame Grieve (Mar 22 2018 at 21:12):
I will not support non-valid xhtml on the auto-publisher, nor on the HL7 website
Chris Moesel (Mar 22 2018 at 21:31):
@Grahame Grieve To clarify, it isn't non-valid XHTML. It isn't XHTML at all. It is HTML 5 (which is a sort of successor to XHTML, since XHTML is mainly based on HTML 4). We cannot use HTML 5 elements and be XHTML 1.0 compliant at the same time. We wanted this reference model browser to be part of the ballot, but we've been told all ballot materials must be on an HL7 server -- so I think we're in a bit of a conundrum. Is there a solution with which you'd be comfortable?
Grahame Grieve (Mar 22 2018 at 21:34):
so it doesn't actually have to be xhtml, it has to be well structured html 5
Chris Moesel (Mar 22 2018 at 21:36):
OK. So if the HTML5 is valid XML, it will be ok, even if it doesn't declare xmlns="http://www.w3.org/1999/xhtml"?
Grahame Grieve (Mar 22 2018 at 21:36):
yes
Grahame Grieve (Mar 22 2018 at 21:36):
in fact, it doesn't have to be valid xml in the strictest sense, since the parser will accept html entities as well as xml entities. It just has to be well strutured html
Chris Moesel (Mar 22 2018 at 21:37):
Alright, I'll circle back with the guys who generate our reference model browser to see what they can do. Thanks for the clarification.
Grahame Grieve (Mar 22 2018 at 21:37):
np
Grahame Grieve (Mar 22 2018 at 21:38):
and I don't even enforce html 5 rules about what elements can be in short hand, though I've thought about it.
Chris Moesel (Mar 22 2018 at 21:40):
OK. By well-structured do you mean that every opening tag must have a closing tag (or be self-closing)? E.g., <br> is bad, <br/> is good?
Grahame Grieve (Mar 22 2018 at 21:41):
I accept either <br></br> or <br/> (depends on the name of the tag which is valid by html5, but I don't care). I don't accept just <br>
Chris Moesel (Mar 22 2018 at 21:44):
Got it. Thanks.
Grahame Grieve (Mar 22 2018 at 21:48):
if they're reworking... I don't know how you produce that stuff, but using jekyll templating would seem like a good idea for that too
Grahame Grieve (Mar 22 2018 at 21:49):
then you can make it part of the IG more directly
Chris Moesel (Mar 22 2018 at 21:53):
It's a completely different stack... All of our stuff is generated from CIMPL (our DSL) text files -- the reference model browser (the topic of this conversation), FHIR logical models, FHIR profiles, ES6 classes, etc.
Grahame Grieve (Mar 22 2018 at 21:56):
i figured. But if you add a mode where you can generate without a page wrapper - just the html itself - then you can use jekyll to template the files and have a better presented IG. The old Quick IG had this whole crappy other representation that wasn't part of the IG and you couldn't navigate around seamlessly - I got several comments about how bad that was
Chris Moesel (Mar 22 2018 at 21:57):
Ah, OK. I follow. Yeah, we can consider that. Not sure if we can get to it by April 1 though. If it was the only thing we had to do it would be a piece of cake, but we've still got quite a list. ;-)
Last updated: Apr 12 2022 at 19:14 UTC
