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.
+Welcome to my website! This is where I write about whatever I think is interesting or helpful. It is made with Jekyll using the Minima theme and is hosted for free on Github Pages.
The source code for this website can be found on its Github repository.
Why Not Use a Toggleable Button
You can also include the button to toggle themes on the website alongside defaulting it if you want, but I find this an unnecessary use of Javascript.
-If you found this blog post useful, leave a comment down below! Check out how to add giscus comments to your own website on my previous blog post guide for it.
Conclusion
+ +If you found this blog post useful, leave a comment down below! Also check out how to add giscus comments to your own website on my previous guide for it.
-
+
- Font Family
+
-
+
- Default Fonts +
- Custom Fonts +
+ - Font Size +
- Line Spacing +
- Font Style +
-
+
- Formatting the Heading +
- Space Between Entries +
- Field Ordering +
- Punctuation
+
-
+
- Authors, Ands & Ampersands + + +
- Period Suppression +
+
Preface
+ +Many colleges give students a mandatory class where they learn how to cite and do referencing in essays.
+ +For my essay, I wrote it using Neovim, the same terminal text-editor I code on and write blogs for my website with, and that would not have been possible without a word processor that can compile documents from plaintext (unlike What-You-See-Is-What-You-Get (WYSIWYG) word processors, such as LibreOffice Writer). As you could tell from the title of this blog post, I used groff to accomplish this.
+ +Although some of the modifications detailed in this guide are specific to APA, you do not have to be writing in APA to find this guide helpful. Just adapt some of the specific changes made in this guide to suit your style guide.
+ +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 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.
+ +A fun fact about this blog post: this is actually my second time writing this whole thing because I frustratingly lost the first one in the dumbest way possible. I accidentally deleted the folder containing it because I forgot that I put it in the folder. Unfortunately, it was already gone by the time I realised due to the auto-emptying routine of my Trash folder scheduled to run once every hour.
+ +Introduction
+ +The American Psychological Association (APA) 7th Edition style guide 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 (t)roff (abbreviated as groff) is an older and more lightweight but less well-known typesetting alternative to LaTeX (which is popular for writing academic papers) that comes preinstalled in most GNU/Linux 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 (“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, 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 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 and refer. For more detail, see GNU’s official manual or troff’s HOWTO.
Cover 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 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
+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).
+ +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).
Conveniently, is another macro to help us 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:
.TL
+.AB no
+.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 “Abstract” heading).
Font
+ +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 already outputs text in your device’s default serif font family (typically Times New Roman), but sometimes (very rarely, in my experience) lecturers prefer sans-serif or even monospace in some cases.
+ +Default Fonts
+ +Changing to another one of the default fonts in groff is simple.
+ +This is how to change it to device’s default sans-serif,
+ +.fam H \" Helvetica
+monospace,
+ +.fam C \" Courier
+and (back to) serif font family:
+ +.fam T \" Times New Roman
+There are many other default fonts in groff listed in this post.
+ +Custom Fonts
+ +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 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, to be exact), but it is very easy to change. Simply add this line to your plaintext document to change the font size to 12pt:
+ +.nr PS 12
+As for what PS stands for, it probably means something like “Point Size”; .nr stands for “Number Registers”.
Line Spacing
+ +All parts of an APA-styled paper should be double-spaced. By default, groff uses 120% of font size 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
+Font Style
+ +Here is how to make your text bold,
+ +.ft B
+italicised,
+ +.ft I
+or even both!
+ +.ft BI
+And to set it back to normal:
+ +.ft R \" Stands for Regular or Roman
+In-text Citation
+ +Now that everything is set up, we can start to get into the citations.
+ +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, 2 Github repositories, and a post from the GNU mailing list (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 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)
+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.
+ +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.
+ +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 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. 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:
.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):
.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
.ceabove where the heading is rendered (.nop \%\\*[REFERENCES]).
+ - (Optional)
.nr PS 14above it increases the font size to 14pt, just remember to reset it back to normal (12pt) with.nr PS 12after.
+ - (Optional)
.spadds 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).
+ +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)):
.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 also some 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!Jrow, itsarg 1is changed from a comma (,) to a period (.) to add a period after the title field.
+ - In the
.ds ref*spec!Trow,\\*Qand\\*Uare removed to remove the opening and closing double quotation marks, respectively, around the title field.
+ - In both the
.ds ref*spec!T:0and.ds ref*spec!T:2rows,\fIinarg 3and\fPinarg 5are removed to not italicise the text and because of redundancy (\fPresets font style back to normal), respectively.
+ - In the
.ds ref*spec!Vrow, itsarg 1is changed from empty ("") to a comma (,) to add a comma after the journal/periodical field; itsarg 3is changed from bold-ing (\fI) to italicising (\fB) the text.
+ - All
\fPinarg 5are moved toarg 4to make sure the punctuations after each field are not in bold or italics.
+
Authors, Ands & Ampersands
+ +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
+ +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
+ +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.
+ +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:
+ +-
+
-msselects ms macros.
+ -Tpdfcompiles it to PDF; it is not needed forpdfroff.
+ -Rselects refer macros.
+ - (Optional)
-dpaper=a4and-P-pa4exports 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.
@@ -118,7 +585,9 @@You can also include the button to toggle themes on the website alongside defaulting it if you want, but I find this an unnecessary use of Javascript.
-If you found this blog post useful, leave a comment down below! Check out how to add giscus comments to your own website on my previous blog post guide for it.
Conclusion
+ +If you found this blog post useful, leave a comment down below! Also check out how to add giscus comments to your own website on my previous guide for it.
Conclusion
+ +f you found this blog post useful, leave a comment down below! Also read how to add reactive dark-mode to your website in my previous blog post.
+ ]]>Posts
--
+
-
+
+ + Guide to APA with groff ms and refer + +
-
Justify and Hyphenate Text on Websites using CSS diff --git a/_site/justify-text.html b/_site/justify-text.html index 1363867..d693603 100644 --- a/_site/justify-text.html +++ b/_site/justify-text.html @@ -94,6 +94,10 @@
Other Blogs That Justify
- JPEG XL’s jpegxl.info, which had fixed its un-hyphenated text.
Conclusion
+ +f you found this blog post useful, leave a comment down below! Also read how to add reactive dark-mode to your website in my previous blog post.
+ diff --git a/_site/sitemap.xml b/_site/sitemap.xml index 90a177d..61b12e5 100644 --- a/_site/sitemap.xml +++ b/_site/sitemap.xml @@ -1,27 +1,25 @@ -- - - + - https://de-soot.github.io/ -2024-05-27T10:25:58+00:00 -1.00 +http://localhost:4000/giscus-comments +2024-05-24T00:00:00+08:00 - https://de-soot.github.io/about -2024-05-27T10:25:58+00:00 -0.80 +http://localhost:4000/dark-mode +2024-09-07T00:00:00+08:00 - +https://de-soot.github.io/added-commenting -2024-05-27T10:25:58+00:00 -0.80 +http://localhost:4000/justify-text +2024-09-07T00:00:00+08:00 ++ +http://localhost:4000/groff-apa +2025-02-06T00:00:00+08:00 ++ +http://localhost:4000/about ++ - -http://localhost:4000/ - - - - - -https://de-soot.github.io/ -2024-05-27T10:25:58+00:00 -1.00 -- -https://de-soot.github.io/about -2024-05-27T10:25:58+00:00 -0.80 -- - - -https://de-soot.github.io/added-commenting -2024-05-27T10:25:58+00:00 -0.80 - -
+