FHIR Chat · Page errors · IG creation

Stream: IG creation

Topic: Page errors

Rick Geimer (Mar 15 2019 at 10:34):

I've got an IG resource with pages like this:

<page>
<nameReference>
<reference value="#6509"/>
<display value="Page content 6509"/>
</nameReference>
<title value="Introduction"/>
<generation value="markdown"/>
</page>

The reference points to a contained Binary resource within the IG resource itself. However, I am seeing the following in the QA file:

Base IG resource error The page "Introduction" is missing a name/source element

Pretty sure this is an IG Publisher error, since the page does have a name[x] element (in this case nameReference) which points to the source. @Grahame Grieve ?

Here is the QA log:

http://build.fhir.org/ig/HL7/davinci-ehrx/qa.html

Grahame Grieve (Mar 15 2019 at 12:14):

I'll have a look

Grahame Grieve (Mar 15 2019 at 22:27):

@Lloyd McKenzie this is actually your code, for generating pages.json. It's not immediately obvious how this should be resolved

Lloyd McKenzie (Mar 15 2019 at 22:48):

If you're using my framework, it's not set up to handle that. It presumes all pages are in a folder. What you'd need to do is change the pre-process transform the manipulates the IG and split the binaries out into files in an appropriate folder and change the IG to have references to them. (I'm not likely to have bandwidth to do it myself between now and Sunday.) (I'm not sure that Eric's framework would be any happier...)

Grahame Grieve (Mar 15 2019 at 22:49):

The IG is not using your framework. So why is it an error?

Eric Haas (Mar 15 2019 at 22:52):

here are how I do STU3 pages ( inspired by Lloyd ):

  <!-- ============ Home Page =============== -->
  <page>
    <source value="index.html"/>
    <title value="Home"/>
    <kind value="page"/>
    <!-- ============ Framework Page =============== -->
    <page>
      <source value="framework.html"/>
      <title value="Framework"/>
      <kind value="page"/>
      <page>
        <source value="guidance.html"/>
        <title value="General Guidance"/>
        <kind value="page"/>
      </page>
      <page>
        <source value="datax.html"/>
        <title value="Data Exchange"/>
        <kind value="page"/>
      </page>
      <page>
        <source value="indv-reporting.html"/>
        <title value="Individual Reporting"/>
        <kind value="page"/>
      </page>
      <page>

...

in R4 would be like

    <!-- ============ Home Page =============== -->
  <page>
<nameUrl value="index.html"/>
<title value="Home"/>
<generation value="markdown"/>

so its a validating against the wrong version of ig.xml

Eric Haas (Mar 15 2019 at 22:52):

and I don't use the nameReference element either

Lloyd McKenzie (Mar 15 2019 at 22:59):

Grahame - how is the HTML page name of a generated page determined if the ImplementationGuide points to it as a contained resource rather than by URL?

Lloyd McKenzie (Mar 15 2019 at 23:00):

I'm wondering if we need something extra in the ImplementationGuide resource to tell us that.

Lloyd McKenzie (Mar 15 2019 at 23:00):

I can change the error to a warning for now, but I don't know what to spit out in the table of contents or in the file used for breadcrumbs.

Eric Haas (Mar 15 2019 at 23:05):

does the page get generated by Jekyll ?

Eric Haas (Mar 15 2019 at 23:09):

you could cycle through all the pages to find it.. and work backwards

{% for p in site.html_pages %}
{{p}}
{% endfor %}

???

I like your first solution better.

Lloyd McKenzie (Mar 15 2019 at 23:13):

Jekyll can't see anything inside the ImplementationGuide instance - it needs all page content (markdown or HTML) to be a "file" in a folder it can manipulate. The framework used for publishing implementation guides would have to take care of doing that. My question is "what should the filename be?". I guess we could use the convention of [Binary.id].[md/html - depending on the page type]. But I'm not super-thrilled with the id and filename needing to be the same. @Rick Geimer, what was your assumption around filenames in the published content here?

Grahame Grieve (Mar 15 2019 at 23:14):

@Rick Geimer I think the challenge is that the IG publisher doesn't handle this approach generally, and so I have 2 questions - what do you think is going to happen generally, and why do it?

Grahame Grieve (Mar 15 2019 at 23:14):

but: this fails the definition of feature complete - we are not making structural changes at this time...

Rick Geimer (Mar 16 2019 at 04:08):

@Lloyd McKenzie I think for now we should make this a warning as you suggested. The pages all render fine and show up in the table of contents, so I'm not sure why this is considered to be an error. @Grahame Grieve as for why we are using this approach, it is because it was actually the most straightforward way for @Sean McIlvenna to add page support in Trifolia on FHIR, since we store everything as FHIR resources in HAPI vs. on a file system, so putting markdown content in contained Binary resources made this very easy, and it's a part of the spec...there was nothing in the spec that hinted that we shouldn't/couldn't use this approach.

Rick Geimer (Mar 16 2019 at 04:13):

Also @Grahame Grieve what do you mean when you say "this fails the definition of feature complete"? When you say "this" do you mean the IG Publisher, or are you saying that all the IGs we created with Trifolia on FHIR that use this approach are not feature complete even though build/render perfectly fine except for those error messages that should probably be warnings ? If the later, why?

Lloyd McKenzie (Mar 16 2019 at 04:18):

@Rick Geimer - where do the filenames for the HTML come from?

Lloyd McKenzie (Mar 16 2019 at 04:32):

And how are you generating using Jekyll if the binaries are in the IG?

Rick Geimer (Mar 16 2019 at 04:36):

@Sean McIlvenna will have to reply with the details, but I believe that he creates the file names from ImplementationGuide.page.title, swapping underscores for spaces, etc. Maybe I wasn't clear on this part, but when we export an IG Publisher package we extract the markdown into separate files in source/pages and then run the Jekyll, so the contained Binary resources are really just used for storage in HAPI.

Rick Geimer (Mar 16 2019 at 04:41):

@Lloyd McKenzie See here for the example of what we export. It is basically using a slightly modified (and probably slightly outdated) version of Eric's framework. We plan to update the tool to support whatever the "official" HL7 framework will be once it is done.

Rick Geimer (Mar 16 2019 at 04:42):

https://github.com/HL7/davinci-ecdx

Lloyd McKenzie (Mar 16 2019 at 04:45):

That doesn't really fly. You've got a file that the publisher is using that the IG doesn't point to and you've got a file that the IG points to that isn't being used. You're putting some of the publication process into the 'extract'. If someone were to edit the content in the ImplementationGuide - which the ImplementationGuide says is where the page lives, then the publication process wouldn't work right. The only way it could work is if they re-edited with your tool. And the content in Git needs to be tool-independent.

Lloyd McKenzie (Mar 16 2019 at 04:47):

Grahame can decide whether to let that slide for this time around, but going forward, either the ImplementationGuide that's exported needs to point to the files, or the ImplementationGuide needs to contain the files and the IGPublisher 'framework' needs to handle the extraction for publication.

Rick Geimer (Mar 16 2019 at 04:56):

@Sean McIlvenna it would be good for you to chime in here. @Grahame Grieve I hope we can let it slide for this round, because all the Da Vinci IGs use this approach. We can certainly look at changing the export so that when we extract the markdown content to files we also change the ImplementationGuide resource to point to those files. I don't think that will be a huge effort, but Sean will have to respond if that's something we can reasonably do in a day.

Rick Geimer (Mar 16 2019 at 04:58):

But if the framework will not support referenced Binary resources we should definitely consider deprecating that in ImplementationGuide, and noting that the use of that feature is not supported in the IG Publisher documentation. Right now everything published implies that it is a valid approach.

Grahame Grieve (Mar 16 2019 at 04:59):

well, if the IG publishes correctly now, then I'll let it go. but raising a structural error like this as a probem in the last week is what the feature complete thing is about - we don't do structural change in the IG publisher in the last few weeks before publication

Grahame Grieve (Mar 16 2019 at 05:00):

so you'll have to live with the errors/issues for now

Rick Geimer (Mar 16 2019 at 05:01):

Ok, thanks Grahame, and we'll see what Sean says, we might be able to patch the ImplementationGuide export to make this issue go away now that we understand what the issue is.

Rick Geimer (Mar 16 2019 at 05:47):

@Lloyd McKenzie @Grahame Grieve
So just to clarify, where we currently have this:

<page>
<nameReference>
<reference value="#5767"/>
<display value="Page content 5767"/>
</nameReference>
<title value="HRex Profiles"/>
<generation value="markdown"/>
</page>

You are saying it needs to be this (where nameUrl contains the name of the extracted markdown file), right?

<page>
<nameUrl value="HRex_Profiles.md"/>
<title value="HRex Profiles"/>
<generation value="markdown"/>
</page>

Just want to make sure we get the fix correct.

Rick Geimer (Mar 16 2019 at 05:48):

Worse case I can manually fix those ImplementationGuide resources if Sean can't get the code updated in time.

Lloyd McKenzie (Mar 16 2019 at 05:49):

All of mine use the equivalent of HRex_Profiles.html. See what works...

Rick Geimer (Mar 16 2019 at 05:57):

ok

Eric Haas (Mar 16 2019 at 16:55):

For the nameUrl. I use the html page too

Eric Haas (Mar 16 2019 at 16:55):

Not the markdown page.

Rick Geimer (Mar 17 2019 at 08:50):

I was able to manually fix this and get a clean build, Sean is working on the code changes in Trifolia so we will be able to clear out these errors by the end of the day Sunday.

However, I am now very confused about what nameUrl should contain. Should it be the file name of the HTML generated by Jekyll, or the markdown file that is used as input to Jekyll? Seems like we need both in the end if we will be relying on the ImplementationGuide resource for both generation and as a means to identify the resulting documentation. Any objections to me filing a change request against ImplementationGuide to add a source[x] field for the input data and clarifying that name[x] is for the output?

Lloyd McKenzie (Mar 17 2019 at 14:19):

The purpose of listing the pages is for the creation of the table of contents and determining hierarchy for breadcrumbs so what's needed is the output HTML names. The input names don't matter if the files exist in one of the source folders so long as the framework takes care of making them .html or .md before Jekkyl runs. However, if you're doing it by reference to source, then yes there'll need to be a name unless the convention we choose to adopt is that 'id' becomes name.

Sean McIlvenna (Mar 18 2019 at 15:59):

A work-around has been made in Trifolia-on-FHIR, for now. But, nameReference should definitely be supported. Otherwise, why even have it?

Lloyd McKenzie (Mar 18 2019 at 19:39):

We'll support it - but there'll need to be a framework that can handle the extraction/retrieval of the references into something that Jekyll can access. It'll have to be part of the IG publisher template work

Last updated: Apr 12 2022 at 19:14 UTC