FHIR Chat · sushi plantuml · shorthand

Stream: shorthand

Topic: sushi plantuml

John Moehrke (Feb 12 2022 at 15:01):

No idea if someone else needs this... but I am making example resources in an IG, would be cool if sushi could have a new type of object in which I write plantuml, and it just puts that somewhere that the IG publisher can process plantuml like it already supports.
This can be done today, but in two different files. And it is harder to keep two files of examples/diagrams aligned than if both the examples and the diagram are in the same file.

Lloyd McKenzie (Feb 12 2022 at 15:07):

What do you mean by "two files"? Current IG publisher lets you put a .plantuml file in images-source and will generate a .svg file in your output folder. Why would you want plantuml inside a FHIR resource?

John Moehrke (Feb 12 2022 at 15:16):

that is the 'second' file.... I explained my use-case. i am making example resources in a .fsh file, those examples are related to a diagram -- in my case a services directory.

John Moehrke (Feb 12 2022 at 15:16):

it is an edge case... hence why I start with a question of if it is useful beyond me

John Moehrke (Feb 12 2022 at 15:17):

might not even be as useful as I imagine

Elliot Silver (Feb 12 2022 at 15:18):

What you’re looking for is one fsh file for both the resource and the plantuml, not the plantuml inside a resource, right?

John Moehrke (Feb 12 2022 at 15:20):

right

Elliot Silver (Feb 12 2022 at 15:20):

I can see it as marginally easier to keep attribute names, etc in sync in one file than in two, or to take advantage of sushi rules to generate common content between the two.

Elliot Silver (Feb 12 2022 at 15:21):

On the other hand the models are very different, and search and replace across files isn’t that hard.

John Moehrke (Feb 12 2022 at 15:30):

the other example I have of this is where I was using plantuml as a prototype UI example - so want to link the UI elements to the data elements in the profile or example. -- which has no good solution even if they could be in the same source file.

Bas van den Heuvel (Feb 14 2022 at 07:17):

What kind of link do you have in mind? Just the attributes or also the links?

Chris Moesel (Feb 14 2022 at 14:14):

We've also had someone recently suggest that it would be helpful to put the intro and notes markdown in the same .fsh file as the definition it applies to. We considered if maybe we could support it via tagged comments (e.g., multiline comments with tags like @NOTES: or @INTRO:). I could see maybe a similar approach working for plantuml (e.g., @PLANTUML:).

The two main issues w/ this are:

• You give up any special support your IDE has. E.g., for the NOTES use case, the markdown would not be syntax-highlighted and the built-in Markdown Preview in many editors (like VS Code) would not work.
• It's outside of the spec (and putting it in the spec would expand FSH beyond what it's currently meant to be). That said, I suppose many things related to the doc that goes into an IG are already outside of spec anyway.

David Pyke (Feb 14 2022 at 14:20):

I think having them as an extension to the FSH spec would be a great idea. I could work up the code in a separate file and then include them if I wanted the previewer or other benefits of my IDE.

I wouldn't make it part of the FSH spec, just a published sushi extension

Bas van den Heuvel (Feb 14 2022 at 20:35):

On plantuml something else comes into play. Plantuml presents (amongst others) class diagrams. The scope of sushi is more on the resource (class). This makes me wonder what diagram is to be generated? One just presenting the resource? What other resource are shown?
In this case a different approach might be more interesting, adding a sushi specific pre-processing step to plantuml in which sushi specific content is injected in the plantuml file.
This will work well for attributes. Not sure whether we need to add something for references and what that would look like.

John Moehrke (Feb 14 2022 at 21:32):

could be like clinfhir can diagram a bundle content.

Bas van den Heuvel (Feb 15 2022 at 07:49):

That could work. The consequence would be that the Bundle would also appear as an artifact in the IG. I do not know whether that is an advantage or disadvantage though. Sounds like something we could try. An extension could label the Bundle as a plantuml collection. We could also consider adding extensions that would indicate what attributes to show: all, just MS, just those defined in the profile, ...

Bas van den Heuvel (Feb 15 2022 at 13:44):

E.g. something like:
Profile: PlantUmlClassBundle
Parent: Bundle

• type = #collection
• link 0..0
• entry
  • extension contains ClassContentLevel named lvl 0..1 MS
  • resource 0..0
  • search 0..0
  • request 0..0
  • response 0..0

Extension: ClassContentLevel

• value[x] only code

Instance: PlantumlClass
InstanceOf: PlantUmlClassBundle

• id = "plantuml"
• entry[+]
  • fullUrl = "http://hl7.org/fhir/StructureDefinition/Patient"
  • extension[lvl].valueCode = #MS
• entry[+]
  • link[+]
    • relation = "subject"
    • url = "http://hl7.org/fhir/StructureDefinition/Patient"
  • fullUrl = "http://hl7.org/fhir/StructureDefinition/Encounter"

Jose Costa Teixeira (Mar 10 2022 at 05:05):

I don't see a way that plantuml would generate nice diagrams without requiring tweaking

Jose Costa Teixeira (Mar 10 2022 at 05:06):

Depends on the diagram and the resource metadata that we are willing to add

Jose Costa Teixeira (Mar 10 2022 at 05:07):

For example, sequence diagrams from an ExampleScenario is ok because the metadata is similar - sequence, actor types, interaction...

Jose Costa Teixeira (Mar 10 2022 at 05:08):

However a class diagram would be harder. There's some need to tell plantuml where to position the elements

Jose Costa Teixeira (Mar 10 2022 at 05:09):

See for example this diagram

Jose Costa Teixeira (Mar 10 2022 at 05:12):

All the lines at the end to say that one box needs to be to the left or to the right of another box (and plantuml's behaviour when the arrow is -> or --> and the renderer used and the version of plantuml...

Jose Costa Teixeira (Mar 10 2022 at 05:22):

If the goal is to say "well, this diagram is always going to be in this resource" then I think a better option would be for sushi to have a syntax for containing special file content:

...
Instance: myBundleExample
InstanceOf: myBundleProfile

/*The following creates a plantuml file - decent delimiters should be found*/
∆∆bundleexample1
@startuml
Class "a little box here"
...
@enduml
∆∆
/*Now back to fshy stuff*/
Description: "This is an example of the document bundle as shown in the diagram <div>{{bundleexample1.svg}}</div>. This example is used in...

Jose Costa Teixeira (Mar 10 2022 at 05:23):

This would generate the plantuml file from sushi (sushi should not care that it is plantuml, only that it is an external file)

Jose Costa Teixeira (Mar 10 2022 at 05:23):

The IG publisher/templates would take care of the rest

Jose Costa Teixeira (Mar 10 2022 at 19:44):

@Chris Moesel how does it sound, the possibility to have "contained files" inside a fsh file?

Chris Moesel (Mar 11 2022 at 13:43):

If the content is inside a definition (and not inside a comment), then it needs to be a part of the grammar, and technically should be part of the FSH spec. I don't think that IG documentation (plantuml, intro, etc) belongs in the spec; IMO, it is outside of scope. One exception would be if we added a very generic keyword that could indicate "the following content is implementation-specific and not required to be understood by all parsers".

But the way we've been thinking about this is as special annotations in comments. So it might look similar to your example above, but it would all be in a block comment, and would be introduced via a special tag.

I think it's definitely feasible and has some advantages. A disadvantage I've noted in the past is that since it is in a .fsh file, you would likely lose any language-specific IDE syntax or snippets (for plantuml, markdown, etc). But still, I do think it's worth looking into. The problem is, we just don't have the available resources to look into it right now.

John Moehrke (Mar 11 2022 at 14:39):

I tend to agree that sushi should stick with sushi specific things. I just initially wondered if there was already an "embedded file here" function that could be used for plantuml script. Second came up the idea of having sushi generate plantuml based on a FHIR object that it created, such as a Bundle (like David Hay's tool can).

Last updated: Apr 12 2022 at 19:14 UTC