Using ```include``` inside ```include``` results in cyclic references

[yucheng11122017]

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

No response

Tell us about your environment

Windows 10

MarkBind version

V4.1.0

Describe the bug and the steps to reproduce it

<include src="tip.md" boilerplate> 
<span id="tip_body">
    <include src="tip.md" boilerplate>
    <span id="tip_body">hi</span>
    </include>
</span>
</include>

tip.md is a boilerplate used in the documentation.

Results in

Expected behavior

Expected to have one outer boilerplate and one inner boilerplate

Anything else?

No response

[damithc]

Good catch @yucheng11122017

[yucheng11122017]

The problem was that the inner variable was being overridden by the outer variable, which resulted in cyclical references.

Eg. Outer include has variable tip_body which was

<span id="tip_body">
    <include src="tip.md" boilerplate>
    <span id="tip_body">hi</span>
    </include>
</span>

Inner include has variable tip_body which was

<span id="tip_body">hi</span>

However, when processing the inner include, the inner tip_body will be overridden to be the outer tip_body resulting in cyclical references.

This is the desired behavior as stated by the User Guide where outermost variables are given priority.
Is there a reason for this design?

[damithc]

This is the desired behavior as stated by the User Guide where outermost variables are given priority.
Is there a reason for this design?

This is like a golden rule in reuse. The reuser (i.e., the outer context) should be able to adapt the reused content without changing its actual content (similar to the open-closed principle). Allowing the outer context to override the variables is a way to facilitate that.

[yucheng11122017]

Ah I see. Thank you!
Would a good way to approach this to then allow the inner variable to override if

1. A boilerplate is being used
2. The outer variable has already been used in a outer boilerplate

Another way I can think of is to enable an override option to allow inner variables to override outer variables (simliar to !important in CSS) but that would violate the rule in reuse

[damithc]

<include src="tip.md" boilerplate> 
<span id="tip_body">
    <include src="tip.md" boilerplate>
    <span id="tip_body">hi</span>
    </include>
</span>
</include>

@yucheng11122017 is there a need for this kind of code? If there is no realistic need for such code (except in very rare/unusual circumstances), we can leave it be.

[tlylt]

Good find @yucheng11122017!

I agree with @damithc that would be great if we could get more clarity on how the above problematic usage is relevant in a realistic context, i.e. some examples of how this is going to be used in a website and how likely this will occur.

If possible, we should:

• document the reason (Using include inside include results in cyclic references #2177 (comment)) provided above if not mentioned anywhere in the UG.
• if it's really rare that this occurs and we still want to have a fix for someone who's unfortunately going to encounter this, we could document the way to manually construct the above without the boilerplate, to showcase how the intended outcome can still be achieved, albeit in a more long-winded way.

[yucheng11122017]

I was trying to create a standardized boilerplate for the boxes in the documentation for #2089 so that the formatting of all boxes can be changed by changing just the boilerplate. But there are some instances of boxes within boxes like here that has boxes within boxes.
I think if the boilerplates are used to standardise some form of presentation components and users use the components within the components this error might occur again.
The way to manually solve this would be to just copy the code from the boilerplate and replace the variables I guess.

[tlylt]

I was trying to create a standardized boilerplate for the boxes in the documentation for #2089 so that the formatting of all boxes can be changed by changing just the boilerplate. But there are some instances of boxes within boxes like here that has boxes within boxes.

I see. In that case we could still enforce the use of the template at the outermost layer and if there's an inner box, one can write it manually. Does that work for that standardization?
Something like:

<include src="tip.md" boilerplate> 
<span id="tip_body">
    <box>
    Warning!
    </box>
</span>
</include>

As for this issue, let's document the reason and workaround for now, and re-look at this if it becomes a serious limitation.

[ang-zeyu]

We could also support some form of <include no-variable-override> attribute but then again this problem can be avoided with good variable naming 🤷‍♂️

Agree with documenting it more clearly if not already done