Introductions and other supplementary material

[Denis_Maier]

CMoS treats Introductions differently than other chapters. According to https://owl.purdue.edu/owl/research_and_citation/chicago_manual_17th_edition/cmos_formatting_and_style_guide/books.html:

Unlike other citations for books, bibliographic entries of this kind include the page number range for the part cited.

N:

7. Steven Pinker, introduction to What is Your Dangerous Idea? , ed. John Brockman (New York: Harper Perennial, 2007), xxv.

B:

Pinker, Steven. Introduction to What is Your Dangerous Idea?, xxiii-xxxiii. Edited by John Brockman. New York: Harper Perennial, 2007.

Probably again not for CSL 1.1, but perhaps after that.

[Sebastian_Karcher]

Note that the OWL example is actually incorrect. They’re misreading the instructions – the citation should actually be
Pinker, Steven. Introduction to What is Your Dangerous Idea?, edited by John Brockman, xxiii-xxxiii. New York: Harper Perennial, 2007.

(The page range follows the principal creator of the book; it just so happens that the books in the CMoS example have both an author and an editor and that confused OWL).

That said, we indeed can’t get the title right with CSL chapter. But I’m more than a little wary of introducing an item type just for this sort of thing.

[Denis_Maier]

Thanks for your note about the OWL example. Good to know.

Concerning the title formatting, I basically see 4 options:

• Don’t support it
• Support it with an additional item type (or a sub-item type; e.g. chapter-supplementary)
• Support it with a variable that serves as a boolean switch.
• Use some nifty processor logic to find these cases (but that would have to be hard-coded in the processor, and I honestly don’t think it would be a good idea.)

Do you see other ways to achieve the desired result? What speaks against adding a new item type for this?

Again: That’s probably a discussion to be had after CSL 1.1, but anyway… My experience when teaching reference management software is just that say they’d rather create their citations and bibliographies by hand then rely on tools that produce results that are not 100% correct. (By the way, I don’t think it is particularly helpful to make this distinction between normal chapters and introductions, but that wasn’t my design choice.)

[cormacrelf]

Option 5:

• Let people & style authors do whatever they want with first-class, namespaced escape hatches, BUT provide a way that users can be made aware of breaking changes that styles make for people who depend on those escape hatches.

I got all excited about giving styles version numbers a while back, but for the wrong reasons – I had thought reusability of style code was the goal. It isn’t. (I’m such a programmer.) The correct goal is letting people keep creating documents with the same reference library and data-entry conventions while upgrading to new releases of styles.

Say you allowed extensions in a <schema> block, that the processor can validate.

<style style-version="2.3.0" xmlns:chicago="https://citationstyles.org/schema/chicago">
  <schema namespace="chicago">
    <!-- - bool can be checked in a condition
             <if chicago:var="true" />
         - string is a regular variable
             <text variable="chicago:var" />
         - name is a name variable
             <names variable="chicago:var" />
         - date is a date variable
             <date variable="chicago:var" />
         - number is a number variable
             <number variable="chicago:var" /> -->
    <key name="chapter-is-introduction" type="bool" />
    <!-- - enum could be like a CSL type: <if chicago:some-enum="two" /> -->
    <key name="some-enum" type="enum" values="one two three" />
  </schema>
  <citation>
    <layout>
      <choose>
        <if chicago:chapter-is-introduction="true" />
      </choose>
    </layout>
  </citation>
</style>

A researcher with a library full of introductory chapters is using Chicago. She realises these are being formatted incorrectly, and asks @Sebastian_Karcher to improve the style for her. He releases Chicago version 2.3.0 as above, and she puts in her Zotero settings (e.g.) that her library depends on Chicago version range “2.3”, i.e. ^2.3.0 in Node semver notation. Zotero then creates some field UI to edit this.

[{
  "id": "citekey",
  "type": "chapter",
  "title": "What is Your Dangerous Idea?",
  "schema:https://citationstyles.org/schema/chicago": {
    "chapter-is-introduction": true
  }
}]

Version 2.4 might add another key to the schema (a semver ‘feature’); version 2.5 might adopt some CSL spec addition that covers this, but retain backwards compatibility with people who are using the old schema entry; version 3.0.0 (breaking) might stop supporting the schema and only support the official way. Styles should have a changelog, so that researchers who are using one version know what might break or be improved if they were to upgrade.

By validate, I mean emit warnings or errors if a user enters:

{ ..., "schema:some-unsupported-schema": { ...} }
=> info: reference ID "citekey" included properties for "some-unsupported-schema"
   (may not be an error, because e.g. most styles do not treat introductions differently.
    This is an 'include X hacks for chicago' type of deal.)

{ ..., "schema:...": { "some-unsupported-key": "..." } }
=> error: schema "chicago" does not support this key.

{ ..., "schema:...": { "chapter-is-introduction": "some-improperly-typed-value" } }
=> error: schema "chicago" key "..." expected a boolean value, found string

I included namespacing in this concept so that multiple similar styles can share a namespace and the properties within it. That way one library could mostly work across a larger number of styles, e.g. all of the variants of a particular style. But it also means that you don’t have to worry about name collisions with future official variable names in the CSL-JSON input. Just reserve schema:* and you’re good.

Obviously not all of this works very well (esp the sharing of namespaces between styles), but it’s maybe a start. I’m thinking now it would be better for schemas to have a version, and styles to support a version range? Anway, there are my thoughts.

---

PS, <key> could also have for="chapter othertypes", to enforce usage only with a specific set of types.

[Denis_Maier]

Very interesting approach, indeed. Would at least give us much flexibility to deal with arcane demands.

[Sebastian_Karcher]

Do you see other ways to achieve the desired result? What speaks against adding a new item type for this?

No, that about sums it up. My concerns is almost always complexity, especially since CSL is predominantly used by GUI tools. CMoS has almost 300 subsections in chapter 14, many of which are quite ideosyncratic. It’s always been my philosophy (and that of Bruce, who started CSL) that it’s never going to be possible to address every ideosyncracy of every citation style while remaining a useable language.
If someone in the humanities wants 100% accuracy (understood as compliance with style guide) of citation output 100% of the time, I don’t think CSL will be for them and I honestly don’t think we should try to make it so. I’m not willing to sacrifies usability and maintainability for the most exacting 5% of possible(!) users.

So my rule of thumb for added complexity is always: does an addition provide enough benefit given the cost. I look at three things for that:

1. Is there significant demand among end users (mainly judged by the Zotero forums, but obviously taking other channels into account). The answer to this is no for this case. This has very rarely come up.
2. Are there a significant number of style guides of some importance for which this would be relevant. Chicago is obviously a heavy-weight here, so that’s a plus, though if most other styles just handle these as chapters (I haven’t checked) that’d again weigh against adding a custom solution
3. Is there a way to generalize this beyond a very narrow example. I’m just not convinced that building something for just introductions is worth it. If we’d be able to roll this into a broader category that addresses other needs, I’d be more open to it (no idea if that’s possible or not).

[bwiernik]

For this particular case, a simple heuristic might be, “If a chapter has an author and a container-author but no editor, it’s an introduction.” That could be handled with existing style logic.

[Denis_Maier]

I am not so sure here. The examples in the CMoS are actually:

Footnote:
Christopher Hitchens, introduction to Civilisation and Its Discontents, by Sigmund Freud, trans. and ed. James Strachey (New York: W.W. Norton, 2010).

Bibliography:
Mansfield, Harvey, and Delba Winthrop. Introduction to Democracy in America, by Alexis de Tocqueville, xvii-lxxxvi. Translated and edited by Harvey Mansfield and Delba Winthrop. Chicago: University of Chicago Press, 2000.

So we have a chapter with author, container-author, editor and translator, but it should be treated as an introduction nevertheless.

[bwiernik]

Perhaps just “If a chapter has a container-author, it’s an introduction”?

[Denis_Maier]

No. I think Chicago wants this formatting only if it is a generic introduction without a distinct title. @Sebastian_Karcher right?

[bwiernik]

Okay, it sounds like this could be handled with “introduction” being set as medium or genre and title left empty. This is how apa.csl handles things like:

[Photograph of William James]. (1948). http://example.com

But I also agree with Sebastian that this is a quite niche rule (why not just cite it as “Introduction” like any other chapter?). May not be worth bothering with.

[Denis_Maier]

Yes. It is indeed a niche rule, and I would prefer to cite “Introduction” just like any other chapter. But anyway, using genre might be a good way to support this. I’ll see if this could be a solution.

[Denis_Maier]

I guess this is more than a start. The more I think about this the more I like the idea of allowing schema additions. This could possibly solve many problems at once: Keeping CSL core specs simple and maintainable while at the same time giving more options to those who need them. This could be especially useful for certain disciplines with rather special demands, like law, classical philology, biblical studies, film studies, musicology. I don’t think this would necessarily entail convoluted GUIs. It might be reasonable to have users who need this use the extra-Field in Zotero for example. (Of course, the idea that GUI tools could add fields if required by a style sounds intriguing.)

I don’t know how difficult it is to implement this. But if is feasible I am absolutely in favor. @cormacrelf Have you already thought about this?

[cormacrelf]

Have I thought about how easy it is to implement? For me? Pretty easy.

It would need some other things to be successful.

• It would need backpressure. Using a schema addition instead of the ‘standard library’ of variables reduces the portability of people’s references between styles. So its use should be generally discouraged where existing stuff would do the trick. I don’t imagine this stance will be difficult to take for the CSL maintainers, given how easily saying no can be justified!
• It would also need documentation. Not of how to use the feature, but when to use a custom-schemas variable and what it will do, whether it’s deprecated. Essentially you need javadoc/rustdoc-style documentation for each key. Ideally this would be compulsory and pull requests to the styles repo would enforce it. With a deprecated = "for X reason" tag. That GUIs will actually warn you about. That’s the third thing:
• This is a feature for end-users, not style authors. Without GUI support and attention to detail over the experience, the validation capabilities are worthless. “STYLE HAD AN ERROR CODE -4188” is much worse than what we have now. That’s where the actual implementation burden is: with Zotero, that means error codes and translations for UI elements. Building a engine->user warning path would be useful in other ways, however. I would like to be able to bubble up things like “invalid raw date string” and “could not disambiguate”, not only do a best-effort rendering.
• Because it connects end-users to style authors more directly, this might have implications for how people seek support. Are people still going to think to post on the Zotero forums and file GitHub issues if they see docs/text written by individuals? I’m a programmer so I have “find where the source code is hosted, read it, maybe fix it yourself and don’t assume the original author actually has time to deal with your problem individually” drilled into me, not sure if everyone else does.