Options to implement APA narrative citations

[bdarcus]

Time to actually test options, with APA.

Existing v1 approach

The current style fragment:

  <citation et-al-min="3" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year" givenname-disambiguation-rule="primary-name-with-initials">
    <sort>
      <key macro="author-bib" names-min="3" names-use-first="1"/>
      <key macro="date-sort-group"/>
      <key macro="date-sort-date" sort="ascending"/>
      <key variable="status"/>
    </sort>
    <layout prefix="(" suffix=")" delimiter="; ">
      <group delimiter=", ">
        <text macro="author-paren"/> <!-- changing macro name to avoid confusion -->
        <text macro="date-intext"/>
        <text macro="citation-locator"/>
      </group>
    </layout>
  </citation>

For "narrative", the problem here is we need the author macro to render outside of the left paren, but cs:layout assumes everything's inside.

Iterative option

We'd probably need to allow multiple cs:layout elements per cs:citation, and add a cs:mode attribute:

<citation et-al-min="3" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year" givenname-disambiguation-rule="primary-name-with-initials">
  <layout mode="narrative" delimiter=", ">
    <!-- Doe (2005), Smith (2010) have argued ...-->
    <text macro="author-intext"/>
    <group prefix="(" suffix=")" delimiter="; ">
      <group delimiter=", ">
        <text macro="date-intext"/>
        <text macro="citation-locator"/>
      </group>
    </group>
  </layout>
  <layout prefix="(" suffix=")" delimiter="; ">
    <group delimiter=", ">
      <text macro="author-paren"/>
      <text macro="date-intext"/>
      <text macro="citation-locator"/>
    </group>
  </layout>
</citation>

Or alternately, one could use a cs:choose to wrap the layout details.

<citation et-al-min="3" et-al-use-first="1" disambiguate-add-year-suffix="true" disambiguate-add-names="true" disambiguate-add-givenname="true" collapse="year" givenname-disambiguation-rule="primary-name-with-initials">
  <choose>
    <if mode="narrative">
      <layout delimiter=", ">
        <!-- Doe (2005), Smith (2010) have argued ...-->
        <text macro="author-intext"/>
        <group prefix="(" suffix=")" delimiter="; ">
          <group delimiter=", ">
            <text macro="date-intext"/>
            <text macro="citation-locator"/>
          </group>
        </group>
      </layout>
    </if>
    <else>
      <layout prefix="(" suffix=")" delimiter="; ">
        <group delimiter=", ">
          <text macro="author-paren"/>
          <text macro="date-intext"/>
          <text macro="citation-locator"/>
        </group>
      </layout>
    </else>
  </choose>
</citation>

Breaking solution

This is an option least trying to preserve existing styles.

  <!-- 
Combine layout and group into list.
-->
<citation>
  <!-- remove attribute parameters above, and place where they belong -->
  <list type="citation" delimiter=", "
    sort-template="apa-author-year"
    group-template="apa-author-year">
    <!-- 
        do sorting and grouping of lists using templates (or transforms?) 
        not sure this would work as is, particularly grouping, but worth considering
    -->
    <if mode="in-text">
      <text template="author-intext"/>
      <!-- author list shortening would use transforms on that template list-->
      <list type="item" prefix="(" suffix=")">
          <text template="date-intext"/>
          <text template="citation-locator"/>
      </list>
    </if>
    <else>
      <list type="citation" prefix="(" suffix=")" delimiter="; ">
        <list type="item" delimiter=", ">
          <text template="author-paren"/>
          <text template="date-intext"/>
          <text template="citation-locator"/>
        </list>
      </list>
    </else>
  </list>
</citation>

Here things are handled with common list and text render elements, and processing configured using transforms and a similar idea of sort named operations.

The basic idea is we'd package somehow what we already know, but then leave it open.

Still not sure this is worth the hassle, but it offers a stark contrast.

[denismaier]

I'll have to take a closer look. In general, I'd say this looks fine. Just one clarification: this is not really 1.1. as it looks currently, but rather the multiple modes version we've been thinking about.

[bdarcus]

It's 1.1 in the sense that I started with the existing (actually 1.0) style, and in the case of option C, only added the one attribute.

[denismaier]

ok

[bdarcus]

We could have a rule going forward, maybe, on what processors should do when they don't understand a conditional attribute (like, consider it nil)?

We could even, now that I think about it, have a new namespace for new attributes, though not clear on the cost/benefit of that.

~PS - I forgot to add cs:choose!~ corrected for C

[bdarcus]

I've added what I think is the best "iterative" version (C) to the the repo, with a commentary at the top.

https://github.com/bdarcus/csl-next/blob/main/examples/citation-v1-mod.xml

https://github.com/bdarcus/csl-next/blob/08b576e47f011da44b0ce98b18f047d46e4c19b4/examples/citation-v1-mod.xml#L19-L37

Not sure yet how to do it better with a new model. I actually like this one pretty well.

But of note: this is just one feature.

[denismaier]

Problem with C: Usually we use layout to specify delimiters between items. In this example this won't work. But it could if mode was a direct child of citation, and layout a child of mode. Or perhaps add @mode to layout?

<citation>
  <layout mode="in-text" delimiter=", ">
    <!-- Doe (2005), Smith (2010) have argued ...-->
    <text macro="author-intext"/>
    <group prefix="(" suffix=")" delimiter="; ">
      <group delimiter=", ">
        <text macro="date-intext"/>
        <text macro="citation-locator"/>
      </group>
    </group>
  </layout>
  <layout prefix="(" suffix=")" delimiter="; ">
    <group delimiter=", ">
      <text macro="author-paren"/>
      <text macro="date-intext"/>
      <text macro="citation-locator"/>
    </group>
  </layout>
</citation>

[denismaier]

If we wanted, we could make this even more bibtex like, i.e., should one layout be able to call another layout?

<layout mode="in-text" delimiter=", "> <!-- Doe (2005), Smith (2010) have argued ...-->
     <text macro="author-intext"/>
        <group prefix="(" suffix=")" delimiter="; ">
          <group delimiter=", ">
            <text macro="date-intext"/>
            <text macro="citation-locator"/>
          </group>
        </group>
      </layout>
      <layout mode="plain">
          <group delimiter=", ">
            <text macro="author-intext"/>
            <text macro="date-intext"/>
            <text macro="citation-locator"/>
          </group>
  </layout>
  <layout mode="default" prefix="(" suffix=")">
          <text layout="plain"
  </layout>
</citation>

[bdarcus]

Doe (2005), Smith (2010) have argued

Oh, I hadn't even thought about that rendering, but that is in retrospect I guess obvious!

EDIT: but what if someone wants the below??

Doe (2005), Smith (2010) and Jones (2020) have argued

I edited the example a bit for correctness and formatting.

Will need to think on this more!

PS - Had earlier been thinking Doe (2005; Smith 2010).

[denismaier]

EDIT: but what if someone wants the below??

Doe (2005), Smith (2010) and Jones (2020) have argued

Yes, we will need to cover this. Perhaps something similar to the name delimiters.

[denismaier]

PS - Had earlier been thinking Doe (2005; Smith 2010).

Yes that might also be a case to be covered. I think in biblatex you have to asrmble that format yourself using some low level commands

[bdarcus]

Problem with C: Usually we use layout to specify delimiters between items.

And in practice the difference between it and cs:group, which also has delimiter?

Like, was you saying C "won't work" because we were making different assumptions about output, and I'm maybe a little tired?

[denismaier]

And in practice the difference between it and cs:group, which also has delimiter?

Delimiters on group is related to the rendered child elements. Delimiter on layout relates to different items.

[bdarcus]

I guess to be more specific, we'd say cs:layout specifies how to format a group of citation-reference or bibliography-reference objects/items, and cs:group to the variables that describe those objects/items?

They both deal with lists though.

I'm trying to be more precise here than we might have been when first designing all that, in part to think through how sound and consistent it all is.

[denismaier]

I guess to be more specific, we'd say cs:layout specifies how to format a group of citation-reference or bibliography-reference objects/items, and cs:group to the variables that describe those objects/items?

~I'm not sure this is correct. cs:group specifies the varialbes for a single item, cs:layout also specifies the rendering of a single item, but delimiter on cs:layout specifies the delimiter between items.~

• ~cs:group: variables of a single item~
• ~cs:layout: ~
  • ~child elements and most attributes: variables of a single item~
  • ~delimiter: group of items~

[bdarcus]

That seems like an inconsistency then.

Or perhaps we may be saying the same thing?

Clearly the children of layout describe the item formatting, but the parent itself only refers to how to format the list as a whole?

  <layout prefix="(" suffix=")" delimiter="; ">

The affixes are wrapping the list, and the delimiter saying what to put between its members?

That's what I was meaning.

Sort of like in lisp (or join methods or functions in almost any language):

ELISP> (string-join (list "one" "two" "three") "; ")
"one; two; three"

So an alternate way to represent it might be:

      <list type="citation" prefix="(" suffix=")" delimiter="; ">
        <list type="item" delimiter=", ">
          <text template="author-paren"/>
          <text template="date-intext"/>
          <text template="citation-locator"/>
        </list>
      </list>

[denismaier]

Ignore my last comment. I've mixed attributes on cs:layout up with attributes on cs:citation.

Treating this as a list makes sense though.

[bdarcus]

Alright, I modified the original post to do away with my examples, and have two variants of one of your's (I don't know what I think of the other one ATM).

I also added a "breaking" example, which is pretty extreme (and not fully thought-out), just to demonstrate the contrast.

[denismaier]

Shouldn't the list element under citation moved to under if?

[bdarcus]

Yes; fixed.

[bdarcus]

Realizing if we merged into a common list element, we could generalize the default transform attributes.

    <template name="apa-authors">
      <list members="contributors"
        shorten-min="3"
        shorten-use="1"
        and-as="symbol">
    <!-- TODO -->
    <render variable="author"/>
      </list>
    </template>

[bdarcus]

And playing here with a more explicit modeling of what is sometimes implicit in CSL 1; here we have nested author year groups within a citation list.

<!-- parenthetical author-date citation -->
<list type=”citation” group-by=”author” prefix=”(“ suffix=”)” separator="; ">
  <render variable=”author” suffix=", "/>
  <list group-by “year”>
    <render variable=”issued” transform=”date.year”/>
    <render variable=”issued” transform=”date.year.suffix”/>
  </list>
</list>

And the narrative alternative.

<!-- narrative author-date citation -->
<list type=”citation” group-by=”author” separator=", " and-as="text">
  <render variable=”author” suffix=", "/>
  <list group-by=“year” prefix="(" suffix=")">
    <render variable=”issued” transform=”date.year”/>
    <render variable=”issued” transform=”date.year.suffix”/>
  </list>
</list>

Don't even really need the list type attribute there probably.

And the generic approach offers a lot of flexibility; for example, different kinds of bibliography formatting:

<list group-by="author">
  <render format="block-heading" variable="author"/>

Or maybe better the simple SQL-like grouping solution, though maybe not as flexible on the formatting.

<list type=”citation” group-by=”author year” prefix=”(“ suffix=”)” separator="; ">
  <!-- borrow group-by idea from SQL -->
  <render variable=”author” suffix=", "/>
  <render variable=”issued” transform=”date.year”/>
  <render variable=”issued” transform=”date.year.suffix”/>
</list>

PS - ~I created a separate "pure" branch to experiment with a more radical simplification.~ I merged it; may as well keep this clean and clear, even if it doesn't go anywhere.

[bdarcus]

Closing this; current version is good enough to evaluate.

[bdarcus]

Can we go back to this example, @denismaier, because I'm confusing myself.

What's the difference between these two examples?

Doe (2005, 2006), Smith (2010) and Jones (2020) have argued
(Doe 2005, 2006; Smith, 2010; and Jones, 2020 have argued

Am I interpreting this right that they both are sorted and grouped the same: first author, then year?

And the only difference is that the affixes in the first are applied to the inner group, rather than the outer? Well, and the delimiters.

So then like this?

citation:
  format:
    - when:
        - mode: narrative
          format:
            - groupBy: cs-author
              delimiter: ", "
              andAs: symbol
              format:
                - groupBy: cs-year
                  prefix: (
                  suffix: )
                  format:
                    - variable: issued
      else:
        - groupBy: cs-author-year # not sure this grouping is right
          prefix: (
          suffix: )
          delimiter: "; "
          format:
            - template: author-apa
            - variable: issued

[bdarcus]

That's mostly correct, and shows the flexibility, but may be confusing. I'm wondering if there might be a way to offer some syntactic sugar for certain kinds of conditions?

Maybe we could define two kinds of conditions somehow, so maybe could do something like the below?

Only makes sense if we can clearly distinguish locale and mode from the other kinds of conditions?

Maybe, in effect, both are kinds of modes??

citation:
  - mode:
      - locale: es
      - citation: narrative
    format:
      ...

I created an issue at the other repo for this.

https://github.com/bdarcus/csl-next.js/issues/13