Style syntax for @related variables

[bwiernik]

We need to write the style syntax for calling related items.

[bdarcus]

Isn't it just a related attribute on the appropriate rendering nodes?

[bwiernik]

That's not in the schema currently

[denismaier]

Basically, that should just be a new atttibute related on cs:date, cs:names, cs:text, and cs:number? Correct?

[bwiernik]

That's all the rendering elements except choose, right?

[bwiernik]

We might consider allowing it on cs:group and cs:macro and making it inheritable?

[denismaier]

We might consider allowing it on cs:group and cs:macro and making it inheritable?

So, to have text variable="title" in a macro/group, but have it expanded to text variable="title" related="original"?

[bwiernik]

Yeah, thinking of something like:

<macro name="reviewed" related="reviewed">
  <group delimiter=", ">
    <text variable="title"/>
    <names variable="author">
      <label form="verb" suffix=" "/>
      <name/>
      <substitute>
        <names variable="editor"/>
       </substitute>
    </names>
    <data variable="issued"/>
  </group>
</macro>

versus requiring @related to be set on each variable individually.

[bwiernik]

That would also make it clear what should happen when this appears:
<text macro="contributors" related="original"/>

[denismaier]

Good idea.

[denismaier]

What if the macro definition has a related attribute and the macro call as well?

[bwiernik]

The general inheritance rules are that a lower-level specification overrides an inherited value from higher-up. I think that's fine here. If that shouldn't happen, the style should be written accordingly.

[denismaier]

How would you call a variable with the standard relationship? related="item"?
E.g., if you have a macro with related="original", but one variable would refer to a variable from the item itself.

[bwiernik]

Is that necessary?

[bwiernik]

I'm not sure that's really necessary, but that could be accomplished by not setting related on the macro, but instead setting it lower down on the relevant groups/variables.

[denismaier]

You are probably correct.

Another thing I'm thinking of: if we indeed do this, we could change container- and volume- variables to relationships. Because most variables are called by macros anyway, and your suggestion would make having related attributes everywhere obsolete.

[bwiernik]

Let's leave that discussion for another day 😏

[denismaier]

That would also make it clear what should happen when this appears:
<text macro="contributors" related="original"/>

The general inheritance rules are that a lower-level specification overrides an inherited value from higher-up. I think that's fine here. If that shouldn't happen, the style should be written accordingly.

Again: What should happen if you define a macro like so:

<macro name="reviewed" related="reviewed">
...
</macro>

And then you call it like that:

<text macro="reviewed" related="original"/>

I don't think that would make much sense.

There maybe should be two variants:

1. macro definition without @related, macro call with @related
2. macro definition with @related, macro call without @related

And, of course, definition and call without @related will also stay valid.

I fear allowing @related at the same time on definition and call could open the door to a lot of bugs and unexpected behavior.

Is that correct? If yes, is there a way to specify this? Probably not in rnc, but what about schematron? @bdarcus @bwiernik

[bdarcus]

If yes, is there a way to specify this? Probably not in rnc, but what about schematron?

I don't think you could do it in RNC.

Should be easy in schematron.

[denismaier]

Should be easy in schematron.

Ok. At least.

And what do you think about the overall issue?

[bdarcus]

First thoughts (subject to change):

• I don't see why we should allow @related on macro.
• I don't think we should allow @related on macro calls; I agree it introduces potential problems, and I don't see the benefit weighed against those risks

What am I missing?

[denismaier]

First thoughts (subject to change):

• I don't see why we should allow @related on macro.
• I don't think we should allow @related on macro calls; I agree it introduces potential problems, and I don't see the benefit weighed against those risks

What am I missing?

The idea is 1. to make macros usable with different relations (e.g. a macro "title" with reviewed and original relations), and 2. to make macro definitions easier (no need to repeat @related="original on each element in the macro definition).

[bdarcus]

The idea is 1. to make macros usable with different relations (e.g. a macro "title" with reviewed and original relations), and 2. to make macro definitions easier (no need to repeat @related="original on each element in the macro definition).

I meant only on the macro node; not on sub-elements within it.

Is the second worth the cost?

[denismaier]

Sorry, I wasn't clear about the first use case.
That was supposed to mean this:

<macro name="title">
...
</macro>

Later you call it with:

text macro="title" related="reviewed"/> or text macro="title" related="original"/>

[denismaier]

So @bdarcus @bwiernik what do you think? Should we add @related to macros and groups?
Other opinions, @georgd @cormacrelf @fbennett @PaulStanley @jgm?

[bwiernik]

I don't have a strong preference one way or the other on cs:macro. I would like to see it on cs:group. If we don't allow it on cs:macro, then we should write the schema to disallow:
<text macro="contributors" related="original"/>

[georgd]

I think, @related is indispensable on cs:text[@variable]and on cs:group.

Allowing it on cs:text[@macro] calls might prove useful if that element is the only one of the related item to be called at that place, so using a group wouldn’t make much sense.

Allowing it on cs:macro is not so important IMO as you’d naturally use a cs:group inside it if calling multiple elements. If not, you could as well put the @related on the single element and still name the macro accordingly.

An other point that I haven’t seen in this discussion: what about nested relationships? Say, a macro contains a cs:group[@related="reviewed"] which in turn contains a cs:group[@related="original"] further down the tree. Which item is the @related="original" pointing to? I assume the original-relation of the reviewed item?

[bwiernik]

Allowing it on cs:text[@macro] calls might prove useful if that element is the only one of the related item to be called at that place, so using a group wouldn’t make much sense.

I don't know what you mean here. If the macro only contains one element, then it can just be rendered as a single rendering element (but then why is it a macro anyway?).

An other point that I haven’t seen in this discussion: what about nested relationships?

My thinking was that there would be no nested relationships. We should probably explicitly disallow them in the data schema.

[bdarcus]

My thinking was that there would be no nested relationships. We should probably explicitly disallow them in the data schema.

I agree, but it's not possible or convenient to do this formally, in the JSON schema, at least.

Would need to be communicated via documentation.

[georgd]

Allowing it on cs:text[@macro] calls might prove useful if that element is the only one of the related item to be called at that place, so using a group wouldn’t make much sense.

I don't know what you mean here. If the macro only contains one element, then it can just be rendered as a single rendering element (but then why is it a macro anyway?).

What I was thinking of: within a cs:group, you are calling various macros but only one of them is a related macro, all the others refer to the item itself:

<group delimiter=", ">
  <text macro="title"/>
  <text macro="issued"/>
  <text macro="title" related="original"/>
  <text macro="accessed"/>
</group>

[bdarcus]

This is why I think we probably shouldn't allow that.

The style author should write two macros, or a single macro with whatever conditional logic.

[georgd]

This is why I think we probably shouldn't allow that.

The style author should write two macros, or a single macro with whatever conditional logic.

I’m sorry, I’m missing the reason for not allowing it.

[bdarcus]

Concern about complexity, debugging, etc.. I'm not 100% certain on this yet though, so could be convinced otherwise.

[georgd]

Concern about complexity, debugging, etc..

I'm not 100% certain on this yet though, so could be convinced otherwise.

Is this about nested relations or about @related on cs:text[@macro]?

[bwiernik]

I think we want to avoid any situation where a block is applied to two different "items" (e.g., the base item, original, reviewed). If that's possible, it's going to be highly prone to incorrect output.

[bwiernik]

I see no reason to allow it on cs:macro---just put it on a ca:group inside if needed.

With respect to cs:text@macro, I agree that I see too many cases of ambiguous expectations, that I it would be best to prohibit inheritance of @related on it.

[georgd]

How should the processor handle a case of nested groups that contain two different `@related`s? Or could that be prohibited by the schema? Brenton M. Wiernik <notifications@github.com> schrieb am Mo., 17. Aug. 2020, 04:12:

…

I see no reason to allow it on cs:macro---just put it on a ca:group inside if needed. With respect to ***@***.***, I agree that I see too many cases of ambiguous expectations, that I it would be best to prohibit inheritance of @related on it. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#357 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABUH4W5OWJZWLJCEWAMD2TSBCGZLANCNFSM4P4WHRUA> .

[bwiernik]

I think we should prohibit that.

[georgd]

Sorry for my igrnorance: will xml-validators detect that in nested macro calls?

[bwiernik]

Oh, you mean in styles, not in data. In styles, this would follow normal inheritance rules--a specified attribute overrides an inherited attribute.

[denismaier]

Ok, coming back to this now. I think I can start a PR in the not so distant future. I propose we add @related on cs:date, cs:names, cs:number, and on cs:text when it renders a variable. cs:text with term or value won't make much sense anyway.

[bwiernik]

That sounds good.

At least for CSL 1.1, we should keep the deprecated plain related variables around, with the understanding that <text variable="original-title" is equivalent to <text variable="title" related="original"/>.

[denismaier]

On keeping these around, see my comment in the PR.