modular-annotated-bibliography-bibtex-rmarkdown

Template in R Markdown for generating a modular, illustrated, and annotated bibliography for the 21st Century with BibTeX

Status: works

What is this?

This template supports making single-paragraph annotations found in classical annotated bibliographies for undergrad homework. It also supports making multi-paragraph entries illustrated with figures, tables, equations, code listings, hyperlinks to videos online, and citations inside and outside the annotated bibliography. Yes, the annotated bibliography includes an inclusive Literature Cited section. These additional features make this modern approach to knowledge management more effective as a tool in science research and for self-study. We have to use a modular approach to the annotations to be able to avoid the loss of whitespace between paragraphs and to enable text wrapping around embedded figures. The modular approach also enables the reuse of annotations in the bibliographies of related projects.

The 21st Century bibliography has the following enhanced features that the classic annotated bibliography lacks:

• No longer restrained by the annote field in the BibTeX entry.
• Modular annotation for easy reuse in related projects.
• Images
• Tables
• Equations
• Code blocks
• Hyperlinks: internal and external
• Bibliographic entries can be reordered for subgrouping by category.
• Table of contents, hyperlinked to sections
• Index of terms
• Bibliography includes papers cited outside of those listed in the annotated bibliography.
• List of acronyms used
• List of glossary terms used
• List of mathematical notation

Why R Markdown?

This template can be used in RStudio or an advanced text editor. Many people prefer to write in R Markdown. R Markdown is a wrapper for LaTeX.

System requirements

You need a recent version of R. R Studio is optional.

You can use your current install of LaTeX (e.g., texlive). If you lack one, you can install via R a slimmed-down version of texlive called tinytex. It will fetch and install packages as you need them.

tinytex::install_tinytex()

You can install and import LaTeX packages using the following in the YAML header of the main Rmd file:

pdf_document:
  extra_dependencies: ['amsmath', 'minted']

The template has a code block to send the -shell-escape flag to the PDF compiler to enable the use of the minted package for syntax highlighting of code blocks.

You will need to install the following R packages:

The packages in [ ] are alternatives to the glossaries package in LaTeX.

• rmarkdown
• acronymsdown
• glossary

Additional requirements

• a BibTeX file (annote fields are not used. )
• a ~/bibNotes folder for storing the annotations. See example above.
• a ~/bibNotes/images folder for storing image files used in the bibNotes.
• a ~/glossaries folder to store the list of acronyms and glossary files.

Adding to the bibliography

1. Provide the path to your BibTeX file in the argument to \bibliography{}.
2. Create a .tex or .Rmd file for each entry and store it in the bibNotes folder. No enabling code on the top line of these files is required.
3. Store associated image files in the images subfolder.
4. Inject the bibliographic entry in a subsection heading by calling with its citekey in the argument for \bibentry{}. See below.

\subsection*{\bibentry{Mooers2021TemplatesForWritingPyMOLScripts}}
\addcontentsline{toc}{subsection}{Mooers2021TemplatesForWritingPyMOLScripts}
\input{/Users/blaine/bibNotes/Mooers2021TemplatesForWritingPyMOLScripts.Rmd}

Bash function for compiling to PDF and automatically opening the PDF

This function supports editing the R Markdown file outside of R Studio and compiling it from the command line (e.g., rmd main to compile to PDF and open the PDF in the Preview.app). Paste the code below into .bashrc or .zshrc and source this file (e.g., source .zshrc).

function rmd {
echo "Compile Rmd (R Markdown) file with R, and open the resulting PDF with the Preview.app. (Mapped to the alias 'pre')."
if [ $# -lt 1 ]; then
  echo 1>&2 "$0: not enough arguments"
  echo "Usage1: rmd <filename stem>"
  return 2
elif [ $# -gt 1 ]; then
  echo 1>&2 "$0: too many arguments"
  echo "Usage1: rmd  <filename stem>"
  return 2
fi
Rscript -e "library('rmarkdown');library('acronymsdown');library('gloassary');rmarkdown::render('$1.Rmd')" && pre $1.pdf
}

Notes

The compiling of the PDF could be faster. It is tolerable if you only occasionally need to compile the master file to make a PDF. If you seek a more interactive experience, try the typst variant found here. Typst may be easier for beginners to learn. The template for Typst has all of the same features except for support for lists of Math Notations and for interactive computing in code blocks in RStudio. A nice introduction to Typst in October 2024 by Dr. Chase Brown of the University of Central Florida is found here.

Update history

Version	Changes	Date
Version 0.1	Added badges, funding, and update table. Initial commit of working version.	2024 November 1

Sources of funding

• NIH: R01 CA242845
• NIH: R01 AI088011
• NIH: P30 CA225520 (PI: R. Mannel)
• NIH: P20 GM103640 and P30 GM145423 (PI: A. West)