Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Clarify the output rules for the `<substitute>` element #104

Open
cparnot opened this Issue · 2 comments

2 participants

Charles Parnot Rintze M. Zelle
Charles Parnot

This is a follow-up to a discussion on xbiblio-devel with @cparnot, @adam3smith, @rmzelle and @fbennett.

Here is what the current specification for 1.0.1 says:

"The substitutions are specified as child elements of cs:substitute, and must consist of one or more rendering elements (with the exception of cs:layout). A shorthand version of cs:names without child elements, which inherits the attributes values set on the cs:name and cs:et-al child elements of the original cs:names element, may also be used. If cs:substitute contains multiple child elements, the first element to return a non-empty result is used for substitution."

(from http://citationstyles.org/downloads/specification-csl101-20120903.html)

The confusion is in the use of 'child elements', which could be interpreted as either strict children, or more generally descendants. The current implementation of the javascript processor applies the "strict children" rule for <group> child elements, but includes all descendants for <choose> child elements.

Here is an example:

  <substitute>
    <names variable="editor"/>
    <names variable="translator"/>
    <group delimiter="-">
      <text variable="volume"/>
      <text variable="issue"/>
    </group>
    <choose>
      <if type="report">
        <text variable="publisher"/>
        <text macro="title"/>
      </if>
      <else>
        <text macro="title"/>
      </else>
    </choose>
  </substitute>

In the case of a report, the following children will be considered in turn:

    1. <names variable="editor"/>
    2. <names variable="translator"/>
    3. <group delimiter="-">
          <text variable="volume"/>
          <text variable="issue"/>
        </group>
    4. <text variable="publisher"/>
    5. <text macro="title"/>

A "strict child" rule would instead consider the following children:

    1. <names variable="editor"/>
    2. <names variable="translator"/>
    3. <group delimiter="-">
          <text variable="volume"/>
          <text variable="issue"/>
        </group>
    4. <if type="report">
          <text variable="publisher"/>
          <text macro="title"/>
        </if>

The first list is the correct interpretation.

To clarify the specifications and be consistent with the reference implementation, I suggest the following phrasing:

"The substitutions are specified as child elements of cs:substitute, and must consist of one or more rendering elements (with the exception of cs:layout). A shorthand version of cs:names without child elements, which inherits the attributes values set on the cs:name and cs:et-al child elements of the original cs:names element, may also be used. If cs:substitute contains multiple child elements, the first element to return a non-empty result is used for substitution. For child elements that have themselves children, the behavior is dependent on the type of child. For <group> children, the full subtree should be evaluated, and used if the result is not empty. For <choose> children, each descendant under the proper <if> should be evaluated in turn, and the first element to return a non-empty result used for substitution. The same rule is recursively applied to <group> and <choose> child elements."

Charles Parnot

Here is maybe an example that could be substituted (!) to the one in the current spec:

In this example, an empty "author" name variable is first substituted by the "editor" name variable, or else by the "translator" variable. If no editor or translator exist, it is substituted by the "publisher" for report entires, or else by the "title" macro. If all of the above substitutions are empty, we fall back to the last <group> element, which outputs the labels for "anonymous" and "untitled", separated by a comma.

  <substitute>
    <names variable="editor"/>
    <names variable="translator"/>
    <choose>
      <if type="report">
        <text variable="publisher"/>
        <text macro="title"/>
      </if>
      <else>
        <text macro="title"/>
      </else>
    </choose>
    <group delimiter=", ">
      <label text="anonymous"/>
      <label text="untitled"/>
    </group>
  </substitute>
Rintze M. Zelle
Owner

The first list is the correct interpretation.

There is no doubt or disagreement about this being the desired behavior? @adam3smith, @fbennett?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.