Page variables should only be overridden by request

[damithc]

v1.17.2

Context:
parent.md:

<variable name="title">Parent page</variable>

Refer the <include src="child.md#summary" />

child.md:

<variable name="title">Child page</variable>

<span id="summary">
summary of page: {{ title }}
</span>

Current: the parent.md renders Refer the summary of page: Parent page
Expected: Refer the summary of page: Child page

Suggested: override page variables only when specifically requested, as follows:

<variable name="title">Parent page</variable>

<include src="child.md#summary">
 <span id="title">{{ title }}</span>
</include>

Rationale: to avoid accidental overriding. We can expect variable names such as title to occur multiple times within an include chain. This problem tripped me up several times when doing #668

[damithc]

@jamos-tay what do you think?

[jamos-tay]

Ah @yamgent and I actually had a discussion on this problem here, the reasoning we decided to do it this way was to differentiate it from {% set %}.

I'm not too sure what's the correct thing to do in this situation. Maybe we could have some notion of public (inheritable) and private (uninheritable) variables?

[damithc]

I see the point about set that was raised in the other thread. In the current version, if the user doesn't want the variable to be overridden, he should use set instead, am I right? Based on that behavior, my instinct as an author is to use set by default (to avoid unintended overriding) and use variables only when there is a specific need to propagate a variable down the include chain.

One concerns about the above is that nunjucks is not a part of MarkBind. It's an advanced templating mechanism that normal MarkBind users shouldn't need to use.
Another concern is that set follows nunjucks semantics, which means those variables cannot be accessed from outside as I want to do here

Perhaps it is safer to require any overriding to be explicit? What do you guys think?
Variable title propagated:

<variable name="title">Parent page</variable>

<include src="child.md#summary">
 <span id="title">{{ title }}</span>
</include>

Variable not propagated:

<variable name="title">Parent page</variable>

<include src="child.md#summary">
</include>

[yamgent]

Our variables are always consistently being overridden, so having only page variables being not overridden makes the behaviour confusing and a bit difficult to explain.

Maybe use a different name other than <variable>? <properties>?

[acjh]

Using <variable> is consistent with the usage {{ title }}.
Also, would outer variables override inner variables properties?

How about defining page variables as explicitly specifying page attribute meaning "only for this page", instead of implicit page variables meaning "defined in this page"?

<variable page name="title">Parent page</variable>

These would continue to be overridden by outer variables.

[damithc]

Our variables are always consistently being overridden, so having only page variables being not overridden makes the behaviour confusing and a bit difficult to explain.

We only have two types of variables, right? global variables (in variable.md) and page variables.

The current 'always override' policy is well-intentioned as it is meant to give authors a powerful reuse mechanism. That's why I was in favor of it at first. Using it once forced me to rethink my view. It seems in the mechanism is too dangerous to use in practice. It forces the author to consider all page variables in a single scope (as they can be overridden from anywhere else in the code base), which is too big a burden when working in a large code base. It's like raising all variables into the global scope. That means if an author introduces a variable x into foo.md (say, to get rid of a local duplication), she has to check all files (both parents and children) in every include chain that foo.md is in. If foo.md is in a sub-site, some of those files that may potentially and unintentionally override x may not even be in the repo.

It feels like the 'variables' we have implmented is a special kind of mechanism that are somewhat different from what a normal programmer consider a variable. I feel it is more intuitive if the default behavior of variables matches that of a public variable? They can be read/modifed but only by the code that has a direct handle it it, and the modification is explicit. We can still support the current behavior but not call them variables?

How about defining page variables as explicitly specifying page attribute meaning "only for this page", instead of implicit page variables meaning "defined in this page"?

<variable page name="title">Parent page</variable>

Yes, that might work. Alternatively (or in addition to), we can use global-override to indicate the "special" type of variables that can be overridden from anywhere. By default, they can only be overridden by specifying the value at the point of inclusion and their values can be read by the parent only.

<variable global-override name="title">Child page</variable>

[acjh]

By default, they can only be overridden by specifying the value at the point of inclusion and their values can be read by the parent only.

That's the opposite of "outer overrides inner" for reuse, and may require changes to the order of how MarkBind processes includes and renders variables. Is there a use case?

[damithc]

That's the opposite of "outer overrides inner" for reuse, and may require changes to the order of how MarkBind processes includes and renders variables. Is there a use case?

It's actually "outer can override inner by request" i.e., trying to avoid "outer overrides inner accidentally".

This one will be overridden by a variable title anywhere in the upstream include chain (i.e., the current behavior). Dangerous to use. Use sparingly.
<variable global-override name="title">Child page</variable>

This one can be overridden by immediate outer; but need to request. To propagate the value down an include chain, need to be specified at each level of inclusion. Safer. Use by default.
<variable name="title">Child page</variable>

[acjh]

"read by parent" → isn't parent outer?

[damithc]

Is there a use case?

A common use case for variables is duplication avoidance. In fact, that's the reason why I used the title variable (see example below). It was a nasty surprise to realize the title is being overridden by the parent.

<variable name="title">Books</variable>

<frontmatter>
title: {{ title }}
</frontmatter>

# {{ title }}
...

[damithc]

"read by parent" → isn't parent outer?

Yes.

Reading a variable by outer (not supported yet):

TOC:
<include src="chapter1.md#title" />
<include src="chapter2.md#title" />

Including by outer, without overriding:

Chapter 1:
<include src="chapter1.md"/>

Including by outer, with overriding:

Chapter 1:
<include src="chapter1.md">
 <span id="title">Preview of Chapter 1</span>
</include>

In all three cases I can add a <variable name="title">Parent</variable> on top without affecting the behavior of the includes. Example:

<variable name="title">Parent</variable>
Chapter 1:
<include src="chapter1.md">
 <span id="title">Preview of Chapter 1</span>
</include>

If I want the variable to be propagated to the inner, I would do this:

<variable name="title">Parent</variable>
Chapter 1:
<include src="chapter1.md">
 <span id="title">{{ title }}</span>
</include>

So, my perception of the variable is like this:

class Chapter1{
 public String title = "Chapter 1";
}

It's usage:

new Chapter1().title // read

new Chapter1().text() // include as is

//include with overriding
c = new Chapter1();
c.title = "New title";
c.text()

Is my perception (OOP-influenced) different from you guys?

[acjh]

"read by parent" → isn't parent outer?

Yes.

That's very different from "outer can override inner by request".

Reading a variable by outer (not supported yet):

Ah, you mean #682.
Does that already work if you define the variable with id attribute?

<variable name="title" id="title">