Stream: IG creation
Topic: Local use vs. final publication
Michaela Ziegler (Oct 21 2020 at 09:15):
Since a short time i get the following message when i build the IG with the publisher locally:
Done. Note that this IG is good for your local use but is not suitable for use as a final publication (consult Confluence for publishing advice if you are actually building with intent to publish)
I have looked here to see what I need to change, but do not see the problem:
So far we have been able to publish our IG's, has anything basically changed?
Here is an IG example where this information appears locally: CH Core
Lloyd McKenzie (Oct 21 2020 at 15:36):
When you use the IG Publisher in 'regular' mode, it doesn't generate redirects and similar information you'd want for a 'full' publication.
Elliot Silver (Oct 21 2020 at 18:08):
Lloyd McKenzie said:
When you use the IG Publisher in 'regular' mode, it doesn't generate redirects and similar information you'd want for a 'full' publication.
Are those difference "things HL7 wants for a HL7 publication" or "things any publisher wants"?
David Pyke (Oct 21 2020 at 18:13):
Sorry for the tangent, but how does one use the publisher in "full" mode?
Jose Costa Teixeira (Oct 21 2020 at 18:32):
i think this applies to any publisher
Grahame Grieve (Oct 21 2020 at 19:14):
when you do a local build, the IG publisher builds the guide for you locally. That is, for the had drive location you are using. If you then build another guide locally that depends on it, your references between guides will work locally. But if you take those guides and post them to the web somewhere, the references will still point to your local drive. Users will report broken links
Grahame Grieve (Oct 21 2020 at 19:14):
when the guides are built for build.fhir.org, the IG publisher knows where they're going to be, and builds them accordingly, so references between the IGs work as people expect.
Grahame Grieve (Oct 21 2020 at 19:15):
if you want to build for posting to an actual web site, neither build is suitable, since they will both contain links that point people to the wrong place.
Grahame Grieve (Oct 21 2020 at 19:16):
I have looked here to see what I need to change
you don't need to change anything. it's working as designed, and how it works for you. Unless you actually want to build for posting to a particular web site.
Grahame Grieve (Oct 21 2020 at 19:16):
in which case, you add a parameter -publish {url] which is the URL where the IG will be published
Elliot Silver (Oct 21 2020 at 19:32):
Would it be helpful to include a mention of -publish in the message so readers have a hint about what the issue is?
Grahame Grieve (Oct 21 2020 at 19:33):
I don't want to mention a solution without the supporting knowledge
Jean Duteau (Oct 21 2020 at 19:34):
i'm not even sure why we have this pseudo-warning. i keep wondering what i did wrong
Jean Duteau (Oct 21 2020 at 19:35):
if I don't need to change anything and it's just saying that the guide built will only work on your local machine, that's a weird way to say it
Grahame Grieve (Oct 21 2020 at 19:35):
it exists because people think that posting their local guides to the web works
Grahame Grieve (Oct 21 2020 at 19:35):
if you think that there's better wording, feel free to propose it
Jean Duteau (Oct 21 2020 at 19:42):
Grahame Grieve said:
it exists because people think that posting their local guides to the web works
So I've posted two of my guides that I've built locally to the web and they appear to work. what should I be looking for to see what is broken?
David Pyke (Oct 21 2020 at 19:43):
Just wait until someone tries to use yours as a dependency. THat's when it breaks.
Jean Duteau (Oct 21 2020 at 19:47):
okay, that's not what the message says though.
Note that this IG is good for your local use but is not suitable for use as a final publication.
This is just screaming that the guide I built has something unknown wrong that will stop it from being considered a real IG.
Would this be a better message for what it is trying to say:
NOTE: This IG as built may have dependency links that are only valid for your local build. Migrating this to the web as-is may create broken links. Consult Confluence for publishing advice if you are actually building with intent to publish this on the web. (HL7 guides will have this automatically done by the build process).
Grahame Grieve (Oct 21 2020 at 19:49):
too long and even I don't know what 'depedency links' are
Jean Duteau (Oct 21 2020 at 19:51):
okay, change 'dependency links' to just 'links'.
Grahame Grieve (Oct 21 2020 at 19:52):
what should I be looking for to see what is broken?
technically, what is wrong is the url in the package.json in package.tgz. Any tool that uses your guide will think that it's found wherever that url is. that includes the IG publisher when creating guides that depend on this guide, but also the validator when it creates references to your guide in the error messages (you don't see them but they will start being more obvious when the validator goes on line - which is very soon now)
The IG publisher only knows how to set the url correctly for online publication if you tell it where that is
Grahame Grieve (Oct 21 2020 at 19:53):
it's not links in your guide that are broken, it's any generated links to your guide
Jean Duteau (Oct 21 2020 at 19:54):
so if my guide is creating links to another guide that was also generated on my local machine, those links will be broken?
Grahame Grieve (Oct 21 2020 at 19:55):
yes. And you probably won't notice since they will work locally.
Grahame Grieve (Oct 27 2020 at 02:53):
I have updated the text for the warning to what Lloyd suggested for the next release
Grahame Grieve (Oct 27 2020 at 02:53):
only, it doesn't point anywhere for documentation until I have the time to actually write the documentation :-(
Last updated: Apr 12 2022 at 19:14 UTC
