Support asciidoc tags for reusing module content

[sterobin]

Current behavior

Any module content that is reused in the source uses the // tag: ... surrounding syntax, and these portions are not converted to the expected include by the splitter.

Example 1: The following section in the source creating-running chap is retained exactly as is after the split, instead of being converted to an include as expected:

// tag::ref-kogito-app-examples[]
[id='ref-kogito-app-examples_{context}']
== Example applications with {PRODUCT} services

{PRODUCT} includes example applications in the https://github.com/kiegroup/kogito-examples[`kogito-examples`] repository in GitHub.
....
// end::ref-kogito-app-examples[]

Example 2: The following include in the source process-services chap, which is an include that points to the reused/tagged module content, is duplicated exactly as is over to the target instead of being converted to a standard include:

include::{asciidoc-dir}/creating-running/chap-kogito-creating-running.adoc[tags=ref-kogito-app-examples]

Desired behavior

Convert tagged module content in the source like this:

// tag::ref-kogito-app-examples[]
[id='ref-kogito-app-examples_{context}']
== Example applications with {PRODUCT} services

{PRODUCT} includes example applications in the https://github.com/kiegroup/kogito-examples[`kogito-examples`] repository in GitHub.
....
// end::ref-kogito-app-examples[]

To a standard include in the target like this:

include::modules/creating-running/ref-kogito-app-examples.adoc[leveloffset=+1]

And convert an include for the reused module content in the source like this:

include::{asciidoc-dir}/creating-running/chap-kogito-creating-running.adoc[tags=ref-kogito-app-examples]

Likewise to a standard include in the target like this:

include::modules/creating-running/ref-kogito-app-examples.adoc[leveloffset=+1]

[LightGuard]

I am unsure what you want in example 1. That should be the source of the tag. I can't convert that to an include because it won't go anywhere, If I'm understanding correctly, what you're asking for would be like telling something to include itself, but without any reference to what it is. Maybe we need to jump on a call quickly to get on the same page.

[sterobin]

Meaning, that module section in the source is supposed to be converted to a module file and then replaced with an include in the new assembly as usual during the split, but because it’s surrounded by the tags (in order to enable it to be reused elsewhere via include), the splitter apparently doesn’t convert it to a module file nor replace the content with the module include in the new assembly. Just ignores it and retains that module section text as is in the new assembly.

If still unclear, happy to chat more. Sorry for the confusion.

[LightGuard]

Huh. Okay, thanks. I'll take a look.

[LightGuard]

Looking at this a bit more, it looks like this is gated behind a preprocessor ifdef line. Could you try removing that ifdef (and corresponding endif) and seeing if it works as intended? If it does, there's a new feature I added a couple of days ago to pass attributes to asciidoctor (using -a / --attributes KEY=VALUE). You could give that a shot passing KOGITO-ENT=true with the -a flag.

[sterobin]

@LightGuard , ah, that would actually explain too why those "Additional resources" sections and an artifacts include didn't make it over, since they too are ifdefed.

Yep, that was it. Just confirmed. Cool, so sounds like will be resolved by passing the attributes variable now. Thanks Jason.

[LightGuard]

Perfect! Feel free to close the issue.

Sent from my iPhone

On Jun 22, 2020, at 16:48, Stetson Robinson notifications@github.com wrote:

 @LightGuard , ah, that would actually explain too why those "Additional resources" sections and an artifacts include didn't make it over, since they too are ifdefed.

Yep, that was it. Just confirmed. Cool, so sounds like will be resolved by passing the attributes variable now. Thanks Jason.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[sterobin]

@LightGuard , well, before I close, this issue is about converting both the tagged portion (Example 1 above, which sounds like will be resolved with the attribute flag) and the corresponding include in the source that needs to be converted during the split to the corresponding include for the assembly (Example 2 above). Using tags has those two connected aspects to it, both of which to be handled by the splitter.

So in short, the behavior with tags during the split needs to go like this:

1. Delete the tag beginning and end that surrounds the module when the module is split (so you don't end up with the surrounding tags in the split module file).
2. Replace that tagged module content with the corresponding include in the generated assembly as usual (sounds like this step will be taken care of).
3. Convert any existing includes in the source that rely on this tag (point to it for reuse) to the corresponding include in the split version. See Example 2 above.

I walk through this as well in the "Desired behavior" portion above, with examples of what the tagged portion and the source include should be converted to. Let me know if it's unclear and we can jump on a quick call.

[LightGuard]

Two and three should be done. I don’t see a reason to do one, and it could potentially break other tagged regions that don’t reference a section. Tagged sections are delimited with comments. It might be a little noise in the source, but won’t affect the output.

[sterobin]

@LightGuard I guess that's true. I really don't see anyone using tags for anything other than reuse in the source, and I did want to cut down on the noise in the split version, but I suppose it's not good to make those assumptions about tags long term.

Closing.