Stream: IG creation
Topic: Simplifier use of IG Publisher
Lloyd McKenzie (Sep 20 2019 at 13:20):
I was doing some more thinking last night about how Simplifier might support "exporting" to IG Publisher, and also the ramifications of not doing so.
Grahame indicated that the markdown flavor use by Simplifier differs from that used by the IGPublisher and that converting would be hard. However, we don't actually need to convert between markdown flavors. Converting from markdown to XHTML would be sufficient to publish using the IG Publisher. So long as the intention is that the source will continue to be maintained within Simplifier, spitting out the more technical XHTML just for publishing should theoretically be ok.
Also, even if I'm wrong about predicting ongoing significant change to HL7's rendering approach, each of the "accelerator" projects is going to want their own template. IHE will certainly have their own. Other organizations will also likely have their own. And it would be nice if all of them could use Simplifier for authoring. I don't think it's going to be super-feasible for Simplifier to keep up with the rendering preferences of all of those groups though.
Lloyd McKenzie (Sep 20 2019 at 13:21):
@Grahame Grieve @Ewout Kramer
Grahame Grieve (Sep 20 2019 at 13:41):
Converting from markdown to XHTML would be sufficient to publish using the IG Publisher.
That's the process we're working on, yes. But it means that you can't switch tool chains. I think that's ok. It does mean that the different tool chains need to meet the requirements, and the requirements need to be documented and governed. that's what we're moving towards
Michel Rutten (Sep 20 2019 at 13:44):
Then it would be useful to maintain a clear separation between IG Markdown representation (for authoring) and HTML representation (for publication).
Grahame Grieve (Sep 20 2019 at 13:45):
indeed. we are doing that. Markdown+some tool process is just a way to get to publication, and that's where we'll exercise governance
Michel Rutten (Sep 20 2019 at 13:47):
Are you planning to perform QA on the (HTML based) publication version?
Grahame Grieve (Sep 20 2019 at 13:50):
yes QA will run on the html version propose for publishing
Michel Rutten (Sep 20 2019 at 14:06):
OK, clear. Is there any (planned) QA on the narratives? Could be tricky to report back detailed issues detected in the HTML which actually need to be fixed in the markdown, e.g. line numbers. Not a showstopper, more about usability.
Grahame Grieve (Sep 20 2019 at 14:08):
qa.html reports html line number, and has a link to the actual element in the page. But yes, it can be very obscure working back from an error in generated html to the source of the problem. but that's the nature of the beast
Michel Rutten (Sep 20 2019 at 14:18):
Maybe Simplifier could verify output after rendering markdown to HTML, immediately report back issues to the user. This would allow user to fix basic formatting w/o having to round trip via IG Publisher QA.
Grahame Grieve (Sep 20 2019 at 14:20):
well, you could certainly do that for sure. or you could integrate the IG publisher in some kind of batch mode to do that inside simplifier. But the rules fall into 3 categories:
- no broken links
- resource validation
- some specific rules about page structure and content (e.g. publish-box)
Grahame Grieve (Sep 20 2019 at 14:21):
(and no references to build.fhir.org unless you are explicitly referencing the current build)
Grahame Grieve (Sep 20 2019 at 14:23):
the third sort of stuff feels like stuff to leave to the IG publisher, and just do the first 2 in simplifier
Michel Rutten (Sep 20 2019 at 14:32):
Sure, that seems feasible.
Grahame Grieve (Sep 20 2019 at 14:33):
btw, I was going to review the snapshot stuff last night, but we didn't have the energy - I will work on it this week (I have to)
Michel Rutten (Sep 20 2019 at 14:36):
No problem, I understand. WGM's can be exhausting, especially if your name is Grahame. :wink: We can look into SnapGen next week, whenever you are ready.
Take it easy and safe travels back home!
Lloyd McKenzie (Sep 20 2019 at 14:38):
I'm not sure that markdown conversion limits means that you can't switch tool chains, just that there's a cost. It means you're either now maintaining XHTML instead of markdown (or need to create/find an engine that can convert XHTML into your particular markdown flavor and perhaps manually tweak the places where conversion was sub-optimal. Not something you'd want to do daily, but certainly easier than, say, going from JSON profiles to spreasheets.
Grahame Grieve (Sep 20 2019 at 14:57):
yes a less cost, but still significant
Eric Haas (Sep 21 2019 at 04:14):
What are the different flavors used ?
Eric Haas (Sep 21 2019 at 04:15):
Ig-pub or rather Jekyll is using kramdown.
Vadim Peretokin (Sep 24 2019 at 10:12):
@Lloyd McKenzie Users are no longer tied to the Simplifier team to style changes - they can modify the header/footer/page html and the css in the Enterprise plan. So it wouldn't be much stress on the Simplifier team to maintain that
Martijn Harthoorn (Sep 24 2019 at 10:52):
Simplifier is CommonMark compliant (and extensible, if needed).
Grahame Grieve (Sep 24 2019 at 12:21):
It’s not the markdown, it’s the liquid templating
Lloyd McKenzie (Sep 24 2019 at 14:47):
@Grahame Grieve so the issue is that in Simplifier you wouldn't embed things like {{site.data.fhir.path}} in your hyperlinks to the core spec?
Ward Weistra (Sep 24 2019 at 16:12):
Simplifier renders (autocompleted and live) tags in the IG like {{tree:project-name/resource-name, snapshot}}:
Simplifier-IG.png
The full list is available via the HELP in the bottom right when editing an IG in your project. (Which is actually an IG itself: https://simplifier.net/guide/simplifierighelp Inception! ;))
Ward Weistra (Sep 24 2019 at 16:15):
We could of course replace those with corresponding IG Publisher snippets when clicking the hypothetical Export to HL7 IG Publisher tool button, where available in both.
Grahame Grieve (Sep 24 2019 at 19:06):
Yep. Different tags and we can’t use tags like that since Jekyll doesn’t work that way
Martijn Harthoorn (Sep 25 2019 at 12:55):
In Simplifier, links to external documentation is generated based on a definition in the project where the resource comes from.
pasted image
Martijn Harthoorn (Sep 25 2019 at 12:55):
like this.
Eric Haas (Sep 25 2019 at 16:15):
My concern is still markdown...
I use a lot of kramdown extensions and you can mix n match html where needed seemlessly (well almost seemlessly)
Martijn Harthoorn (Sep 27 2019 at 08:52):
From what I understand there is a list of requirements of what a ballotable FHIR IG (html output) should look like. For those requirements, the markdown flavour should not matter.
If there is a separate list of requirements of what the input to the IG-build-tool should look like, then that is a concern for other tools that want to work (chain) with that tool.
Grahame Grieve (Sep 27 2019 at 12:48):
for working with the IG publisher, there's a list of requirements for working with the IG publisher. The tool chains won't be interoperable (finding out the gap has been the focus of this thread). None of that relates to publishing requirements
Lloyd McKenzie (Sep 27 2019 at 15:02):
There's the baseline requirements and then there's the question of a consistent look and feel. I think the latter is going to be important and is going to be hard to manage independently.
Ward Weistra (Sep 28 2019 at 11:29):
I understand there are (will be) three types of IGs:
- Balloted IGs, published on hl7.org or fhir.org, adhering to all three sections https://wiki.hl7.org/FHIR_Implementation_Guide_Publishing_Requirements.
- FHIR Community Process IGs, adhering to the Basic (I assume) requirements on https://wiki.hl7.org/FHIR_Implementation_Guide_Publishing_Requirements and the Project Output requirements on https://wiki.hl7.org/FHIR_Community_Process
- Other IGs, which document their data model without desire to adhere to the above regulations.
The third already works well on Simplifier. Regarding the other formulated requirements, I think we could implement each of those to give users a choice in what tools to use, as long as:
- They are no longer a moving target, i.e. the requirements are managed by FHIR-I and have a controlled change process, in which we can be included
- IG Publisher specific wordings are brought back to their underlying functional needs ('the IG must build on the CI build')
- The Product parts of an HL7 IG are either functionally defined or shared as small includable components. We already have support for custom CSS and other formatting options.
- And there are of course requirements in there that the user should check, not the tool (e.g. 'Have a FHIR implementation guide proposal in place')
Of course it can be that not all requirements HL7 has in mind are currently documented (eg. look and feel requirements like: numbering of headings, required pages, required components on certain pages?). If so these could be considered if they really are essential and if so proposed to be added.
Lloyd McKenzie (Sep 28 2019 at 15:34):
There's the base requirements, but there's also an expectation by users for a consistent look and feel. Anyone looking at an Argonaut or Da Vinci IG is going to expect the navigation, rendering, etc. to look and behave the same. That's going to be challenging to keep in sync, particularly given that the look and feel of the HL7 IGs will be updating a fair bit based on feedback now that we have the ability to drive a consistent look & feel. It's not an issue to run the decisions about changes to look & feel through a review process, but I'd still expect it to iterate fairly rapidly, at least for the next year or so.
Ward Weistra (Sep 30 2019 at 09:23):
@Lloyd McKenzie I understand and support your desire for consistent look and feel, it would be great if users using multiple IGs intuitively know where to find something after having used a few. Many of those requirements we should be able to define, separate from the tool used and preferably separate from the specific HTML used, like my examples above:
look and feel requirements like: numbering of headings, required pages, required components on certain pages?
On top of the current requirements like what to include in the header and footer.
And if we add more via a controlled change process, with involvement of and time to implement for the tool providers we should be able to keep that in sync, right?
Lloyd McKenzie (Sep 30 2019 at 15:21):
It's certainly theoretically possible to do that, but it's going to be a fair bit of work, at least when we're in a "frequent iteration" phase.
Ward Weistra (Sep 30 2019 at 15:41):
I'm happy to work with you on that, eg. when the first iteration of the template is brought under change management in a few weeks, to see what consistency requirements we can abstract from that and which parts of the template are not strictly needed for Ballotable and FCP IGs.
Last updated: Apr 12 2022 at 19:14 UTC
