Understanding APA References with railroad diagrams

Lately in college, I've been learning about the APA style and, of course, APA citations. I've actually used those for a while now, but every single time I've made a reference, I've had to browse through APA's mind-numbingly-many examples just to figure out what I'm supposed to do.

And the programmer in me loathes that. After all, if there were some rules and principles underlying the whole thing, couldn't I just memorize those, like for any other convention out there? Also, where is the direct and to-the-point explanation of the syntax, similar the ones we have for programming languages? Like, there is a short reference, but it's still just examples, no rules. Are we to always depend on the examples, never understanding why things are the way they are?

Well, turns out, there are principles underlying the whole thing. And, better yet, we can even capture them on a railroad diagram—like the cool diagrams from JSON.org, except hairier! What follows is my attempt to do just that.

The principles

First, let's consider the purpose. A reference serves to show where an idea comes from—to present a citation. For it to work effectively, it's split in two parts. One is the reference list entry, which contains detailed information about the exact source and how one can find it. The other is the in-text citation, which is points to the reference list entry, and is somewhere in the text. Every reference style will have to have some way to write those out, and for the rest of this article we will be considering the APA style.

As far as APA is concerned, a reference consists of the following elements (as their documentation will readily tell you):

• Author (Who wrote it?)
• Date (When was it published?)
• Title (What's it called?)
• Source (Where can the reader find it?)
• Page number (Which part of it exactly?)

If you don't have an author, you move the title to the author's place. If you don't have a date, you write "n.d.". If you don't have a title, you omit that and write a description in brackets. If you don't have a page number, you use a paragraph number or also omit that. If you don't have a source, you are... out of luck (as the whole point of a citation is to cite a source), unless it is personal communication with someone, in which case there is a separate style for writing that.

Past that, writing the citation itself is only a matter of syntax, of methodologically placing all the things in the right places with the right formatting... which, as a programmer, I find to be the easier part, hence the diagrams.

In-text citations

In-text citations are written right next to your quotation or paraphrase in the body of the paper. The main principle about them is brevity. We want each in-text citation to be short, yet informative enough that we can find it in the reference list later. In APA, we don't use numbers for references (which would be shorter), but instead list the author, date, and, optionally page—all of them in parenthesis and separated by commas.

When you write an in-text citation you ideally want to write only the things that you don't already have in the text. This results in the so-called "narrative citation". If you instead list everything, it is a "parenthetical citation". As we want brevity, the author is kept only to a last name, and the date is only the year—unless that leads to ambiguity, in which case there are extra rules.

Reference citations

After the body of a paper comes the notorious reference list. The main principle here is being specific, and fully describing the reference. In addition, we also want to keep the list easy to search.

For reference list entries, in APA, we list the author, date, title, and, crucially, the source. This time around, between the elements, we have periods—unless one of them ends with e.g. a quotation mark, in which case we skip the extra dot.

Here, the author name lists initials as well. For easier searching by last name (as that's what we have in the in-text citation), the the last name is written first, and everything is in alphabetical order. The date is written inside parenthesis. Title is written out in sentence-case, with original punctuation.

Yet, the vast majority of the complexity of a reference list entry lies in properly styling the source. Generally, it consists of a publisher's name or a website's name (unless they are also the author, in which case we omit that) followed by a URL where the work can be accessed.
However, when the source is part of a periodical, we have some extra syntax used to specify the volume (italics), issue (inside parenthesis), and page numbers (with a dash) in a conventional way. This can be observed in the diagram below.
In addition, there is a thing called edited chapters / edited volumes. I haven't seen any uses of those yet, but they still make for the majority of odd exceptions to the general citation syntax. If you ever need to use one, I would suggest checking the relevant examples, even if they are present in the diagram below.

Something else that tripped me up at first is deciding whether the title or the source should be written in italics. Turns out, there is a rule for that: italics are used for the element that is a stand-alone work. A stand-alone work would be something like a book or a journal, that then contains smaller parts, like chapters or articles that only make sense within it. So, a book title, is in italics, but the chapter titles are not; scientific journals and newspapers are stand-alone, but the articles inside are not; and so on. Just note that webpages can be either stand-alone or not depending on the circumstances; webpages are considered stand-alone when they are individual articles not part of a periodical; but as soon as they become part of a blog or online newspaper, then the blog/newspaper is the stand-alone work, and not the article.

Conclusion

When I first encountered APA citations, I remember looking up "APA railroad diagram" and "APA diagrams" and finding nothing—nothing!—like it on the Internet. Hence, I set out to diagram APA citations mainly for myself, both to prove that they can be diagrammed and as a way to learn the APA style. I wish I had an article like this, and I hope it will be there to help the next person who searches for that same term.

Personally, I find APA's official style guidelines website somewhat hard to parse. I think it is because of the lack of an at-a-glace page that summarizes all the main parts of the style and perhaps even spells out the general principles that guided the stylists in drafting the rest of the guidelines. Perhaps, the above explanation and diagrams might help fill that void a bit.

Extras: Combined image of the diagrams

Here you can find all the diagrams from this page in one image. You can right click or long press to save the image or open it in a new tab.

// SPDX-License-Identifier: CC-BY-4.0
let ZeroStart = (x) => { x = rr.Start(x); x.width = 20; return x; };
let OptionalAlt = (x, skip=Skip()) => rr.Choice(0, x, skip);

let dPostcard = Diagram(ZeroStart({label: 'APA references overview'}),
  Stack(
    Sequence(Comment('In-text citation:'), 
      '(',
        Choice(0, NonTerminal('Author,'), Comment('(narrrative)')),
        Choice(0, NonTerminal('Year,'), 'n.d.,'),
        Choice(0, NonTerminal('p. Page'), Comment('(narrrative)')),
      ')', '.',
      Comment('...points to...'),
    ),
    Sequence(Comment('Reference list entry:'),
      Sequence(
        Choice(0,
          Sequence(
            NonTerminal('Author, I.'),
            NonTerminal('(Date).'),
            NonTerminal('Title.'),
          ),
          Sequence(
            Comment('(no author)'),
            NonTerminal('Title.'),
            NonTerminal('(Date).'),
          ),
        ),
        Sequence(
          Choice(0,
            Sequence(NonTerminal('Source.'), Comment('(italics on standalone)')),
            Sequence(NonTerminal('Periodical, Vol(Is), P–P.')),
          ),
          Choice(1, Skip(), NonTerminal('URL'), NonTerminal('doi')),
        ),
      ),
    )
  )
)

let dIntext = Diagram(ZeroStart({label: 'APA In-text'}),
  '(',
  OneOrMore(Choice(0,
    Sequence(
      Group(Choice(0,
        Comment('(in narrative)'),
        // Sequence(NonTerminal('Lastname')), Sequence(NonTerminal('Lastname'), '&', NonTerminal('Lastname')), Sequence(NonTerminal('Lastname'), 'et al.'),
        Sequence(NonTerminal('Lastname'), Choice(0, Skip(), Sequence('&', NonTerminal('Lastname')), 'et al.')),
        Sequence(NonTerminal('Organization')),
        Sequence(Comment('(no author)'), NonTerminal('Title'))
      ), 'Author'),
      Choice(0, ',', Skip()),
      Group(Choice(0, Comment('(narrative)'), Sequence(NonTerminal('Year')), 'n.d.'), 'Date'),
      Choice(0, ',', Skip()),
      Group(Choice(0, Comment('(no page)'), Sequence('p.', NonTerminal('Page')), Sequence('pp.', NonTerminal('P'), '–', NonTerminal('P'))), 'Page'),
    ),
    Group(Sequence(
      Choice(0, Comment('(narrative)'), Sequence(NonTerminal('I. I. Lastname'))),
      Choice(0, ',', Skip()),
      'personal communication',
      ',',
      Choice(0, Sequence(NonTerminal('Month'), NonTerminal('Day'), ',', NonTerminal('Year'))),
    ), 'Personal communication'),
  ), Sequence(';', Comment('(multiple citations)'))),
  ')',
  Comment('...'),
  '.'
);

let dReference = Diagram(ZeroStart({label: 'APA Reference'}),
  Stack(
    Choice(0,
      Stack(
        Group(Choice(0,
          Sequence(Optional(Sequence(OneOrMore(NonTerminal('Lastname, I.'), ','), '&')), NonTerminal('Lastname, I.')), Sequence(NonTerminal('Organization'), '.')   
        ), 'Author'),
        Group(Sequence(
          '(',
          Choice(0,
            Sequence(Choice(1, 'ca.', Skip()), NonTerminal('Year'), Choice(1, Sequence(',', NonTerminal('Month'), OptionalAlt(NonTerminal('Day'))), Skip())),
            'in press',
            'n.d.'
          ),
          ')',
          '.',
        ), 'Date'),
        Group(Sequence(
          Choice(0,
            Sequence(NonTerminal('Part title'), Comment('(in "Sentence case")')),
            Sequence(Comment('<em>'), NonTerminal('Standalone title'), Comment('</em>')),
            Comment('(missing title)'),
          ),
          Choice(0, Comment('(no ed.)'), Sequence('(', NonTerminal('Ed.'), 'ed.', ')')),
          Choice(0, Comment('(book/article)'), Sequence('[', NonTerminal('Descr.'), ']')),
          OptionalAlt('.'),
        ), 'Title'),
      ),
      Sequence(Comment('(no author)'), Group(Comment('...'), 'Title'), Group(Comment('...'), 'Date')),
    ),
    Group(Sequence(
      Choice(0,
        Comment('(bare URL or publisher is also author)'),
        Sequence(NonTerminal('Publisher/Website name'), Choice(0, Comment('(location irrelevant)'), Sequence(',', NonTerminal('Location'))), '.'),
        Sequence(Comment('<em>'), NonTerminal('Newspaper/Blog-like website name'), Comment('</em>'), '.'),
        Group(Stack(
          Sequence(Comment('<em>'), NonTerminal('Periodical title'), Comment('</em>'), ','),
          Sequence(Comment('<em>'), NonTerminal('Volume'), Comment('</em>'), '(',  NonTerminal('Issue'), ')', ','), 
          Sequence(Choice(0, NonTerminal('Page'), Sequence(NonTerminal('Page'), '–', NonTerminal('Page')), Sequence('Article', NonTerminal('Number'))), '.'),
        ), 'Periodical'),
        Group(Stack(
          Sequence('In', Choice(0, Sequence(NonTerminal('I. Lastname'), '(Ed.),'), Sequence(Comment('...'), '(Eds.),')), Sequence(Comment('<em>'), NonTerminal('Title'), Comment('</em>'))),
          Sequence(OptionalAlt(Sequence('(', OptionalAlt(Sequence(NonTerminal('Ed.'), 'ed.')), OptionalAlt(','), OptionalAlt(Sequence(NonTerminal('Page range'))), ')')), '.'),
          // Sequence(OptionalAlt(Sequence('(', MultipleChoice(0, 'any', Sequence(NonTerminal('Ed.'), 'ed.'), Sequence('pp.', NonTerminal('P'), '–', NonTerminal('P'))), ')')), '.'),
        ), 'Edited book chapter'),
      ),
      Choice(0, Stack(Choice(0, Comment('(stable URL)'), Sequence('Retrieved', NonTerminal('Date'), ', from')), NonTerminal('URL')), NonTerminal('doi'), Comment('(no URI)')),
    ), 'Source'),
  ),
);

// Reorder the following lines to select the correct diagram
dPostcard
dIntext
dReference

// apa-railroad.js
import rr, * as rrClass from 'https://raw.githubusercontent.com/tabatkins/railroad-diagrams/ea9a12393bbaa2c802b0449fd5bdf34b6868b83c/railroad.js'
Object.assign(window, rr)
rrClass.Options.AR = 11

// <<All the code from above goes here>>

console.log(
  ({'postcard': dPostcard, 'intext': dIntext, 'reference': dReference}[Deno.args[0]])
    .format()
    .toStandalone(
      rrClass.defaultCSS
        .replace('rgba(0,0,0,0)', 'none')
        .replace(': 10 5', ': 11 5.5')
        .replace(/background-color: .+;/, '')
    )
)

#!/usr/bin/env bash
deno run apa-railroad.js postcard > apa-railroad-postcard.svg
deno run apa-railroad.js reference > apa-railroad-reference.svg
deno run apa-railroad.js reference > apa-railroad-reference.svg
magick apa-railroad-postcard.{svg,png}
magick apa-railroad-intext.{svg,png}
magick apa-railroad-reference.{svg,png}
montage apa-railroad-{intext,reference}.svg -geometry +0 -tile 1x2 apa-railroad.png