Adjust subheading level offset correctly in module files correctly after the split

[sterobin]

Current behavior

When module sections have subheadings, sometimes the splitter adjusts the module heading correctly down to a level-one = heading as expected, but the subsequent subheadings within that module aren't taken back by the same number of level offset adjustments during the split. This results in a level-one = heading for the module, followed by a subheading that's too high, like a level-three === instead of a level-two ==.

Example, in the source OpenShift chap file, there is the following module section that includes a couple subheadings, as shown:

[id="con-kogito-operator-architecture_{context}"]
=== {PRODUCT} Operator architecture

[role="_abstract"]
The {PRODUCT} Operator ...

==== {PRODUCT} Operator dependencies on third-party operators

The {PRODUCT} Operator uses ...

==== {PRODUCT} Operator core package structure

The {PRODUCT} Operator

The expectation is that each subheading in the module will be reduced by however many levels the module heading was reduced by for it to start as a level-one =. In this case, that's two levels back (module starts as === but needs to be = after split), so each subhead should likewise be reduced by two levels (so ==== to ==, etc.).

Instead of that, this is what happens in the split OpenShift module file:

[id="con-kogito-operator-architecture_{context}"]
= {PRODUCT} Operator architecture

[role="_abstract"]
The {PRODUCT} Operator ...

=== {PRODUCT} Operator dependencies on third-party operators

The {PRODUCT} Operator uses ...

=== {PRODUCT} Operator core package structure

The {PRODUCT} Operator

Note that the module heading is correctly reduced by two levels to make it a level-one = as expected, but the subheads are reduced only by one level to === instead of by two levels to ==, which is needs to do to match the module heading treatment. As a result, the build fails.

Target behavior

When splitting modules, reduce the module heading down to a level-one = (happening today) and then reduce any subheadings within that module file by the same number of levels (not happening today) to create the proper structure.

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]

Yeah... I don't know about that. The current behavior keeps the files as valid asciidoc files. Messing with the headers and trying to keep track of them is really not something I want to be doing. Let me think on it.

[sterobin]

@LightGuard I don't follow.The splitter already messes with the headers by adjusting the first heading, so by not adjusting subheadings accordingly, it's creating invalid asciidoc files. I'm just saying that we need to ensure it's generating valid asciid files with valid headings. So I'm not sure what you're saying or what you're referring to.

[LightGuard]

Please provide a test case.

[sterobin]

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.

[sterobin]

@LightGuard Per our chat, I found what I was saying, where the splitter already adjusts subheadings in modules correctly some places but then not in other places.

Example of where the splitter adjusts subheadings incorrectly: See my example above.

Example where splitter adjusts subheadings correctly:

From source chapter:

....

[id="con-kogito-automation_{context}"]
== {PRODUCT} business automation

[role="_abstract"]
{PRODUCT} is a ...

=== Cloud-first priority

{PRODUCT} is ...

=== Domain-specific flexibility

{PRODUCT} adapts ...

=== Developer-centered experience

Another focus ...

To target module file:

[id='con-kogito-automation_{context}']
= {PRODUCT} business automation

[role="_abstract"]
{PRODUCT} is  ...

== Cloud-first priority

{PRODUCT} is ... 

== Domain-specific flexibility

{PRODUCT} adapts ... 

== Developer-centered experience

Another focus ...

Note how the splitter handled all subheadings perfectly. This isn't the case in the example I provided above, and not sure why some headings are handled correctly and others not.

[LightGuard]

87 is related