Skip to content

Corrections #56

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
de-soot merged 1 commit into from
Feb 7, 2025
Merged

Corrections #56

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 33 additions & 59 deletions _posts/2025-02-20-groff-apa.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: post
title: Guide to APA with groff ms and refer
date: 2025-02-06
date: 2025-02-07
categories: groff, ms, refer, macro, tmac, APA, style guide, pdf
permalink: /groff-apa
---
Expand Down Expand Up @@ -35,8 +35,6 @@ permalink: /groff-apa
- [Space Between Entries](/groff-apa#spacebetweenentries)
- [Field Ordering](/groff-apa#fieldordering)
- [Punctuation](/groff-apa#punctuation)
- [Authors, Ands & Ampersands](/groff-apa#authorsandsampersands)
- [Effect on Citations](/groff-apa#effectoncitations)
- [Period Suppression](/groff-apa#periodsuppression)

[Exporting as PDF](/groff-apa#exportingaspdf)
Expand Down Expand Up @@ -85,16 +83,18 @@ The first page does not have any headers (including page numbering) because grof

If you followed the steps on the previous section on the cover page, you might be confused as to why the first page after the cover page still does not have any page numbering while the page after it starts with the page numbering of '2'. This is because although groff started counting page numbers on the first page after the cover page, it still suppresses the first page by default.

When we used the `.RP no` macro to move the cover page information into its own page, we simply created a new "page 0" that groff does not know about (which is also why groff does not count it in the page numbering).
When we used the `.RP no` macro (also needed for this section) to move the cover page information into its own page, we simply created a new "page 0" that groff does not know about (which is also why groff does not count it in the page numbering).

Conveniently, is another macro to help us fix this. Place `.P1` below `.RP no` to unsuppress the first page header (page numbering):
There is another macro we can use to fix this. Place `.P1` below `.RP no` to unsuppress the first page header (page numbering):

```
.RP no
.P1
```

Note that `.P1` does not work by itself without `.RP no`, likely because groff suppresses headers on any page with cover page information even if you make them empty by doing this:
The `.RP no` macro is needed for this, but it produces a cover page. Use PDF-editing software to delete it if it is unwanted. Any tool can be used for this, but the best one I found is [PDFArranger](https://github.com/pdfarranger/pdfarranger).

`.P1` does not work by itself without `.RP no` likely because groff suppresses headers on any page with cover page information, even if you make them empty by doing this:

```
.TL
Expand Down Expand Up @@ -166,18 +166,12 @@ Here is how to make your text **bold**,
.ft B
```

*italicised*,
or *italicised*.

```
.ft I
```

or even ***both***!

```
.ft BI
```

And to set it back to normal:

```
Expand All @@ -192,7 +186,7 @@ refer uses numbered footnotes by default, but APA wants the author(s) and date i

## Parenthetical Citation <a name=parentheticalcitation></a>

After some research, I found a [blog post "no-tears" guide](https://preciouschicken.com/blog/posts/no-tears-references-groff), 2 [Github](https://github.com/Koshkov/groff-paper-template) [repositories](https://github.com/skurtulmus/refer-styles), and a post from the [GNU mailing list](https://lists.gnu.org) (which I cannot seem to find anymore). I extracted the refer block (denoted by `.R1` and `.R2`) from all those sources and combined them to make a frankenstein that works perfectly for most APA parenthetical citations:
After some research, I found a [blog post "no-tears" guide](https://preciouschicken.com/blog/posts/no-tears-references-groff), 2 [Github](https://github.com/Koshkov/groff-paper-template) [repositories](https://github.com/skurtulmus/refer-styles), and a post from the [GNU mailing list archive](https://lists.gnu.org) (which I cannot seem to find anymore). I extracted the refer block (denoted by `.R1` and `.R2`) from all those sources and combined them to make a frankenstein that works perfectly for most APA parenthetical citations:

```
.R1 \" Refer block start
Expand All @@ -210,7 +204,7 @@ no-label-in-reference # Do not display (Author(s), Date) like footnotes in refer

My lecturer luckily did not require me to use narrative citations, but yours might. If you do have to use narrative citation, unfortunately, refer does not have any support for narrative citations being alongside parenthetical citations. While it is possible to repurpose the citation formatting part of the refer block to change it from parenthetical to narrative, it would still not be possible to have both narrative and parenthetical citation on the same page.

The only practical solution I see to this problem is to keep the refer block as-is and write the narrative citations manually. This will require you to have a separate document for producing the referencing for the narrative citations, because refer will not make entries for them in the reference list as it will not recognise the narrative citations that you manually typed in, treating them like ordinary text. This also means that you need to generate 2 separate output PDFs and extract the correct reference list from the one without narrative citations to merge with the other one that does. Any PDF-editing tool can be used for this, but the best free and open-source one that I found was [PDFArranger](https://github.com/pdfarranger/pdfarranger).
The only practical solution I can think of for this problem is to keep the refer block as-is and write the narrative citations manually. This will require you to have a separate document for producing the referencing for the narrative citations, because refer will not make entries for them in the reference list as it will not recognise the narrative citations that you manually typed in, treating them like ordinary text. This also means that you need to generate 2 separate output PDFs and extract the correct reference list from the one without narrative citations to merge (using PDF-editing software) with the other one that does.

# Reference List <a name=referencelist></a>

Expand Down Expand Up @@ -252,7 +246,7 @@ Below is a list explaining each change made:

## Space Between Entries <a name=spacebetweenentries></a>

There is no space between reference entries by default, which can make it look cramped. This is already conforming to APA, but my lecturer wanted extra padding between the entries (even if that meant [breaking APA guidelines](https://apastyle.apa.org/style-grammar-guidelines/paper-format/reference-list)).
There is no space between reference entries by default. This is already conforming to APA, but my lecturer wanted extra padding between the entries (even if that meant [breaking APA guidelines](https://apastyle.apa.org/style-grammar-guidelines/paper-format/reference-list)) and maybe yours might too.

Inside `refer-ms.tmac` on lines 44--45, you can find this:

Expand All @@ -269,6 +263,28 @@ Inside `refer-ms.tmac` on lines 44--45, you can find this:
..
```

{%comment%}

### For Specific Entries <a name=forspecificentries></a>

For reference lists that span more than one page, some entries (especially large ones) may be split between 2 pages. While it would be easy to press the enter key a couple times in a WYSIWYG word processor, you should know by now that things are not going to be that easy in groff and refer.

To fix an entry being split between pages, first identify the entry above it and then add `TODO: I forgot how I did it` at the end of its `%O` line:

```
%K key123
%A Author, A.
%D 2000
%T Title
%J Journal
%V 123
%N 456
%P 789
%O https://doi.org/123.456
```

{%endcomment%}

## Field Ordering <a name=fieldordering></a>

The way refer orders the fields of each reference entry is hard-coded and different from what APA desires. More specifically, the date field is placed after the title field instead of being in between it and the author(s) field.
Expand Down Expand Up @@ -385,52 +401,10 @@ The list below details the changes:

- In the `.ds ref*spec!J` row, its `arg 1` is changed from a comma (`,`) to a period (`.`) to add a period after the title field.
- In the `.ds ref*spec!T` row, `\\*Q` and `\\*U` are removed to remove the opening and closing double quotation marks, respectively, around the title field.
- In both the `.ds ref*spec!T:0` and `.ds ref*spec!T:2` rows, `\fI` in `arg 3` and `\fP` in `arg 5` are removed to not italicise the text and because of redundancy (`\fP` resets font style back to normal), respectively.
- In both the `.ds ref*spec!T:0` and `.ds ref*spec!T:2` rows, `\fI` in `arg 3` and `\fP` in `arg 5` are removed to not italicise the text and because of redundancy (`\fP` resets font style back to the previous style), respectively.
- In the `.ds ref*spec!V` row, its `arg 1` is changed from empty (`""`) to a comma (`,`) to add a comma after the journal/periodical field; its `arg 3` is changed from bold-ing (`\fI`) to italicising (`\fB`) the text.
- All `\fP` in `arg 5` are moved to `arg 4` to make sure the punctuations after each field are not in bold or italics.

### Authors, Ands & Ampersands <a name=authorsandsampersands></a>

By default, refer prepends "and" before the last author for more than 1 author. This is in contrast to the ampersand (&) that APA wants.

It should have been an easy fix to simply replace an "and" in one of the refer tmac files, but there is surprisingly no such thing to be found in any of the 2 files.

A solution to this is to simply manually type out the whole Authors field in the bibliography file:

```
%K key123
%A Author, A., Author, B. & Author, C.
%D 2025
%T Title
%J Journal
%V 123
%N 456
%P 999
%O https://doi.org/12.34
```

As opposed to how it would usually be:

```
%K key123
%A Author, A., Author, B. & Author, C.
%D 2025
%T Title
%J Journal
%V 123
%N 456
%P 999
%O https://doi.org/12.34
```

However, this solution conflicts with the format of in-text citations, as described in the subsection below.

#### Effect on Citations <a name=effectoncitations></a>

Due to having only one `%A` in the bibliography file, refer will think that there is only one author and the formatting for citations specified in the refer block will not work.

There is a solution for this. It is not pretty, but it works. Similarly to what you would do in the solution described in the Narrative Citations section, you would have to have 2 separate bibliography files: one that generates the correct citations (normal file with multiple `%A` for multiple authors) and one that generates the correct author field in the reference entry (modified file with only one `%A` for multiple authors). After compiling both versions of the document by changing the argument of `bibliography` in the refer block to switch between both of the bibliography files, use a PDF-editing tool to extract and combine the correct citations and references into one final file.

### Period Suppression <a name=periodsuppression></a>

By default, refer appends a period at the end of each entry. This means that a period is added after the last field that contains a DOI or URL, which APA has [explicitly stated to not do](https://apastyle.apa.org/instructional-aids/reference-guide.pdf).
Expand Down
Loading