Customizing Yaml header properties to DITA specialized metadata element

[kirkilj]

Hi @jelovirt, You may not recall, but I previously asked if we could use the lwdita SchemaProvider mechanism to convert certain Yaml header properties to a specialized DITA metadata element. In our scenario, the name of the property/metadata element is “usecase”. At the time you said that you wouldn’t recommend it. Our IA group is doing major refactoring of content from a component-based approach toward user-centric information design, which requires a retraining of our writers to make their content use-case based. Our React-based HTML5 viewer will leverage this metadata along with a SubjectScheme2Json-based hierarchical taxonomy to inform our semantic search capabilities and chatbots. We’d like to reduce any conceptual speed-bumps and avoid using or , since it adds noise to the visual semantics. We’d greatly prefer to generate a metadata element which our specialized RNG/DTDs support.

In looking at the implementation details of how LwDITA is implemented, our intern, Raghav, pointed out that the MetadataSerializerImpl class is what’s used to convert the Yaml header properties to the corresponding DITA metadata element.

It appeared initially to us that we might be able to subclass MetadataSerializerImpl in our SchemaProvider plugin and modify some methods to customize the metadata conversion. However, in looking at the lwdita implementation more closely, it looks like there might be some private members in the class hierarchy that we wouldn’t be able to access.

My team is new at this level of Java development, so certain questions that someone like Radu could answer himself easily by a thorough examination of the lwdita implementation, leveraging his many years of Java development, is beyond the current grasp of our team.

We’re also aware of the whole “square peg in a round hole” impedance mismatch between Markdown and DITA and that we might hit some dead-ends as we go.

We’d appreciate knowing if we’re indeed heading toward a dead-end with this usecase metadata request from our IA team.

[rkhanna222]

Hi @jelovirt,

As John indicated that our team's aim is to modify MetadataSerializerImpl in order to generate a unique metadata tag named "usecase". To accomplish this, it's essential for us to extend the DitaRenderer class. However, we're currently facing a roadblock because DitaRenderer doesn't have a default constructor, rendering it unextendable. Additionally, DitaRenderer incorporates a private subclass named MainNodeRenderer, which through its constructor, invokes further functionality (TopicRenderer) that we're interested in customizing.

At this juncture, we're evaluating two potential options: One is to develop a custom class for DitaRenderer and an associated subclass to facilitate further function calls, but this isn't typically considered the best practice. Alternatively, we're contemplating asking for your help to change the MainNodeRenderer class and the DitaRenderer's constructor to public, allowing us to extend them.

Here's the current sequence of operations for better understanding:
MarkdownParserImpl -> DitaRenderer -> MainNodeRenderer (private subclass) -> TopicRenderer -> MetadataSerializerImpl

Our proposed flow, if we proceed with our customizations, would be as follows:
MarkdownParserCustomImpl -> DitaRendererCustom -> MainNodeRendererCustom (private subclass) -> TopicRendererCustom -> MetadataSerializerImplCustom

Given these circumstances, we would appreciate your advice. What do you think would be the best course of action for our situation? Is there an alternative solution you would suggest?

[raducoravu]

Jarno's entire Java code is available to you, how about if you take his code, change the package name and make it yours instead of extending the Java code in the lwdita plugin?

[kirkilj]

Hi @raducoravu, thanks for your reply.

Raghav suggested the same thing as a fallback. I just wanted to make sure we weren't overlooking a cleaner alternative that wouldn't require us to copy his code and then have to merge updates manually from the LwDITA project when it's updated.

I assume Syncrosoft has to manually do that quite a bit when you have to patch certain OSS components to get around limitations. Do you mostly fork the projects in GitHub and work with those in a pure Git workflow, or do you just download source and diff outside of Git to merge?

I also wanted to keep @jelovirt in the loop so he can stay abreast of the use cases organizations envision with LwDITA. He may see opportunities to improve extensibility options without sacrificing key aspects of the code base.

I'll be on holiday for 2 weeks starting July 31, so Raghav will carry the torch in the interim.

Do you know if Jarno's on holiday now? Many of Nokia's employees in Finland take some or all of July off.

[raducoravu]

@kirkilj I do not know about Jarno's holiday plans.

Our DITA OT plugin's folder name starts with "com.oxygenxml.dynamic.resources.converter" so it gets loaded by the DITA OT before the "org.lwdita" plugin as most plugins are loaded alphabetically by folder name.
We do not work the lwdita project on GitHub. Like in the screenshot above our custom DITA OT plugin patches only certain classes from the "com.elovirta.dita.markdown" package to make various changes to them and uses the rest of the classes as they are.
But this means we need to manually adjust our patches when a new release of the lwdita plugin is launched.

Screenshot 2023-07-28 at 07.40.47

[kirkilj]

Hi @raducoravu, Thanks for the screenshot especially. It lines up with what Raghav discovered navigating the codebase. It may very well be the case that Jarno implemented the SchemaProvider mechanism to handle the cases he was concerned about as far as supporting different flavors of Markdown, such as MDITA, but there hasn't been enough people yet wanting to use the new mechanism to affect certain types of behavior, such as custom metadata elements. Some classes and methods may have been originally declared as private or protected as a safe practice in earlier versions, but which Jarno may want to open up so that they can be subclassed and refined by a SchemaProvider.

We are also having a problem where our SchemaProvider is not getting discovered and invoked when the schema Yaml header is used in Markdown test content. Raghav put some output to the console to signify when our SchemaProvider class is used, and we're not seeing it in the output. Either myself or Raghav will send you a zip via email of our custom plugin as I promised earlier to explore how Oxygen's Markdown editor might be able to also use our SchemaProvider.

[jelovirt]

Getting back to this late, I think it might be better if I added extension points (not DITA-OT plug-in extension points) to allow customizing some processing.