Better handle cases where entire modules are conditionalized in chap/assembly files

sterobin commented 3 years ago

Current behavior

Some modules/sections are conditioned, such as to apply for community but not enterprise, or vice versa.

For example, the following two modules in this DMN chap file apply to Kogito community docs but not to Kogito enterprise docs, and thus the two module sections in the chapter file are conditionalized accordingly with an ifdef before the first and an endif after the second:

ifdef::KOGITO-COMM[]

[id="ref-dmn-feel-enhancements_{context}"]
=== FEEL enhancements in {PRODUCT}

{PRODUCT} includes ...
...

[id="ref-dmn-model-enhancements_{context}"]
=== DMN model enhancements in {PRODUCT}

{PRODUCT} also includes ...
...

endif::[]

The expectation is that the above condition tags will be left in place in the converted assembly file surrounding the two converted module includes, as follows:

ifdef::KOGITO-COMM[]

include::ref-dmn-feel-enhancements.adoc[]

include::modules/dmn/ref-dmn-model-enhancements.adoc[]

endif::[]

Instead, what happens today is the following:

The starting ifdef is ignored entirely.
Both includes are included in the new assembly without the condition tags, so they are rendered in enterprise when they should be conditioned to not display in the rendering for enterprise. See lines 51 and 53 of the generated assembly, which should be surrounded by the Kogito community conditions but are not: https://gitlab.cee.redhat.com/red-hat-jboss-bxms-documentation/kie-docs-translator/-/blob/master-kogito/assemblies/assembly-kogito-using-dmn-models.adoc
The closing endif is retained at the end of the second file, the one that immediately precedes the closing tag. As a result, that stray endif breaks the build. See the stray endif on the last line of the second file: https://gitlab.cee.redhat.com/red-hat-jboss-bxms-documentation/kie-docs-translator/-/blob/master-kogito/modules/dmn/ref-dmn-model-enhancements.adoc

Target behavior

Retain all ifdef/endif conditions as they are, including condition tags that should surround a module include in the assembly file not just content in the module file.

This might be tricky because, how can the splitter know if an endif at the end of a module is the close of a condition that encapsulates the entire module and should thus be conditioned in the assembly file VS. just the close of conditioned content within that module and thus be conditioned within the module file? The answer to that determines whether to retain the conditions in the assembly (surrounding the includes) or within the module file.

Example, this is a condition to enclose the includes in the assembly:

ifdef::KOGITO-COMM[]

[id="ref-dmn-feel-enhancements_{context}"]
=== FEEL enhancements in {PRODUCT}

{PRODUCT} includes ...
...

[id="ref-dmn-model-enhancements_{context}"]
=== DMN model enhancements in {PRODUCT}

{PRODUCT} also includes ...
...

endif::[]

Whereas this is a condition to enclose just a portion within the module file:

[id="ref-dmn-model-enhancements_{context}"]
=== DMN model enhancements in {PRODUCT}

{PRODUCT} also includes ...

ifdef::KOGITO-COMM[]
And also does some community stuff.
...

endif::[]

Note how in both cases the second file ends with an endif exactly the same way. Asciidoc doesn't have any trouble because it tracks back to the start ifdef tag wherever it is and removes it out regardless.

So is there a way for the splitter to detect whether to condition out entire modules and retain the ifdefs in the assembly vs. condition out module content and retain the ifdefs only in the module file? It seems to struggle with that today.

Resources

Source repo and branch used: https://github.com/kiegroup/kie-docs/tree/master-kogito
Target repo and branch used: https://gitlab.cee.redhat.com/red-hat-jboss-bxms-documentation/kie-docs-translator/-/tree/master-kogito/

Splitter command used:

target/asciidoc-splitter-1.0-SNAPSHOT-bin/bin/asciidoc-splitter.sh -sr git@github.com:kiegroup/kie-docs.git -sb master-kogito -or git@gitlab.cee.redhat.com:red-hat-jboss-bxms-documentation/kie-docs-translator.git -ob master-kogito -i index.adoc

LightGuard commented 3 years ago

Please provide test case. I thought I had conditionals figured out.

sterobin commented 3 years ago

As discussed in chat, you should have all the info and links that you need above to create a branch or download the zip for a test case.

LightGuard commented 3 years ago

I hate conditionals. Have to think on this a lot more. The way things are done both within asciidoctor and what I've done in the splitter don't make this easy.

LightGuard / asciidoc-splitter