Notes on using LaTeX for manuscripts: Difference between revisions

Latest revision as of 12:40, 28 May 2024

This is not a LaTeX manual. Instead, it is a list of topics that have come up repeatedly within our lab in the preparation of manuscripts.

Learning more about LaTeX

Leslie Lamport's LaTeX manual (available in the lab)
Kopka and Daly's Guide to LaTeX (available in the lab)
The Not So Short Introduction to LaTeX 2ε

General advice

Use a LaTeX-aware editor. A particularly powerful combination is Emacs + AUCTeX.
GNU Emacs for OS X can be downloaded here. (Note: if you wish to use this OS X version from the command line, add this line to ~/.bashrc or ~/.profile: alias emacs='/Applications/Emacs.app/Contents/MacOS/Emacs')
It is convenient to use a PDF viewer that can reload a PDF file without restarting. On OS X, Skim can detect automatically whether a LaTeX file has been recompiled. On Linux, Okular does the same, and is generally an excellent and fast program for viewing and marking PDF files. On Linux, Acrobat offers the Ctrl-R command for reloads (remarkably, this functionality seems not to be available in the OS X and Windows versions of the same program).
Make sure to keep your LaTeX file cleanly formatted (i.e., human readable). When using AUCTeX (see above), take advantage of the LaTeX-aware paragraph rewrapping command (alt-q). Take particular care with equations, and use line breaks and proper indentation to keep the LaTeX source readable (similar to what you would do when writing code). This makes it much easier to modify an equation later.

Formatting

Understand the difference between an end-of-sentence period and a period used in an abbreviation, and how LaTeX distinguishes these. A period after a lower-case letter is assumed to be the end of a sentence, and LaTeX needs to be told if this is not the case. So, 'et al.' must be typed as 'et al.\' unless it occurs at the end of a sentence (or immediately before a comma). This is typically not true for 'i.e.' and 'e.g.' because those two abbreviations (at least in American English) are always followed by a comma: 'i.e.,' and 'e.g.,'
On the other hand, a period after a capital is assumed to be not the end of a sentence, and only needs special treatment if it actually is. Those cases are rare; a typical example would be the sentence 'See model A.' which must be entered as 'See model A\@.'
Note that the bibliography environment is exempt from these rules, so it is not necessary to write the '\' in 'Phys.\ Rev.\ Lett.\' (unless you use such a journal reference in the main text of your document). Of course, in practice, you should use BibTeX (see below) instead of creating a bibliography environment by hand.
It is good form to avoid line breaks that result in an isolated number at the beginning of a line. This can be achieved via the '~' symbol, which yields a non-breaking space. Thus, make it a habit to write
```
See Eq.~\ref{eq:gauss}.
```
Note how this also eliminates the need to insert a '\' after 'Eq.' (cf. previous point)
However, a combination of numbers at the beginning of a line is acceptable. So if you refer to multiple numbered equations or figures at once, it is only necessary to suppress a line break before the last number. Thus, one writes
```
See Eqs.\ \ref{eq:2d} and~\ref{eq:3d}.
```
Note that a '\' is now required after 'Eqs.'
Likewise, suppress line breaks before citations,
```
The FFT method~\cite{gauss1805,cooley1965} is widely used in ...
```
(Distracting side note to reader: learn how Gauss presumably invented the FFT in 1805.)

In the spirit of the previous point, note that you should write

The parameter~$\alpha$ indicates ...

but

The parameters $\alpha$ and~$\beta$ indicate ...

An easy way to enclose equation numbers in parentheses is the \eqref{} command, which is part of the amsmath package (invoked via \usepackage{amsmath}):
```
See Eq.~\eqref{eq:gauss}.
```
For labels of equations, figures, section, tables, choose names that start with 'eq:', 'fig:', 'sec:', 'tab:', respectively. Also, use descriptive labels. Labels of the form \label{eq:3} or \label{figure1} are poor choices.
Placement of labels: In a single displayed equation, put the \label command on the line immediately before the \end{equation} command. In a figure environment, place the label command immediately after the \caption{} command (not within the caption, and certainly not before it). For sections, place the label on a separate line, directly after the \section{} command.
Sentences cannot start with an abbreviation. Write 'Eq.', 'Fig.','Ref.', 'Sec.' in full. Replace 'E.g.,' at the beginning of a sentence with 'For example'. (Exception: Nature leaves 'Eq.', 'Fig.', 'Ref.', 'Sec.' abbreviated.)
In general, displayed equations should be a grammatical part of the sentence. Avoid constructs like '...as shown in the following equation:'
This also implies that proper punctuation must be used in displayed equations. To avoid that a period or comma after a displayed equation is too close to the equation, insert a small space via '\;'. Thus, a proper construct would be:
```
the mass increases quadratically with time,
\begin{equation}
   m = t^2 \;.
\end{equation}
```
In journals that use superscript-style references (e.g., Journal of Chemical Physics), references that are a grammatical part of the sentence are not written in superscript. Use the \onlinecite command for this. For example: See Ref.~\onlinecite{somepaper}.
Two equivalent entities are separated by an 'n-dash' instead of a hyphen. This is achieved via '--'. For example:
```
Poisson--Boltzmann theory
particle--hole symmetry
```
A notable exception is 'Lennard-Jones', which is a single hyphenated name.
If you use \sim to indicate 'approximately,' the spacing will be wrong, since LaTeX treats sim as a binary operator. This is solved by enclosing it in braces:
```
${\sim}10$
```
Alternatively, you can define a new command in the preamble
```
\newcommand{\unsim}{\mathord{\sim}} % \sim as a unary operator
```
Symbols and letters that serve as mathematical variables must always be italicized. On the other hand, labels and any other explicative text should be written in non-italicized, non-mathematical form (this means using \mathrm if inside a math environment).
Side note: The previous point also applies to any figures in the manuscript. Since the Symbol-Oblique font is not widely available, you may want to use the following method for italicizing Greek symbols: Open the figure in Adobe Illustrator, select the character and then choose "Transform -> Shear" and shear by 10 degrees, horizontally, to manually italicize the character.

Figures

To include figures, in the preamble of your document use the command

\usepackage{graphicx}

Each figure is then included via

\includegraphics[width=\figurewidth]{somefigure}

Ideally, the figure should be scalable, so an Encapsulated Postscript ('.eps') file if you use LaTeX followed by dvips, or a PDF file if you use pdflatex. To facilitate switching between those programs, do not include the filename extension in the \includegraphics{} command, so, e.g., do not write \includegraphics{somefigure.pdf}.
Also, note that in this example the width of the figure is specified via a macro, defined in the preamble of the LaTeX file via

\newcommand{\figurewidth}{0.4\textwidth}

This makes it easy to resize all the figures in a document at once.

Finally, note that it is convenient to organize all figures in a subfolder (e.g., Figures), and then use \includegraphics{Figures/somefigure}. However, there is a command that makes this even cleaner: in the preamble, right after the \usepackage{graphicx} command, include

\graphicspath{{Figures/}}

Then, you can simply use \includegraphics{somefigure} and LaTeX will search for somefigure in the folder Figures. This has the added benefit that you can change the location of all figures by changing a single statement in the LaTeX file.

Commonly used style packages

For extensive additional options to format equations, use the AMS-LaTeX package. Detailed documentation. Add the following command to the preamble:
```
\usepackage{amslatex}
```
Note: when using RevTeX (see Physical Review Letters or Journal of Chemical Physics below), specify the amslatex option in the \documentclass command instead.
The MathTime and MathTime Plus font packages allow the use of the Times Roman typeface along with matching math fonts. Add the following commands to the preamble:
```
\usepackage[mtbold,subscriptcorrection]{mathtime}
\usepackage[mathcal]{mathpi}
```
Note: when using this with the SIAM document class, omit the subscriptcorrection keyword.

BibTeX

Instead of entering references for each paper separately, we use BibTeX. This offers several advantages:

References are sorted automatically in the order in which they are cited (or alphabetically, if a journal style calls for it).
No need to enter references more than once.
No need to manually (re)format references to comply with the style of the journal.
Fixes to incorrect references will actually propagate to future manuscripts.

In BibTeX, references are entered as records in a database, and BibTeX extracts the references from that database, formats them for the appropriate journal, and compiles them in a properly sorted list (the '.bbl' file).

Detailed instructions can be found online or in the LaTeX manual by Lamport (copy available in the lab). Here we only discuss a few points specific to our usage.

We have several databases (.bib files), approximately divided by topics ('colloids.bib', 'polyelectrolytes.bib', etc.). We also have one database that only contains macros for journal names ('journals.bib').
At the end of the document, there will be just two commands:
```
\bibliographystyle{journalstyle}
\bibliography{journals,polyelectrolyte,colloids}
```
('polyelectrolyte' and 'colloids' are just examples of databases)
The 'journalstyle' is a style file ('.bst' file) that imposes the journal-specific formatting rules. Many journals provide such a style file. For other cases (specifically, Acta Materialia, Biophysical Journal, Journal of Polymer Science) we have produced our own style files. When using a journal-specific LaTeX style package (RevTeX for APS journals, achemso for ACS journals), the \bibliographystyle{} command can be omitted.
When entering a new record into a database, always include the article title, even when using the reference in a journal that will not show that title. Someone else later may need to cite the same reference in a situation where the title will be required (including NSF proposals).
Titles in records must be entered using the original capitalization. Certain journal styles will alter this capitalization (e.g., only allowing the first character to be capitalized instead of each noun). To exempt certain elements from such rules, encloses them in {}. Examples are:
- Names
- Abbreviations, such as 'DNA'
- Roman numerals indicating that an article is part of a series
- The first character after a colon
Thus, examples of properly recorded titles are:
```
title = "Monte {C}arlo Study of {DNA}"
title = "Efficient simulation of phase transitions, part {I}"
title = "History of computer simulations: {M}olecular dynamics"
```
Note: do not simply enclose the entire title in {} to suppress any alteration of the capitalization.
Enter mathematical symbols, as well as subscript and superscripts, in titles using LaTeX notation.
The typical choice for the 'key' (label with which you refer to a reference) is 'johnson76', i.e., last name of the first author in all lower case, followed by the last two digits of the year. If that key is already taken, append lower case 'a', 'b', etc.
Put all your .bib files in a separate folder (instead of keeping multiple copies of them, e.g., in different article folders). BibTeX will find them if you set the "BIBINPUTS" environment variable using the following line:
```
export BIBINPUTS=$HOME/Documents/tex/bib//:
```
Of course, the actual value should reflect the location of your .bib files. Note the double '//' at the end, which means that also subfolders of "$HOME/Documents/tex/bib" will be searched. Moreover, the trailing ':' means that BibTeX will also search all default folders, after it has searched "$HOME/Documents/tex/bib" and subfolders. Place this line in your ~/.bashrc file (on Linux) or your ~/.zprofile file (on MacOS, assuming you use the default zsh).
Most likely, you will only use the BibTeX style files that are stored in a central location on our group file system (and that will be search automatically by BibTeX). However, if you have additional personal style files, or if you want to create a folder with style files on your laptop, you can use another environment variable for that:
```
export BSTINPUTS=$BSTINPUTS:$HOME/tex/bib/Styles:
```
The syntax is identical to what is described above for BIBINPUTS. But note how "$BSTINPUTS" appears on the right-hand side; this is to ensure that you will first search our group's default style files.

Practical work-flow notes

Comparing different versions of a manuscript: Use diff and wdiff.
Use a LaTeX-aware spell checker, such as Ispell. Note: on some Linux systems (such as Ubuntu 14.04) this seems to have been compiled without the option to show the "mini menu" by default. This is fixed easily by invoking 'ispell -M'.

Journal-specific notes

Physical Review Letters

Use RevTeX 4.2 (available on all desktop machines via /usr/local):
```
\documentclass[aps,prl,reprint,showpacs,floatfix]{revtex4-2}
```
Abstract should be 600 characters or less.
Section selection in PRL is determined by the first PACS number, so choose accordingly. Most CSML papers should go to section L6 or L8. Do not choose a general category (starting with '0') as the first PACS number.
Prior to submission:
- Replace the reprint option in the \documentclass{} command with preprint
- Rerun LaTeX on this file twice
- Comment out the \bibliography{} command
- Insert the '.bbl' file into the LaTeX file
- Note that EPS figures are no longer required; PDF format is permitted

Biophysical Journal

Journal of Chemical Physics

Invoke RevTeX 4.2 (available on all desktop machines via /usr/local):
```
\documentclass[aip,jcp,citeautoscript,amsmath]{revtex4-2}
```
The citeautoscript option will automatically convert citations of the style
some sentence [2,3].
to
some sentence.^2,3
Note the location of the punctuation. Thus, simply enter all references as you would for inline style citations; it will automatically be arranged correctly. The only exception is a citation that you refer to explicitly, see LaTeX notes.
Prior to submission:
- Add the preprint option to the \documentclass{} command
- Rerun LaTeX on this file twice
- Comment out the \bibliography{} command
- Insert the '.bbl' file into the LaTeX file

Nano Letters

Use the achemso package (available on all desktop machines via /usr/local):

\documentclass[journal=nalefd,manuscript=letter,layout=twocolumn]{achemso}

Abstract should be 75 words or less. UPDATE: The latest guidelines put the limit at a rather unfathomable 4000 characters (this amounts to approximately one printed page) - I do not recommend trying this.

Nature

See note on abbreviations.

SIAM journals

Use the SIAM macros (available on the desktop machines via /usr/local):
```
\documentclass[final,letterpaper]{siamltex1213}
```
SIAM style requires equations to be written simply as stand-alone numbers (so without 'Eq.' before it), enclosed in parentheses. Only at the beginning of a sentence and in situations where there may be confusion, the word 'equation' is inserted in full. See SIAM Style Manual, Section 3.4.
According to SIAM style, in-text references are written as stand-alone numbers, i.e., it is proper to write 'see [19]' (SIAM Style Manual, Section 15.5).
The SIAM BibTeX style file (siam.bst)
- as provided on the SIAM website (version 01/24/1988) does not properly abbreviate first names of authors; this is fixed in the 01/29/1988 version distributed with TeXLive (i.e., standard on Linux and OS X).
- provides numerical citations but sorts them alphabetically---this gives a cluttered impression in the main text, and is not required per SIAM style; this is fixed in siam-el.bst.
Figures must be in EPS format.
Select 3-4 categories from the AMS subject classicifation.

NSF proposals

Text fonts: The Grant Proposal Guide permits Computer Modern (at least 11pt), but I find this both unattractive and not very legible, so instead opt to use Times New Roman (11pt). Note that this is not identical to Times. INSTALLATION NOTES FOLLOW SOON
Math fonts: The math fonts that I use to accompany Times New Roman are the Mathtime Professional 2 fonts. The limited Lite set can be downloaded for free. INSTALLATION NOTES FOLLOW SOON
Titles are required for all cited articles. Use BibTeX style erik_title_doublespace.
Use these styles files. After installing these, you only need to invoke
```
\usepackage{nsf-settings}
```
Whereas these style files set the proper margins, note that NSF allows absolutely no text to appear in the margin, so you need to be "fanatical" about overfull \hbox warnings. (This also holds for the reference section!)