2 Tools & Workflows for Writing

Many people use MS Word when it comes to writing. Not withholding the importance of the invention of MS Office, it is not the right tool to write methodological or theoretical papers in statistics. To many, writing a statistical paper using MS Word would be as interesting as running a statistical data analysis using MS Excel. Simply put, MS Office is great for office staff to do routine office documentary tasks.

For professional writing, one need to be aware of the professional tools and invest time to master them.

2.1 Word vs. LaTeX

The right, high quality, professional typesetting system is LaTeX. LaTeX is a typesetting language that makes it easier and cleaner to write documents involving extensive mathematical content. It is the standard in Statistics, Mathematics, Physics, Chemistry and other disciplines that require many mathematical formulas.

LaTeX separates the appearance of a document from its content. This allows authors to be able to focus on writing the content without having to worry about its appearance until the end. There are many different professionally looking appearances one can choose or design, allowing for easy adaptation to different formats and styles.

A LaTeX document has .tex extension, and can be edited by your favorite text editor. The final output of the document can have different formats, the most popular of which is pdf, which stands for portable document format. It can be opened on any platform (computer operating system).

The source .tex file is a plain text file. Just like source code of any programming language, a plain text file allows version control, which makes tracking and managing the source easy and professional. The most popular version control tool today is git.

Example 2.1 LaTeX vs. Word

Suppose you want to write down a likelihood function for a Gaussian model: \[ L(\mu, \sigma^2 \mid x_1, \ldots, x_n)= (2\pi\sigma^2)^{-n / 2}\exp\left\{ -\frac{1}{2\sigma^2}\sum_{i = 1}^n(x_i - \mu)^2\right\}. \]

  • In LaTeX , the source code is simple and transparent:
L(\mu, \sigma^2 \mid x_1, \ldots, x_n) = (2\pi\sigma^2)^{-n / 2}\exp\left\{
-\frac{1}{2\sigma^2}\sum_{i = 1}^n(x_i - \mu)^2\right\}.

This produces beautifully typeset mathematics, is reproducible, and can be revised easily. In MS Word, one must insert each symbol manually through the Equation Editor: Greek letters via dropdowns, summations via menus, exponents via special boxes. Formatting quickly becomes clumsy, and editing dozens of formulas is tedious. Copy-pasting often breaks structure, and version control is nearly impossible.

For one or two equations Word may be acceptable. But for an entire paper with dozens of equations, cross-references, and theorems, LaTeX is the only tool that is professional, efficient, and sustainable.

Exercise 2.1 Compare Word and LaTeX

  1. Typeset the following equation in MS Word using its built - in Equation Editor: [ = _{^p}{ |y - X|_2^2
  • ||_1 }. ]
  1. Now, paste this LaTeX code into Overleaf (or another LaTeX editor) and compile:
\hat{\beta} = \arg\min_{\beta \in \mathbb{R}^p}
\left\{\frac{1}{2n}\|y - X\beta\|_2^2 + \lambda \| \beta\|_1 \right\}
  • Which approach is faster?
  • Which result looks more professional?
  • Which is easier to revise and share?

While LaTeX is the professional standard for statistical and mathematical writing, statisticians must also remain flexible when collaborating with scientists from other fields. In many interdisciplinary projects, collaborators still prefer Word as the common platform for writing and revision. This can also often be the case when developing grant applications to National Insititutes of Health (NIH). This is understandable, since for papers in fileds such as biology, medicine, or social sciences, statistical formulas are often minimal or should even be avoided altogether. In such cases, it is often best to accommodate collaborators by using Word for the main text, while reserving LaTeX for supplementary technical sections, appendices, or internal drafts where precise mathematical notation is required.

2.2 Git for Version Control

Many tutorials are available in different formats. Here is a YouTube video ``Git and GitHub for Beginners—Crash Course’’.

The video also covers GitHub, a cloud service for Git. Other similar services are, for example, bitbucket and GitLab. A cloud service gives you a cloud back up of your work and makes collaboration with co - workers easy.

There are tools and tutorials that make learning Git easy.

2.2.1 Set Up

  • Download Git here.

  • Make a GitHub Account here if you don’t have one yet.

  • Get started with your GitHub account by following the help page.

    • One important step is the set-up.

    • The connection between your local and GitHub repositories needs to be set up onlyonce.

    • One easy way is with a personal access token, as illustrated in a YouTube video.

2.2.2 Most Frequently Used Git Commands

  • git clone:
    • Clones a remote repository to a local folder.
    • Requires either HTTPS link or SSH key to authenticate.
  • git pull:
    • Downloads any updates made to the remote repository and automatically updates the local repository.
  • git status:
    • Returns the state of the working directory.
    • Lists the files that have been modified, and are yet to be or have been staged and/or committed.
    • Shows if the local repository is begind or ahead a remote branch.
  • git add:
    • Adds new or modified files to the Git staging area.
    • Gives the option to select which files are to be sent to the remote repository.
  • git rm:
    • Used to remove files from the staging index or the local repository.
  • git commit:
    • Commits changes made to the local repository and saves it like a snapshot.
    • A message is recommended with every commit to keep track of changes made.
  • git push:
    • Pushes commits made on local repository to the remote repository.

Example 2.2 A clean daily Git workflow

  1. Pull the latest changes
git pull

  1. Write/edit files (e.g., intro.Rmd, style.css).

  2. Check what has changed

git status
git diff
  1. Stage only what you intend to commit
git add intro.Rmd style.css
  1. Commit with a focused message
git commit -m "intro: refine motivation; style: add callout color"
  1. Push to remote
git push

2.2.3 Tips on using Git:

  • Use the command line interface instead of the web interface (e.g., upload on GitHub)
  • Make frequent small commits instead of rare large commits.
  • Make commit messages informative and meaningful.
  • Name your files/folders by some reasonable convention.
  • Lower cases are better than upper cases.
  • No blanks in file/folder names.
  • Keep the repo clean by not tracking generated files.
  • Creat a .gitignore file for better output from git status.
  • Keep the linewidth of sources to under 80 for better git diff view.

2.2.4 Pull Request

To contribute to an open source project (e.g., our classnotes), use pull requests. Pull requests

“let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.”

Watch this YouTube video: GitHub pull requests in 100 seconds.

Example 2.3 A useful .gitignore for LaTeX/Bookdown

Create a file named .gitignore in the project root:

# RStudio / R files
.Rproj.user/
.Rhistory
.RData
.Ruserdata

# Bookdown build output
_book/
_bookdown_files/
*.utf8.md
*.knit.md

# LaTeX build files
*.aux
*.bbl
*.blg
*.brf
*.fls
*.fdb_latexmk
*.idx
*.ilg
*.ind
*.lof
*.log
*.lot
*.maf
*.mtc*
*.out
*.pdf        # <-- if you want to keep generated PDFs out of git
*.synctex.gz
*.toc
*.ttt
*.xdv

# Common OS junk
.DS_Store
Thumbs.db

# Editor files
*.swp
*.swo

Now git status will show only meaningful source changes.

2.3 LaTeX

2.3.1 LaTeX Templates

A LaTeX source file has extension name .tex. It is a plain text file that can be edited by any text editor. It can be tracked easily for differences between any two versions. Different document classes are predefined such as letter, article, report, beamer (for presentations), and book. Customized document classes can be defined once you know more about LaTeX.

2.3.2 Editing and Compiling LaTeX

Working efficiently with LaTeX largely depends on the editing environment. Although a plain text editor is sufficient for editing, certain tools can make the writing, compiling, and debugging process much smoother. Choosing an editing environment is also a matter of personal preference.

2.3.2.1 Local Editors

  • Emacs with AUCTeX: a very powerful, customizable editor popular with many statisticians. AUCTeX provides syntax highlighting, automatic indentation, compilation shortcuts, and forward/backward search between the source and the PDF.
  • RStudio: although primarily for R, it supports LaTeX via R Markdown and Bookdown projects, making it very convenient for statistical writing.
  • TeXstudio and TeXmaker: cross-platform editors that offer integrated compiling, autocompletion, spell checking, and bibliography management.

2.3.2.2 Online Editors

  • Overleaf: a widely used online LaTeX editor that runs in the browser. It allows real-time collaboration, version history, and integrates easily with GitHub. Overleaf is especially helpful when working with co-authors who are less comfortable setting up LaTeX locally.

2.3.2.3 Compiling LaTeX

For compilation, the traditional workflow involves running pdflatex and bibtex manually. Tools like latexmk can automate this process by detecting which passes are needed and executing them automatically. Most editors (e.g., TeXstudio, VS Code, Emacs+AUCTeX) integrate latexmk so you only need to press one shortcut key to recompile the document.

Exercise 2.2 Compile a LaTeX template

Let us start from a basic template in the demo repo. Clone it to an appropriate location on your own computer. Go to the manuscript folder and compile the pdf product with the following:

pdflatex statspaper
bibtex statspaper
pdflatex statspaper
pdflatex statspaper

It is the bibtex step that incorporates the references from the bib files. Two rounds of pdflatex are necessary for LaTeX to get all the cross-referencing settled.

The whole process could be automated by:

latexmk -pdf statspaper

Advanded users may take a look at the Makefile, in which different targets can be set up and the needed opertations for each target is automated.

2.3.2.4 Choosing the Right Tool

  • If you prefer maximum control and flexibility, Emacs with AUCTeX or VS Code with LaTeX Workshop are excellent.

  • If you want a quick, friendly environment, RStudio work well.

  • For collaborations, especially interdisciplinary projects or student mentoring, Overleaf is often the most practical choice, since it removes the need to install LaTeX locally.

Exercise 2.3 Trying different editors

  1. If you already have LaTeX installed, open the same .tex file in two different editors (e.g., Emacs and TeXstudio, or VS Code and RStudio). Alternatively, you may use Overleaf.
  2. Try compiling the document and correcting a small error (e.g., a missing bracket).
  3. Discuss:
    • Which editor felt more comfortable?
    • Which features (syntax highlighting, autocompletion, error display) were most helpful?
    • If you were collaborating with someone outside statistics, which tool would you recommend?

2.3.2.5 Tips on Getting Started

  • Read the compiling log and fix the errors/warnings.
  • Googling the error/warning messages usually helps.
  • Limit the preamble to include only what is necessary.
  • Set up document margins with the geometry package.
  • No manually controlling spaces.
  • Familiarize yourself with LaTeX symbol tables.
  • Keep line widths under 80 characters in source files.
  • Separate paragraphs in source files by double blank lines.
  • Define acronyms at their first occurrences and only once.
  • Use GPT or other LLM tools. While these tools are very convenient and getting better and better, it is still helpful if you know the basic about LaTeX.

Perfect — that will be very engaging for students. You can simulate realistic LaTeX error messages, show them in an example block, and then ask students to diagnose what they mean. Here’s a ready-to-drop Rmd block:

Example 2.4 Common LaTeX error messages

Here are some typical error messages you might encounter.

  1. Missing end of document
! LaTeX Error: \begin{document} ended by \end{article}.
  1. Undefined control sequence
! Undefined control sequence.
l.6 This paper is written in \Latex
  1. Missing $ inserted
! Missing \$ inserted.
l.12 The regression coefficient is beta\_1
  1. Citation undefined
LaTeX Warning: Citation 'smith2020' on page 3 undefined on input line 45.
  • What do each of these errors/warnings mean?
  • How would you go about fixing them?

2.3.3 Math Equations

For serious math typesetting, use packages amsmath, amsthm, and others.

Tips on using math:

  • Punctuate equations as they always are part of sentences.
  • Add spaces between symbols for better readability in sources.
  • Do not start a sentence with a math symbol; rephrase to avoid it.
  • No fractions (\frac) in inline math expressions.
  • No breaking inline math expressions into different lines in tex sources.
  • No labeling equations that are not referenced.
  • Reference labeled equations with \eqref instead of (\ref).
  • Keep fonts consistent for the same notations (e.g., \(n\) not n; AIC not \(AIC\)).
  • Use appropriate sizes for parentheses.
  • When multiple parentheses are needed in mathematical expressions, use the following ordering unless the journal specifies otherwise \([\{(\mbox{math here})\}].\)
  • Use predefined math functions (e.g, \(\exp\) not \(exp\); \(\Pr\) not \(P\)).
  • Use \allowdisplaybreak to allow page breaks in aligned equations.
  • Use \dd for differentiation operator (available from package physics).
  • No breaking long equations arbitrarily in tex source; break them into short lines at appropriate places and add sufficient spaces to make the sources more readable.
  • Align at appropriate places in multiline equations.

Example 2.5 Cleaning math expressions in LaTeX

Below are some math expressions written poorly in LaTeX.
Your task is to (1) identify what’s wrong with each one, and (2) rewrite it following the best practices.

  1. Inline math with fraction:
 $ \frac{a}{b} + c $

  1. Missing equation label:

    \begin{equation}
y = \beta_0 + \beta_1 x + \epsilon
\end{equation}

  2. Wrong font for notations:

    $ AIC = -2logL + 2k $

  3. Misplaced function and parentheses:

    $ P(X>c) = exp(-\lambda c) $

Exercise 2.4 A “correct” paragraph with bad LaTeX

The following paragraph deliberately violates many LaTeX best practices. Your task is to identify and fix all the issues.

Let $\mathbf{m}=(m_1,\ldots,m_p)^T \in N^{p}$ be a vector of taxon counts
and $M=\sum_{j=1}^{p} m_j$ be the total count. Let $S \in \{1, ..., K\}$
be the unobservable hidden state variable indicating the cluster membership.
Assume $\mathbf{m}$, in any given state S, follow a Dirichlet-Multinomial (DM)
distribution. More specifically
\begin{equation}\label{eq:dm}
  \mathbf{m} | (S=k) \sim DM(M,\theta_k,\alpha^{[k]})
\end{equation}
or, equivalently, the hierarchical structure
\begin{equation*}
  \begin{aligned}
    \mathbf{m} | \mathbf{p} &\sim Multinomial(M,\mathbf{p}) \\
    \mathbf{p} | (S=k) &\sim Dir(\theta_k,\alpha^{[k]})
  \end{aligned}
\end{equation*}
where $\alpha^{[k]}=(\alpha_{1}^{[k]},...,\alpha_{p}^{[k]})^T \in \Delta^{p-1}, 
\theta_k>0$
is an over-dispersion parameter and $\mathbf{p}$ follows a Dirichlet 
distribution under
each state k in the hierarchical formulation The conditional mean of 
taxon j's count is
$E(m_{j} | S = k) = M\alpha_{j}^{[k]}$ and the conditional variance 
is
$Var(m_j | S=k) = 
\frac{M\alpha_{j}^{[k]}(1-\alpha_{j}^{[k]})(M \theta_k + 1)}{\theta_k + 1}$
For completeness, note also that $P(S=k|\mathbf{m})>0$ for 
all k $[\{(m_1+m_2]\}]$ (see (\ref{eq:dm})).

Let \(\mathbf{m}=(m_1,\ldots,m_p)^T \in N^{p}\) be a vector of taxon counts and \(M=\sum_{j=1}^{p} m_j\) be the total count. Let \(S \in \{1, ..., K\}\) be the unobservable hidden state variable indicating the cluster membership. Assume \(\mathbf{m}\), in any given state S, follow a Dirichlet-Multinomial (DM) distribution. More specifically \[\begin{equation} \mathbf{m} | (S=k) \sim DM(M,\theta_k,\alpha^{[k]}) \tag{2.1} \end{equation}\] or, equivalently, the hierarchical structure \[\begin{equation*} \begin{aligned} \mathbf{m} | \mathbf{p} &\sim Multinomial(M,\mathbf{p}) \\ \mathbf{p} | (S=k) &\sim Dir(\theta_k,\alpha^{[k]}) \end{aligned} \end{equation*}\] where \(\alpha^{[k]}=(\alpha_{1}^{[k]},...,\alpha_{p}^{[k]})' \in \Delta^{p-1}, \theta_k>0\) is an over-dispersion parameter and \(\mathbf{p}\) follows a Dirichlet distribution under each state k in the hierarchical formulation The conditional mean of taxon j’s count is \(E(m_{j} | S = k) = M\alpha_{j}^{[k]}\) and the conditional variance is \(Var(m_j | S=k) = \frac{M\alpha_{j}^{[k]}(1-\alpha_{j}^{[k]})(M \theta_k + 1)}{\theta_k + 1}\). For completeness, note also that \(P(S=k|\mathbf{m})>0\) for all k \([\{(m_1+m_2]\}]\) (see (2.1)).

Click here for tips
  • Display equations missing terminal punctuation.
  • Conditional bars written as | instead of \mid.
  • Distribution names (DM, Multinomial, Dir) as bare text in math (should use \text{}/\mbox{} or \mathrm{}).
  • Wrong/undefined sets and symbols.
  • Inconsistent notation/fonts (transpose).
  • Inline fraction \frac{…}{…} in inline math.
  • Mismatched/incorrect delimiter ordering: [\{( … ]\}].
  • Unnumbered vs numbered environments used inconsistently; labeled equation \label{eq:dm} referenced as (ref{…}) instead of \eqref{…}; or labeled without a proper reference.
  • Missing commas and periods in sentences around math; weak spacing/readability in sources.

2.3.4 Tables

If you are manually typing a LaTeX table source, think if you can generate the source. There are multiple R packages that can generate the tex source from a given dataset. See package xtable for example.

Tips on professional LaTeX tables:

  • Use tbp for floating locations; avoid h.
  • Make it self-contained with an informative caption.
  • Captions should be located above the table unless the journal specifies otherwise.
  • Avoid vertical lines.
  • Put negative signs in math mode.
  • Use better top, middle, and bottom rules from package booktabs.
  • Allow hierarchy by cmidrule().
  • Do not change font size for tables. Change table layout to fit instead of re-sizing it.
  • Right adjust numbers with decimal places.
  • Use consistent number of decimal places within a column or row of same types of measurements.
  • Avoid having many leading 0’s in decimal entries.

See Small Guide to Making Nice Tables by Markus Puschel

Perfect — this is a great place to design a “bad table” exercise so students can practice spotting and fixing formatting issues. Here’s a deliberately messy version of your table, full of bad practices (tiny font, vertical lines, inconsistent decimals, misaligned numbers, redundant symbols, etc.).

You can drop this directly into your bookdown/LaTeX as an exercise block.

Exercise 2.5 Fix the table

Below is a table showing some descriptive statistics of a case-control cohort, but typesetwith many bad practices.Your task is to identify the issues (at least 8) and then rewrite the table according to professional LaTeX table guidelines. Fix all the issues, compile, and check.

\begin{table}[h]
\caption{Table showing descriptive characteristics of the case control data.}
\centering
\tiny
\begin{tabular}{|l|c|c|c|c|}
\hline
 & Multi-record cases & Multi-record controls & Single-record cases & 
 Single-record controls \\
\hline
Total & 487.0 & 2435 & 1408.00 & 7040 \\
\hline
Sex &   &   &   &   \\
Female & 310(63.7%) & 1505 (61.8) & 952(67.61 %) & 4760 \\
Male & 177 (36.34) & 885 & 456 (32.4 %) & 2280.000 \\
\hline
Race &   &   &   &   \\
Asian & 12 & 60.00 & 27(1.9\%) & 135.000 \\
Black & 36 (7.39 \%) & 180 & 106 (7.5%) & 530 \\
Hispanic & 32 (6.57%) & 160 & 116 (8.2) & 580 \\
Other & 24 (4.93 %) & 120 & 128(9.09%) & 640 \\
White & 383 (78.64 \% ) & 1915 & 1031 (73.2\%) & 5155 \\
\hline
Age &   &   &   &   \\
10-14 & 46 (9.45) & 237 (9.7%) & 176(12.5) & 830 (11.8%) \\
15-19 & 247(50.7 \%) & 1161 & 711 (50.50) & 3449 (49) \\
20-24 & 194 (39.84\%) & 1037 & 521(37.0\%) & 2761 (39.22\%) \\
\hline
\end{tabular}
\end{table}
Click here for tips
  • Overuse of vertical lines |.
  • Inconsistent decimal places.
  • Parentheses and percentages formatted inconsistently.
  • Tiny font makes the table unreadable.
  • Caption is vague and not self-contained.
  • Numbers not aligned by decimal point.
  • Extra zeros (2280.000, 135.000).
  • Percentages outside math mode.
  • Floating specifier [h] instead of tbp.

2.3.5 Figures

Use vector graphs, not raster graphs (unless you have to, e.g., screenshots). Save the code that generates the figures so the figures can be improved easily.

Tips on LaTeX figures:

  • Use tbp for floating locations; avoid h.
  • Use LaTeX package graphicx.
  • Make it self-contained with an informative caption.
  • Captions should be located below the figure unless the journal specifies otherwise.
  • For line plots with different groups, use different line pattern to distinguish them, not only color, so that readers can tell the difference if printed in black/white. Same for different dots (symbols) on plots.
  • Use colorblind friendly colors (especially avoid red/green).
  • Keep the right aspect ratio when necessary (e.g., basketball court; map; pp-plot).
  • Remove extra margins.
  • Keep the ratio when resizing (e.g., width = \textwidth)
  • Name the figure files appropriately.

2.3.6 References

BibTeX is a reference management tool for formatting lists of references that can be used together with LaTeX to generate a reference list. Non-referenced references are not to be cited. All referenced references are to be listed. This nice feature is made possible by the package natbib. We need to collect references in BibTeX format and save them in a bib database (.bib) file. The display styles of the references are controlled by bib style (.bst) files. Many journals have their own bib style files available for download. One can construct a customized bib style easily with the help of custom-bib.

An alternative to BibTeX and natbib is biblatex. Most journals, however, use BibTeX and natbib, so we focus on that here.

A reference is cited in the manuscript through its key by \citep{} for parenthetical citations or \citet{} for textual citations, where the key is placed inside the curly brackets. The key is used to cite or cross-reference the bibliographic entry in a .tex document. Variations \citep*{} and \citet*{} prints all authors. Sometimes, \citeauthor{} and \citeyear{} can be useful when only author(s) or year is needed. The key of the cited references is put in the parentheses.

For \citep{}, multiple keys separated by commas can be put in the same parentheses for citing multiple references. Two optional arguments are allowed to \citep[][]{}. For example, \citep[see, e.g.,][p. 26]{} could be useful when a specific page (or section/chapter) is being referenced as an example.

In general, to compile a tex file with bibtex references into a pdf document, one needs to run pdflatex first, then bibtex, and then pdflatex twice to get the references correct. A simpler solution is latexmk -pdf. In my practice, I always have a Makefile and use make to smartly automate the compiling process. See, for example, Anthony’s thesis repo.

Tips on preparing BibTeX databases:

  • Devise a good naming convention for reference keys and stick to it.
  • Keep the bib database sorted and formatted tidy. (No repeated entries.)
  • Title: Capitalize first letters of notional words (not form words).
  • Use Google Scholar to get the bibtex source of a reference, but be sure to quality control the google output for missing fields and errors.
  • Protect capitalization of words with special meanings in curly braces. (e.g., {B}ayesian, {M}arkov Chain {M}onte {C}arlo)
  • Protect capitalization of initial words after a colon in titles and journals.
  • Use title style for jornal/book titles.
  • For book chapters or proceeding articles, use @incollection instead of @article, and fill the booktitle and editor fields.
  • Separate pages numbers with double dashes and no other spaces (e.g., pages = {110--118}).
  • Books need to have publisher and address fields.
  • For preprints, always check if they have been published recently.
  • Use the note field to show information that should always be shown,
  • All references without page numbers or volume number should be checked.
  • Keep bib key style consistent.

Perfect — this section lends itself naturally to a “spot the errors” exercise. Here’s a ready-to-drop exercise block you can use in your bookdown chapter:

Exercise 2.6 Cleaning Up BibTeX Entries

Below are two BibTeX entries that contain several common problems (formatting, capitalization, missing fields, inconsistent page ranges, etc.).

@article{Foygel2019,
author = {Rina Foygel Barber and Emmanuel J. Cand{\`e}s and Aaditya Ramdas and Ryan J. Tibshirani},
title = {{Predictive inference with the jackknife+}},
volume = {49},
journal = {The Annals of Statistics},
number = {1},
publisher = {Institute of Mathematical Statistics},
pages = {486--507},
year = {2021},
doi = {10.1214/20-AOS1965},
URL = {https://doi.org/10.1214/20-AOS1965}
}
@article{Kessler2019,
  title={Using EHRs to Predict Suicide Risk: Harnessing Big Data for Better Care},
  author={Kessler, Ronald C. and Hwang, Irving and Hoffmire, Claire A. and McCarthy, John F.},
  journal={American journal of psychiatry},
  volume={176},
  number={1},
  pages={19-20},
  year={2019},
  publisher={American Psychiatric Association}
}
Click here for tips
  • Are author names formatted consistently?
  • Is capitalization in titles handled correctly?
  • Are page numbers written with a single dash or double dash?
  • Should publisher appear for journal articles?
  • Are all required fields present (doi, url, etc.)?
  • Is the key (Foygel2019, Kessler2019) descriptive and consistent?

2.3.7 Cross-Referencing

Define a label for each object and refer to it by its label.

Tips on cross-referencing:

  • Devise a good naming convention for labels and stick to it.
  • Use different label prefixes for different types of objects (e.g, eq: for equations, sec: for sections, tab: for tables, fig: for figures, alg: for algorithms, etc.)
  • Labels within the source(s) for a single document must be unique.
  • Prevent referencing numbers from starting at a new line (e.g., use Table~\ref{tab:simulation}; note the tilde).
  • Watch warnings from compiling logs for undefined labels or multiply defined labels and fix them.
  • Use package xr for cross-document referencing (and labels must be unique across documents).

2.4 Command Line Interface

On Linux or MacOS, simply open a terminal.

On Windows, several options can be considered.

The new Windows OS provides a Windows Subsystem for Linux. As the name suggests, it aims to provide a Linux system on a Windows computer. It might be worth trying out.

To jump start, here is a tutorial: Ubuntu Linux for beginners.

At least, you need to know how to handle files and traverse across directories. The tab completion and introspection supports are very useful.

Here are several commonly used shell commands:

  • cd: change directory; .. means parent directory.
  • pwd: present working directory.
  • ls: list the content of a folder; -l long version; -a show hidden files; -t ordered by modification time.
  • mkdir: create a new directory.
  • cp: copy file/folder from a source to a target.
  • mv: move file/folder from a source to a target.
  • rm: remove a file a folder.