Mc  Gill-style citations for Pollen
1 Example
2 User/  author tags
declare-work
cite
3 Integration with your Pollen tags
7.9

McGill-style citations for Pollen

Sancho McCann

 (require pollen/citations-mcgill)
  package: pollen-citations-mcgill

This module provides McGill-style citation management for use with the Pollen module. pollen-citations-mcgill lets you:

This requires the end-user/author to use declare-work within their Pollen source code. It requires your Pollen project (in your "pollen.rkt" file, usually) to call two transformer functions (provided by this module). This is in order that this module be able to manage reference tracking and back-references for any citations that are rendered within that footnote context.

1 Example

You can see this working at https://github.com/sanchom/sanchom.github.io. "down-the-foxhole.html.pm" is a good example of declaring the works and using them later within notes. "pollen.rkt" demonstrates the required integration calls described in Integration with your Pollen tags.

I’m also using it for the project at https://github.com/sanchom/associate.

There is also an online demo that you can play with at https://citations-demo.herokuapp.com/.

2 User/author tags

These are tags/functions that the ultimate author of a document will use in their source text.

You need to provide them through your "pollen.rkt" like this:

(provide declare-work)
(provide cite)

procedure

(declare-work #:type type 
  #:id id 
  [#:title title 
  #:author author 
  #:author-institutional author-insitutional 
  #:author-given author-given 
  #:author-family author-family 
  #:author2-given author2-given 
  #:author2-family author2-family 
  #:author3-given author3-given 
  #:author3-family author3-family 
  #:editors? editors? 
  #:etal? edit? 
  #:in-book in-book 
  #:journal journal 
  #:edition edition 
  #:year year 
  #:date date 
  #:volume volume 
  #:issue issue 
  #:publication publication 
  #:citation citation 
  #:parallel-citation parallel-citation 
  #:jurisdiction jurisdiction 
  #:case-judge case-judge 
  #:institution institution 
  #:legislative-body legislative-body 
  #:number number 
  #:chapter chapter 
  #:reading reading 
  #:bill-status bill-status 
  #:eventual-statute eventual-statute 
  #:proceedings proceedings 
  #:publisher publisher 
  #:publisher-location publisher-location 
  #:thesis-description thesis-description 
  #:description description 
  #:comment-info comment-info 
  #:forthcoming forthcoming 
  #:pages pages 
  #:first-page first-page 
  #:url url 
  #:display-url? display-url? 
  #:custom-format custom-format 
  #:short-form short-form 
  #:cited-to cited-to]) 
  void?
  type : string?
  id : string?
  title : (or/c string? #f) = #f
  author : (or/c string? #f) = #f
  author-insitutional : (or/c string? #f) = #f
  author-given : (or/c string? #f) = #f
  author-family : (or/c string? #f) = #f
  author2-given : (or/c string? #f) = #f
  author2-family : (or/c string? #f) = #f
  author3-given : (or/c string? #f) = #f
  author3-family : (or/c string? #f) = #f
  editors? : string? = ""
  edit? : string? = ""
  in-book : (or/c string? #f) = #f
  journal : (or/c string? #f) = #f
  edition : (or/c string? #f) = #f
  year : (or/c string? #f) = #f
  date : (or/c string? #f) = #f
  volume : (or/c string? #f) = #f
  issue : (or/c string? #f) = #f
  publication : (or/c string? #f) = #f
  citation : (or/c string? #f) = #f
  parallel-citation : (or/c string? #f) = #f
  jurisdiction : (or/c string? #f) = #f
  case-judge : (or/c string? #f) = #f
  institution : (or/c string? #f) = #f
  legislative-body : (or/c string? #f) = #f
  number : (or/c string? #f) = #f
  chapter : (or/c string? #f) = #f
  reading : (or/c string? #f) = #f
  bill-status : (or/c string? #f) = #f
  eventual-statute : (or/c string? #f) = #f
  proceedings : (or/c string? #f) = #f
  publisher : (or/c string? #f) = #f
  publisher-location : (or/c string? #f) = #f
  thesis-description : (or/c string? #f) = #f
  description : (or/c string? #f) = #f
  comment-info : (or/c string? #f) = #f
  forthcoming : (or/c string? #f) = #f
  pages : (or/c string? #f) = #f
  first-page : (or/c string? #f) = #f
  url : (or/c string? #f) = #f
  display-url? : string? = ""
  custom-format : (or/c string? #f) = #f
  short-form : (or/c string? #f) = #f
  cited-to : (or/c string? #f) = #f
The id is the string that users/authors can use to cite this work using cite.

type must be one of "article", "chapter", "book", "thesis", "proceedings", "unpublished", "legal-case", "legal-case-US", "bill", "statute", "regulation", "debate", "book", "magazine/news", or "custom".

Depending on the type of the work, the subsequent fields that are meaningful or mandatory will differ. For example, if type is "thesis", then thesis-description is actually meaningful. If type is "legal-case", then citation is mandatory. Some fields are incompatible with each other. For example, if author is specified, then author-given and author-family are automatically extracted and must not also be specified (and vice versa). These various restrictions are best presented through examples, which are presented next.

And if none of these are adequate, you can always fall back to a custom citation format, but this requires you to lay out the citation yourself using the custom-format argument. This takes a string optionally marked up with italicized sections (by surrounding them with asterisks).

Specifying authors

The way to declare an author or authors is the same across all document types. You can declare an author’s given and family name explicitly:

◊declare-work[#:id "Mills" #:type "article"
              #:author-given "Aaron" #:author-family "Mills"
              ...]

Or, for the first author, if they only have two parts to their name, you can use #:author as shorthand. The system will assume the first name is the given name and that the second name is the family name.

◊declare-work[#:id "Mills" #:type "article"
              #:author "Aaron Mills"
              ...]

For additional authors (up to three), you have to list them like this:

◊declare-work[#:id "FSP" #:type "magazine/news"
              #:author "Jennifer Daskal"
              #:author2-given "Danielle Keats" #:author2-family "Citron"
              #:author3-given "Nathaniel" #:author3-family "Gleicher"
              ...]

If there are more than three authors, McGill style only lists the first, followed by et al. You can tell the citation system to use et al like this:

◊declare-work[#:id "Lazer" #:type "article"
              #:author-given "David MJ"
              #:author-family "Lazer" #:etal? "yes"
              ...]

If the string argument to #:etal is any kind of affirmative string (e.g. "yes", "T", "t", "#t", "YeS"), the system will interpret it as a "yes", otherwise, it will interpret it as a "no".

If the people you have listed using the author arguments are actually editors, use the #:editors? argument, and provide an affirmative string.

In place of a person, you can also specify an institutional author:

◊declare-work[#:id "FB" #:type "magazine/news"
              #:author-institutional "Facebook"
              ...]

article

Author(s), a title, and a journal name are mandatory.

E.g.:

◊declare-work[#:id "DiResta" #:type "article"
              #:author "Renee DiResta"
              #:title "Computational Propaganda: If You Make it Trend, You Make it True"
              #:journal "The Yale Review"
              #:volume "106" #:issue "4"
              #:first-page "12" #:year "2018"]

book

Title and year are mandatory.

E.g.:

◊declare-work[#:id "Bilewicz" #:type "book"
              #:author "Michal Bilewicz"
              #:author2-given "Aleksandra" #:author2-family "Cichocka"
              #:author3-given "Wiktor" #:author3-family "Soral"
              #:editors? "yes"
              #:title "The Psychology of Conspiracy"
              #:year "2015" #:publisher "Routledge"
              #:publisher-location "New York"]

chapter

Title, in-book (a reference to a book that has also been declared), and first-page are mandatory.

E.g.:

◊declare-work[#:id "Douglas: Chapter" #:type "chapter"
              #:author-given "Karen M" #:author-family "Douglas"
              #:etal? "yes"
              #:title "The Social, Political, Environmental, and
                       Health-Related Consequences of Conspiracy Theories"
              #:in-book "Bilewicz" #:first-page "183"]

legal-case

This is for citing Canadian legal cases. The title (style of cause) and citation elements are mandatory. If the year is not the first thing to appear in the citation string, you must also explicitly include the year.

E.g. (showing a simple citation using a neutral citation, and a specified short-form; in short-forms, the asterisks signify that it is to be rendered italicized):

◊declare-work[#:id "Maltz" #:type "legal-case"
              #:title "Maltz v Witterick"
              #:citation "2016 FC 524" #:short-form "*Maltz*"]

E.g. (showing a parallel citation and explicit jurisdiction information because the citations don’t reveal the jurisdiction and court):

◊declare-work[#:id "Delrina ONCJ" #:type "legal-case"
              #:title "Delrina Corp v Triolet Systems Inc"
              #:citation "[1993] OJ No 319"
              #:parallel-citation "47 CPR (3d) 1"
              #:jurisdiction "ON Ct J (Gen Div)"]

E.g. (explicitly declaring the year because it isn’t the first part of the citation):

◊declare-work[#:id "Delrina" #:type "legal-case"
              #:title "Delrina Corp v Triolet Systems Inc"
              #:citation "58 OR (3d) 339"
              #:jurisdiction "ON CA"
              #:year "2002"
              #:short-form "*Delrina*"]

The system will automatically format the jurisdiction according to McGill rules, removing the space between all-uppercase jurisdiction strings.

legal-case-US

The title (style of cause), citation, and year elements are mandatory. Jurisdiction will also usually be provided unless citing the Supreme Court through the ◊emph{United States Reports}.

E.g.:

◊declare-work[#:id "Titanic" #:type "legal-case-US"
              #:title "Lindsay v The Wrecked and Abandoned Vessel RMS Titanic"
              #:citation "52 USPQ (2d) 1609"
              #:year "1999" #:jurisdiction "SDNY"
              #:short-form "*Lindsay v RMS Titanic*"]

magazine/news

The only mandatory element for this is the title. This citation format can also be used for general website citation.

E.g.:

◊declare-work[#:id "Serhan" #:type "magazine/news"
              #:title "The Case Against Waging 'war' on the Coronavirus"
              #:author "Yasmeen Serhan"
              #:date "31 March 2020"
              #:publication "The Atlantic"]

It’s common to specify a URL when you are citing an online news source or website. If you want the URL to be displayed in the citation as per a standard McGill URL reference, use the #:display-url? element. If you provide a URL and don’t use #:display-url?, then the title will merely be turned into a hyperlink. This might be all you want if you’re rendering the citation on a blog.

◊declare-work[#:id "FSP" #:type "magazine/news"
              #:author "Jennifer Daskal"
              #:author2-given "Danielle Keats" #:author2-family "Citron"
              #:author3-given "Nathaniel" #:author3-family "Gleicher"
              #:publication "New America"
              #:title "Free Speech Project: Confronting Viral Disinformation"
              #:date "26 March 2020"
              #:url "https://youtu.be/a6hFwYxUSxM" #:display-url? "yes"]

statute

This is a citation to a published statute (as opposed to a bill). You can use this to cite to either Annual Statutes of Canada or Revised Statutes. The title, volume, year, and chapter are mandatory elements. Volume is the name of the statute publication (e.g. RSC, SC, RSBC).

E.g.:

◊declare-work[#:id "CC" #:type "statute"
              #:title "Criminal Code"
              #:volume "RSC" #:year "1985" #:chapter "C-46"]
 
◊declare-work[#:id "C-25" #:type "statute"
              #:title "An Act to amend the Criminal Code, the Youth Criminal Justice Act
                       and other Acts and to make consequential amendments to other Acts"
              #:volume "SC" #:year "2019" #:chapter "25"]

bill

The bill number, title, legislative-body, and year are mandatory elements.

E.g. (note, this example also shows a user-specified short-form with a mix of italics and roman text):

◊declare-work[#:id "BC PPPA" #:type "bill"
              #:number "2"
              #:title "Protection of Public Participation Act"
              #:legislative-body "4th Sess, 41st Leg, British Columbia"
              #:year "2019"
              #:url "https://www.leg.bc.ca/content/data%20-%20ldp/Pages/41st4th/1st_read/gov02-1.htm"
              #:short-form "BC *PPPA*"]

regulation

debate

thesis

proceedings

unpublished

custom

The custom type lets you specify a citation that doesn’t fit neatly into any of the provided categories. This citation system will still manage back-references, using ibid, supra, and short-forms. It’s just that you will specify the layout of the initial citation.

E.g.:

◊declare-work[#:id "Charter" #:type "custom"
              #:custom-format "*Canadian Charter of Rights and Freedoms*[[pinpoint]],
                               Part I of the *Constitution Act, 1982*, being Schedule B to the
                               *Canada Act 1982* (UK), 1982, c 11"
              #:short-form "*Charter*"]

In the custom format, surround text that should appear italicized in asterisks. Indicate the position for pinpoints using the [[pinpoint]] markup.

procedure

(cite id    
  [#:pinpoint pinpoint    
  #:parenthetical parenthetical    
  #:judge judge    
  #:speaker speaker    
  #:signal signal    
  #:terminal terminal])  txexpr?
  id : string?
  pinpoint : (or/c string? #f) = #f
  parenthetical : (or/c string? #f) = #f
  judge : (or/c string? #f) = #f
  speaker : (or/c string? #f) = #f
  signal : (or/c string? #f) = #f
  terminal : string? = "."
Produces a txexpr with a formatted citation. The content of the citation is that which was provided via declare-work, supplemented by the specific arguments in the call to cite.

pinpoint needs to be something like "page 6", "at para 1", "clause 7", etc.

parenthetical is a short quote or explanation no longer than one sentence.

judge is the name of the judge.

speaker is the name of the speaker in the case of a legislative debate or other transcript.

signal is an introductory signal to prepend to the citation ("See", "See also", "See generally", etc.)

You can change the terminal to end the citation in something other than a "." A common alternative is ";" in order to join multiple citations together in a single footnote signal as described at McGill 1.3.4.

Only when a call to cite is within your Pollen system’s note-tag context will the resulting citation be fully managed by this citation system. If you call cite just inline in a paragraph, this citation system will just leave you a formatted citation in place. Such a citation will not affect reference counting and will not be subject to transformation into back-references.

3 Integration with your Pollen tags

This citation system assumes/requires that you define some sort of a "note" tag within which citations are treated specially (that is, managed by this citation system).

You can name that tag whatever you want. For example, if you name that tag note, the end-user/author would need to write:

◊note{Here is a cited work within a note context. ◊cite["id-string"]}

All citations that the end-user/author places within your note context will be managed by this citation system, but only if you do the following extra work within your note tag and during the final decode.

First, your note tag is responsible for counting the footnote number. One way of doing this is through a global variable in your "pollen.rkt" that is mutated upon each call to note.

Second, transform the entire content of the note with the following code:

(define transformed-content
  (decode-elements content
                   #:txexpr-proc (λ (x) (transform-cite-in-a-note x footnote-number))))

The resulting transformed-content is what you should actually show the user (in a sidenote, footnote, inline pop-up, or however you’ve decided to use your note tag).

Third, during the final decode, provide the show-necessary-short-forms function as an argument to decode via #:txexpr-proc:

(decode ...
 #:txexpr-proc (compose1 custom-hyphenation show-necessary-short-forms))