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

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. It lets you:

This requires the end-user/author to use declare-work within their Pollen source code. It requires your Pollen project 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.

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 format-work)
(provide cite)

procedure

(declare-work #:type type    
  #:id id    
  [#:title title    
  #:author author    
  #:author-given author-given    
  #:author-family author-family    
  #:author2-given author2-given    
  #:author2-family author2-family    
  #:author3-given author3-given    
  #:author3-family author3-family    
  #:journal journal    
  #:year year    
  #:date date    
  #:volume volume    
  #:publication publication    
  #:issue issue    
  #: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    
  #: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-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
  journal : (or/c string? #f) = #f
  year : (or/c string? #f) = #f
  date : (or/c string? #f) = #f
  volume : (or/c string? #f) = #f
  publication : (or/c string? #f) = #f
  issue : (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
  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", "thesis", "proceedings", "unpublished", "legal-case", "legal-case-US", "bill", "statute", "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 must not also be specified (and vice versa). These various restrictions are best presented through examples.

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).

[TODO: document what fields are meaningful for each type of work.]

procedure

(format-work #:type type    
  [#:title title    
  #:author author    
  #:author-given author-given    
  #:author-family author-family    
  #:author2-given author2-given    
  #:author2-family author2-family    
  #:author3-given author3-given    
  #:author3-family author3-family    
  #:journal journal    
  #:year year    
  #:date date    
  #:volume volume    
  #:publication publication    
  #:issue issue    
  #: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    
  #:custom-format custom-format    
  #:short-form short-form])  txexpr?
  type : string?
  title : (or/c string? #f) = #f
  author : (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
  journal : (or/c string? #f) = #f
  year : (or/c string? #f) = #f
  date : (or/c string? #f) = #f
  volume : (or/c string? #f) = #f
  publication : (or/c string? #f) = #f
  issue : (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
  custom-format : (or/c string? #f) = #f
  short-form : (or/c string? #f) = #f
Takes the exact same arguments as declare-work, with the exception of id. This function does not accept an id. Instead of making the work available for later citing, this function just returns a formatted citation in a txexpr.

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 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))