This is the website where I write about whatever inspires me to write in form of blogs. It is made using Jekyll’s Minima theme and is hosted for free on Github Pages.
+This is the website where I write about whatever I think is interesting or helpful. It is made using Jekyll’s Minima theme and is hosted for free on Github Pages.
The source code for this website can be found on its Github repository.
For users visiting a website in a dark room at night, it would be less straining for their eyes if the webpage was displayed in a darker colour to match the environment, which is what dark mode does.
diff --git a/about.md b/about.md index 1c55a40..12e8fb3 100644 --- a/about.md +++ b/about.md @@ -4,11 +4,10 @@ title: About permalink: /about --- -This is the website where I write about whatever inspires me to write in form of [blogs][blog]. It is made using [Jekyll][jekyll]'s [Minima][minima] theme and is hosted for free on [Github Pages][pages]. +[This](/) is the website where I write about whatever I think is interesting or helpful. It is made using [Jekyll][jekyll]'s [Minima][minima] theme and is hosted for free on [Github Pages][pages]. The `source code` for this website can be found on its [Github repository][github repo]. -[blog]: / [jekyll]: https://jekyllrb.com [minima]: https://github.com/jekyll/minima [pages]: https://pages.github.com From 156e3fa1b468a53bdc07d3b3a1bb6352993ba7b3 Mon Sep 17 00:00:00 2001 From: wc <78423238+de-soot@users.noreply.github.com> Date: Thu, 6 Feb 2025 21:02:02 +0800 Subject: [PATCH 6/7] Updated README.md and about.md --- README.md | 19 +++ _posts/2025-02-20-groff-apa.md | 276 ++++++++++++++++++++++++++++----- _site/README.md | 22 ++- _site/about.html | 2 +- _site/feed.xml | 2 +- about.md | 2 +- 6 files changed, 283 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index a855682..71737a5 100644 --- a/README.md +++ b/README.md @@ -31,3 +31,22 @@ bundle exec jekyll serve 7) Profit! Refer to the [official Jekyll documentation](https://jekyllrb.com/docs) for more information regarding installing and running Jekyll. + +### Write a Blog Post + +1. Create a markdown (`.md`) file inside `/_posts` with this at the top of the document: + +```md +--- +layout: post +title: +date: YYYY-MM-DD +categories: +permalink: /... +--- +``` + +2. Write the title of the post after `title:`. +3. Replace `YYYY`, `MM`, and `DD` with the year, month, and day the post is published, respectively. +4. Add any keywords related to the topic of your post after `categories:` separated by commas. +5. Replace the `...` after `permalink:` with the custom path given to the blog post. diff --git a/_posts/2025-02-20-groff-apa.md b/_posts/2025-02-20-groff-apa.md index 12985ec..21f443c 100644 --- a/_posts/2025-02-20-groff-apa.md +++ b/_posts/2025-02-20-groff-apa.md @@ -32,10 +32,12 @@ permalink: /groff-apa [Reference List](/groff-apa#referencelist) - [Formatting the Heading](/groff-apa#formattingtheheading) -- [Authors, Ands & Ampersands](/groff-apa#authorsandsampersands) - - [Effect on Citations](/groff-apa#effectoncitations) - [Space Between Entries](/groff-apa#spacebetweenentries) -- [Period Suppression](/groff-apa#periodsuppression) +- [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) @@ -43,11 +45,11 @@ permalink: /groff-apa I think every student who has been through college has had to write an essay with citations and referencing for all their sources for a mandatory prerequisite class, and I was no exception to this. -Just as a fun little challenge, I wanted to write my essay using [Neovim](https://neovim.io), the same terminal text-editor I code on and write blogs for my website with, so I had to find a word processor that can compile documents from plaintext (unlike What-You-See-Is-What-You-Get (WYSIWYG) word processors, such as [LibreOffice](https://www.libreoffice.org) [Writer](https://www.libreoffice.org/discover/writer)). As you could tell from the title of this blog post, I chose to use [`groff`](https://www.gnu.org/software/groff) for that task. +Just as a fun little challenge, I wanted to write my essay using [Neovim](https://neovim.io), the same terminal text-editor I code on and write blogs for my website with, so I had to find a word processor that can compile documents from plaintext (unlike What-You-See-Is-What-You-Get (WYSIWYG) word processors, such as [LibreOffice](https://www.libreoffice.org) [Writer](https://www.libreoffice.org/discover/writer)). As you could tell from the title of this blog post, I chose to use [groff](https://www.gnu.org/software/groff) for that task. -You do not have to be using APA to find this guide helpful, as it goes through where many of the things that you will need to change are and explains how to change them. Just adapt some of the specific changes made in this guide to suit your needs. +You do not have to be writing in APA to find this guide helpful, as it goes through where many of the things that you will need to change are and explains how to change them. Just adapt some of the specific changes made in this guide to suit your needs. -This blog guide mainly just serves to compile all the relevant research I had done into a simple step-by-step solution I can easily follow when I want to use `groff` to write essays in APA again, but it also hopes to help others who were in the same spot I was save themselves some time and frustration that I had to go through when figuring things out by myself for the first time. +This blog guide mainly just serves to compile all the relevant research I had done into a simple step-by-step solution I can easily follow when I want to use groff to write essays in APA again, but it also hopes to help others who were in the same spot I was save themselves some time and frustration that I had to go through when figuring things out by myself for the first time. I made a [Github repository](https://github.com/de-soot/groff-apa) as a companion to this guide. It gives an example of the final generated output so you know exactly what you are going to get out of this. The source files included in the repository have some extra comments to help readability and can also be used as a template to quickly set things up to just get started writing. @@ -57,19 +59,19 @@ A fun little fact about this blog post: this is actually my second time writing The [American Psychological Association](https://apa.org) (APA) 7th Edition [style guide](https://apastyle.apa.org) is the most popular for formatting references and citations in college-level essays (at least that was what my lecturer said when they gave out the writing assignment). -[GNU](https://gnu.org) [(t)roff](https://troff.org) (abbreviated as `groff`) is an older and more lightweight but less well-known typesetting alternative to [LaTeX](https://www.latex-project.org) (which is popular for writing academic papers) that comes preinstalled in most [GNU/Linux](https://en.wikipedia.org/wiki/GNU/Linux_naming_controversy) distributions. If it was not for the massive size of a LaTeX install (>2GB vs. `groff`'s <10MB), I likely would not have used `groff`. `groff` also has a simpler syntax and compiles in an instant compared to LaTeX, which are some of the things that further convinced me to stick with `groff` even when I got stuck and lost at times. +[GNU](https://gnu.org) [(t)roff](https://troff.org) (abbreviated as groff) is an older and more lightweight but less well-known typesetting alternative to [LaTeX](https://www.latex-project.org) (which is popular for writing academic papers) that comes preinstalled in most [GNU/Linux](https://en.wikipedia.org/wiki/GNU/Linux_naming_controversy) distributions. If it was not for the massive size of a LaTeX install (>2GB vs. groff's <10MB), I likely would not have used groff. groff also has a simpler syntax and compiles in an instant compared to LaTeX, which are some of the things that further convinced me to stick with groff even when I got stuck and lost at times. -The `ms` macro is largely seen as the "default" macro for writing to PDF in `groff`, so it should have the most documentation out of any other macros. That was the main reason I chose to use the `ms` macro, along with already having previous experience writing basic documents with the `ms` macro. +The [ms](https://www.gnu.org/software/groff/manual/groff.html.node/ms.html) ("manuscript") macros were the earliest and are largely seen as the "default" set of macros for writing in groff, so it should have the most documentation out of any other macro packages. That was the main reason I chose to use the it instead of other macros, as well as having already experimented with writing basic documents with ms previously. -However, `groff` by itself cannot do citations and referencing out-of-the-box. Fortunately, it does come with a preprocessor called `refer` that does the citing and referencing for it (although, the defaults for `refer` do not conform to APA guidelines). Luckily, it is not too complex to change those defaults to match any style guide as long as you know where to find the right things to change. +However, groff by itself cannot do citations and referencing out-of-the-box. Fortunately, it does come with a preprocessor called refer that does the citing and referencing for it. Although the defaults for refer do not conform to APA guidelines, it is not too complex to change those defaults to match any style guide as long as you know where to find the right things to change. # Prerequisites -This guide assumes you are using a GNU/Linux-based system and already know how to write and compile basic `groff ms` documents to Portable Document Format (PDF). If not, do not worry. There are many resources online for getting started, such as Luke Smith's videos on [`groff`](https://videos.lukesmith.xyz/w/eDqgKby1W4sHQGZgqZbMLe) and [`refer`](https://videos.lukesmith.xyz/w/5ANbTYv7cgF69FhpAkVBwi). For more detail, see GNU's official [manual](https://www.gnu.org/software/groff/manual/groff.html) or `troff`'s [HOWTO](https://troff.org/TheGroffFriendsHowto.pdf). +This guide assumes you are using a Unix-based system (e.g. GNU/Linux, *BSD, macOS, etc.) and already know how to write and compile basic `groff ms` documents to Portable Document Format (PDF). If not, do not worry. There are many resources online for getting started, such as Luke Smith's videos on [groff](https://videos.lukesmith.xyz/w/eDqgKby1W4sHQGZgqZbMLe) and [refer](https://videos.lukesmith.xyz/w/5ANbTYv7cgF69FhpAkVBwi). For more detail, see GNU's official [manual](https://www.gnu.org/software/groff/manual/groff.html) or `troff`'s [HOWTO](https://troff.org/TheGroffFriendsHowto.pdf). # Cover Page -My assignment did not require me to include a cover page, but yours might. Although it is standard for cover page information to be on its own separate page, `groff` does not conform to that standard by default. Luckily, the `ms` macro does have a convenient to change this easily. Just put [`.RP no`](https://linux.die.net/man/7/groff_ms) as the first line of your document (`.RP` stands for "report"; the `no` argument tells it to not repeat the cover page information on the next page): +My assignment did not require me to include a cover page, but yours might. By default, groff puts cover page information on the same page as the essay. Luckily, the ms macros contain a convenient way to change this. Just put [`.RP no`](https://linux.die.net/man/7/groff_ms) as the first line of your document (`.RP` stands for "report"; the `no` argument tells it to not repeat the cover page information on the next page): ``` .RP no @@ -79,11 +81,11 @@ This is also needed for the next section on page numbering. # Page Numbering -The first page does not have any headers (including page numbering) because `groff` expects it to include cover page information (i.e. the title of the paper; optionally author(s), institution(s), date, and abstract). +The first page does not have any headers (including page numbering) because groff expects it to include cover page information (i.e. the title of the paper; optionally author(s), institution(s), date, and abstract). -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. +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 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): @@ -92,7 +94,7 @@ Conveniently, is another macro to help us fix this. Place `.P1` below `.RP no` t .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: +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: ``` .TL @@ -100,19 +102,19 @@ Note that `.P1` does not work by itself without `.RP no`, likely because `groff` .AE ``` -which works because even though the title (`.TL`) is required, it stops at the abstract (`.AB`, which ends at `.AE`; the `no` argument suppresses the error/warning it gives when its empty). +which works because even though the title (`.TL`) is required, it stops at the abstract (`.AB`, which ends at `.AE`; the `no` argument suppresses the "Abstract" heading). # Font -Probably the most widely accepted font for writing essays has got to be Times New Roman in 12 point size. This section covers how to change the font family, size, style, and line spacing. +Many lecturers demand assignments to be submitted in double-spaced Times New Roman in 12 point size. This section covers how to change the font family, size, style, and line spacing. ## Font Family -By default, `groff` outputs text in your [device's default serif font family](https://www.gnu.org/software/groff/manual/groff.html.node/Using-Fonts.html) (typically Times New Roman). This is a sensible default for most things, but in my experience, you sometimes may have to change your font to suit your lecturer's tastes. +By default, groff already outputs text in your [device's default serif font family](https://www.gnu.org/software/groff/manual/groff.html.node/Using-Fonts.html) (typically Times New Roman), but sometimes (very rarely, in my experience) lecturers prefer sans-serif or even monospace in some strange cases. ### Default Fonts -Changing to another one of the default fonts in `groff` is simple. +Changing to another one of the default fonts in groff is simple. This is how to change it to device's default [sans-serif](https://www.gnu.org/software/groff/manual/groff.html.node/Font-Families.html), @@ -132,15 +134,15 @@ and (back to) serif font family: .fam T \" Times New Roman ``` -There are many other default fonts in `groff` listed in [this post](https://technicallywewrite.com/2024/04/12/changefonts). +There are many other default fonts in groff listed in [this post](https://technicallywewrite.com/2024/04/12/changefonts). ### Custom Fonts -This one is trickier, and I still have not been able to get it to work on my device yet. I did find a [guide that seemed promising](https://www.port.de/cgi-bin/groff/AddingFonts) though. Maybe I will revisit this in the future, if I get it working. +Installing custom fonts for groff is a little bit trickier; I have not been able to get it to work on my device yet. I did find a [guide that seemed promising](https://www.port.de/cgi-bin/groff/AddingFonts) though. Maybe I will revisit this if I get it working in the future. ## Font Size -The default font size in `groff` is a little bit less than 12pt ([10pt](https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html) to be exact), but it is very easy to change. Simply add this line to your plaintext document: +The default font size in groff is a little bit less than 12pt ([10pt](https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html), to be exact), but it is very easy to change. Simply add this line to your plaintext document: ``` .nr PS 12 @@ -176,7 +178,7 @@ And to set it back to normal: ## Line Spacing -All parts of an APA-styled paper should be double-spaced according to [this](https://apastyle.apa.org/style-grammar-guidelines/paper-format/line-spacing). By default, `groff` uses [120% of font size](https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html) as vertical spacing. Fortunately, changing this to double-spacing is just as simple as changing the font size: just set the vertical spacing (`.nr VS`) to double your font size (`.nr PS`). +All parts of an APA-styled paper [should be double-spaced](https://apastyle.apa.org/style-grammar-guidelines/paper-format/line-spacing). By default, groff uses [120% of font size](https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Type-Size-and-Vertical-Spacing.html) as vertical spacing. Fortunately, changing this to double-spacing is just as simple as changing the font size: just set the vertical spacing (`.nr VS`) to double your font size (`.nr PS`). ``` .nr VS 24 @@ -186,57 +188,259 @@ All parts of an APA-styled paper should be double-spaced according to [this](htt It is finally about time to start getting into the actual citations after all that setting-up. -`refer` uses numbered footnotes by default, but APA wants the author(s) and date included in their in-text citations. This section will cover how to do exactly as APA says. +refer uses numbered footnotes by default, but APA wants the author(s) and date included in their in-text citations. This section will cover how to do exactly as APA says. ## Parenthetical Citation -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](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 -database ref.bib # Path to refer bibliography file from current working directory (can be absolute directory) -accumulate # Prints References at end of the document (same as `-e` argument for `refer`) -move-punctuation # Ensures citations appear before punctuations (same as `-P` argument for `refer`) +database ref.bib # Path to refer bibliography file from current working directory (can also be absolute directory) +accumulate # Prints References at end of the document (same as `-e` argument for refer) +move-punctuation # Ensures citations appear before punctuations (same as `-P` argument for refer) sort A+ # Sorts References in alphabetical order label "(A1?(A1.n(A3?' et al.':A2&' & 'A2.n)):Q)', '(D.y|D)" # "Author(s), Date" format for parenthetical citation (joins author names using '&' if 2 authors; appends 'et. al.' if 3 or more) -bracket-label " (" ) "; " # (same as `-S` argument for `refer`) +bracket-label " (" ) "; " # (same as `-S` argument for refer) no-label-in-reference # Do not display (Author(s), Date) like footnotes in reference list .R2 \" Refer block end ``` ## Narrative Citation -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. +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 somewhat 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 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). # Reference List -This section is where we start to dive into `refer`'s code (usually located inside either `/usr/share/groff/current/tmac` or `/usr/local/share/groff/current/tmac`). Rest assured, the changes that will be made will not be very complicated as long as you know 3 things: what to change, what to change them to, and where to find them (all 3 being what I had to figure out on my own by reading and tinkering with the source code). +This section is where we start to dive into refer's code (usually located inside either `/usr/share/groff/current/tmac` or `/usr/local/share/groff/current/tmac`). Rest assured, the changes that will be made will not be difficult as long as you know 3 things: what to change, what to change them to, and where to find them (all 3 being what I had to figure out on my own by reading and tinkering with the source code). ## Formatting the Heading +The "References" heading is left-aligned by default, whereas [APA wants it centered](https://apastyle.apa.org/style-grammar-guidelines/paper-format/reference-list). Some extra changes not specified by APA my lecturer wanted were to make the Heading a little bigger and add an extra line of space below it. +On lines 75--79 of `refer-ms.tmac`, you will find this: -## Authors, Ands & Ampersands - +``` +.de ref*biblio-start-hook +. SH +. nop \&\\*[REFERENCES] +. par@reset +.. +``` +And this is what it will look like fixing the issues (lines that are commented out (denoted by `\"`) do not strictly conform to APA, uncomment them to use them): -### Effect on Citations +``` +.de ref*biblio-start-hook +.\" nr PS 14 +. SH +. ce +. nop \&\\*[REFERENCES] +.\" sp +.\" nr PS 12 +. par@reset +.. +``` +Below is a list explaining each change made: +- To make the heading centered, put `.ce` above where the heading is rendered (`.nop \%\\*[REFERENCES]`). +- (Optional) `.nr PS 14` above it increases the font size to 14pt, just remember to reset it back to normal (12pt) with `.nr PS 12` after. +- (Optional) `.sp` adds an extra line of space below it. ## Space Between Entries +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)). + +Inside `refer-ms.tmac` on lines 44--45, you can find this: + +``` +.de ref*biblio-item-end +.. +``` + +(Optional) Just like how we added a space below the "References" heading, use `.sp` to add a line of space between each entry in the reference list: + +``` +.de ref*biblio-item-end +. sp +.. +``` + +## Field Ordering + +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. + +There will be these 5 lines that dictate the order of the fields of each entry on lines 53--57 of `refer-ms.tmac`: +``` +.ds ref*spec!0 Q A T S V N P I C D O +.ds ref*spec!1 Q A T J S V N P I C D O +.ds ref*spec!2 Q A T S V P I C D O +.ds ref*spec!3 Q A T B E S V P I C D O +.ds ref*spec!4 Q A T R G P I C D O +``` + +Documentation for what each of the `ref*spec!N` mean can be found in the comments at the top of `refer.tmac` on lines 67--71: + +``` +.\" ref*spec!0 Q A T S V N P I C D O -- other +.\" ref*spec!1 Q A T J S V N P I C D O -- journal article +.\" ref*spec!2 Q A T S V P I C D O -- book +.\" ref*spec!3 Q A T B E S V P I C D O -- article within book +.\" ref*spec!4 Q A T R G P I C D O -- technical report +``` + +The values for the letters after the `ref*spec!N` are specified in the bibliography file linked in the refer block (`ref.bib`). + +Rearranging `D` (Date) into the correct order (right after `A` (Author(s)) and before `T` (Title)): -## Period Suppression +``` +.ds ref*spec!0 Q A D T S V N P I C O +.ds ref*spec!1 Q A D T J S V N P I C O +.ds ref*spec!2 Q A D T S V P I C O +.ds ref*spec!3 Q A D T B E S V P I C O +.ds ref*spec!4 Q A D T R G P I C O +``` + +## Punctuation + +Switching the order of the fields messes up the hard-coded punctuation order, but there are some other defaults that do not follow APA guidelines. +Go to lines 59--73 of `refer-ms.tmac`, where you will find this: +``` +.ds ref*spec!A ", " " +.ds ref*spec!B """ " " "in \fI" "" "\fP" +.ds ref*spec!D """ " " "(" ")" +.ds ref*spec!E ", " " "ed. " +.ds ref*spec!G """ " " "(" ")" +.ds ref*spec!J ", " " "\fI" "" "\fP" +.ds ref*spec!N """ "(" "" ")" +.ds ref*spec!O ". " " +.ds ref*spec!P ", " " "p.\~" +.ds ref*spec!PP ", " " "pp.\~" +.ds ref*spec!T ", " " "\\*Q" "" "\\*U" +.ds ref*spec!T:0 ", " " "\fI" "" "\fP" +.ds ref*spec!T:2 ", " " "\fI" "" "\fP" +.ds ref*spec!V """ " " "\fB" "\fR" +.ds ref*spec!dflt ", " " +``` + +It will look like nonsense at first, but documentation can be found in the comments of `refer.tmac` on lines 84--110: + +``` +.\" arg 1 the punctuation character to use to separate this field +.\" from the previous field +.\" arg 2 a string to insert after the punctuation character of the +.\" previous field (normally a space) +.\" arg 3 a string with which to prefix this field +.\" arg 4 a string with which to postfix this field +.\" arg 5 a string to add after the punctuation character supplied +.\" by the next field +.\" +.\" 1 2 3 4 5 +.\" ------------------------------------------------------------------ +.\" ref*spec!A , " " -- author name +.\" ref*spec!B "" " " "in \fI" "" "\fP" -- bk title of article +.\" ref*spec!D "" " " "(" ")" -- date of publication +.\" ref*spec!E , " " "ed. " -- editor +.\" ref*spec!G "" " " "(" ")" -- US Gov. ordering # +.\" ref*spec!J , " " "\fI" "" "\fP" -- journal name +.\" ref*spec!N "" "(" "" ")" -- issue number +.\" ref*spec!O . " " -- other information +.\" ref*spec!P , " " "p.\~" -- page +.\" ref*spec!PP , " " "pp.\~" -- page range +.\" ref*spec!T , " " "\\*Q" "" "\\*U" -- journal title +.\" ref*spec!T:0 , " " "\fI" "" "\fP" -- book title (other) +.\" ref*spec!T:2 , " " "\fI" "" "\fP" -- book title (book) +.\" ref*spec!V "" " " "\fB" "\fR" -- volume number +.\" +.\" ref*spec!dflt , " " -- all other entries +``` + +This is how it looks like after some changes: + +``` +.ds ref*spec!A ", " " +.ds ref*spec!B """ " " "in \fI" "\fP" +.ds ref*spec!D """ " " "(" ")" +.ds ref*spec!E ", " " "ed. " "" +.ds ref*spec!G """ " " "(" ")" +.ds ref*spec!J ". " " "\fI" "\fP" +.ds ref*spec!N """ "(" "" ")" +.ds ref*spec!O ". " " +.ds ref*spec!P ", " " "p.\~" +.ds ref*spec!PP ", " " "pp.\~" +.ds ref*spec!T ". " " +.ds ref*spec!T:0 ". " " +.ds ref*spec!T:2 ". " " +.ds ref*spec!V ", " " "\fI" "\fR" +.ds ref*spec!dflt ", " " +``` + +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 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 punctuations are not in bold or italics. + +### Authors, Ands & Ampersands + +#### Effect on Citations + +### Period Suppression + +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). + +To fix this, first go into `refer.tmac`, where you will find this on lines 210--213: + +``` +. \" now add a final period +. ie d ref*string \{\ +. if !\\n[ref*suppress-period] \ +. as ref*string . +``` + +Now just remove the period (`.`) on the last line (213): + +``` +. \" now add a final period +. ie d ref*string \{\ +. if !\\n[ref*suppress-period] \ +. as ref*string +``` # Exporting as PDF +The plaintext document can be compiled with either `groff`, + +``` +groff -ms -Tpdf -R -dpaper=a4 -P-pa4 sample.ms > sample.pdf +``` + +or `pdfroff` (which is just a wrapper around `groff`): + +``` +pdfroff -ms -R -dpaper=a4 -P-pa4 sample.ms > sample.pdf +``` + +I found that `pdfroff` produces better-looking text output, but it may need to be installed separately for macOS, which uses an older version of `groff` that does not come packaged with `pdfroff`. + +Below is a list explaining what each of the optional arguments mean: + +- `-ms` selects ms macros. +- `-Tpdf` compiles it to PDF; it is not needed for `pdfroff`. +- `-R` selects refer macros. +- (Optional) `-dpaper=a4` and `-P-pa4` exports the paper to the international-standard A4 size instead of the default US letter. + +# Conclusion +If you found this helpful in any way or have any questions, feel free to leave a comment below. ]]>For users visiting a website in a dark room at night, it would be less straining for their eyes if the webpage was displayed in a darker colour to match the environment, which is what dark mode does.
diff --git a/_site/index.html b/_site/index.html index 5fb4fa7..ef801a4 100644 --- a/_site/index.html +++ b/_site/index.html @@ -38,7 +38,12 @@Posts
--
+
-
+
+ + Guide to APA with groff ms and refer + +
-
Justify and Hyphenate Text on Websites using CSS diff --git a/_site/sitemap.xml b/_site/sitemap.xml index 7a719ba..61b12e5 100644 --- a/_site/sitemap.xml +++ b/_site/sitemap.xml @@ -13,6 +13,10 @@
2024-09-07T00:00:00+08:00 + +http://localhost:4000/groff-apa +2025-02-06T00:00:00+08:00 +http://localhost:4000/about diff --git a/assets/main.scss b/assets/main.scss index 5a31819..d1d7d6e 100644 --- a/assets/main.scss +++ b/assets/main.scss @@ -5,31 +5,31 @@ body { background-color: hsl(0, 0, 98); - font-size: 1.2rem; + font-size : 1.2rem; } h1 { - color: hsl(0, 0, 5); + color : hsl(0, 0, 5); font-family: sans-serif; font-weight: bold; } h2 { - color: hsl(0, 0, 10); + color : hsl(0, 0, 10); font-family: sans-serif; } h3 { - color: hsl(0, 0, 15); + color : hsl(0, 0, 15); font-family: sans-serif; } p, ol, ul { - font-family: serif; color : hsl(0, 0, 20); + font-family: serif; hyphens : auto; text-align : justify; - line-height: 1.75; + line-height: 150%; } @media (prefers-color-scheme: dark) {
-
+