Six Useful LaTeX Packages

Here are six \LaTeX packages that, while they are perhaps not among the best known, I have found to be very useful. All of them are probably available in your \LaTeX distribution, but in case they are not I give links to the packages on CTAN (the Comprehensive TeX Archive Network). A PDF file containing a demonstration of the examples below is available here.

Mathtools

Mathtools extends the amsmath package with various additions, particularly for fine-tuning the typesetting of equations, and it also fixes a few problems with amsmath. To give just one example, the standard amsmath bmatrix environment centres its columns:

A = \begin{bmatrix}
     12 & 3  & 0 \\
     0  & 10 &-1 
   \end{bmatrix}

For matrices with negative elements, such as this one, the columns can look better right justified. The bmatrix* environment provided by mathtools allows a column alignment parameter to be given, so we can right justify the columns as follows:

A = \begin{bmatrix*}[r]
     12 & 3  & 0 \\
     0  & 10 &-1 
   \end{bmatrix*}

Unfortunately, only one alignment parameter can be given, so this command does not allow different columns to have different alignments (to achieve this, we can use the array environment instead).

The mathtools package is regularly updated.

Url

The url package provides the \url command, which acts like \verb except that it allows line breaks to be made when the argument is typeset. I use url whenever I need to typeset a URL or a path, in particular in my BibTeX bib files. I call the package with the hyphens option, so that line breaks will be allowed at hyphens. Example:

\usepackage[hyphens]{url}
...
\footnote{\url{https://icl.bitbucket.io/hpl-ai/}}
\url{http://blogs.mathworks.com/cleve/2013/01/07/george-forsythe/}

An advantage over the \verb command is that \url (or, if necessary, \urldef) can be used inside another command, such as \footnote, as in this example.

Upref

By loading the upref package you ensure that every \ref or \eqref reference is set in an upright font. This is normal typesetting practice, but it is not enforced by all \LaTeX classes. It is enforced by the SIAM class, for example.

Siunitx

The siunitx package typesets SI units according to the official rules, with just the right spacing between the number and the unit. For example, you can type

\si{kg.m/s^2}

instead of

$\mathrm{kg}\,\mathrm{m}/\mathrm{s}^2$

Even if you do not need to type SI units, you might find useful the package’s ability to round and format numbers.

Upquote

The upquote package forces left and right quotes to be typed as straight (vertical) quotes in \verb and verbatim environments. This is usually what is required in program listings. We used upquote in MATLAB Guide.

Fancyvrb

The fancyvrb package provides a more powerful replacement for the verbatim environment, allowing the font to be specified, the environment to be boxed, an external file to be inclued in a verbatim environment, and much more. Here is example that formats the contents of the environment in blue and boldface:

\begin{Verbatim}[fontsize=\small,formatcom=\color{blue}]
>> syms x, int(1/(1-x^4))
ans =
atan(x)/2 + atanh(x)/2
\end{Verbatim}

The second example includes an external file, numbers the lines, and puts horizontal lines before and after the code:

\renewcommand{\theFancyVerbLine}%
{\textcolor{red}{\small\arabic{FancyVerbLine}}}
\VerbatimInput[frame=lines,numbers=left,fontsize=\small]%
{d:/matlab/gen/gf.m}

Other packages

I have previously written about the enumitem and booktabs packages, which I also strongly recommend.

Handbook of Writing for the Mathematical Sciences, Third Edition

hwms3_cover_front.jpg

The third edition of Handbook of Writing for the Mathematical Sciences was published by SIAM in January 2020. It is SIAM’s fourth best selling book of all time if sales for the first edition (1993) and second edition (1998) are combined, and it is in my top ten most cited outputs. As well as being used by individuals from students to faculty, it is a course text on transferable skills modules in many mathematics departments. A number of publishers cite the book as a reference for recommended style—see, for example, the AMS Author Handbook, the SIAM Style Manual and, outside mathematics and computing, the Chicago Manual of Style.

Parts of the second edition were becoming out of date, as they didn’t reflect recent developments in publishing (open access publishing, DOIs, ORCID, etc.) or workflow (including modern LaTeX packages, version control, and markup languages). I’ve also learned a lot more about writing over the last twenty years.

I made a variety of improvements for the third edition. I reorganized the material in a way that is more logical and makes the book easier to use for reference. I also improved the design and formatting and checked and updated all the references.

I removed content that was outdated or is now unnecessary. For example, nowadays there is no need to talk about submitting a hard copy manuscript, or one not written in LaTeX, to a publisher. I removed the 20-page appendix Winners of Prizes for Expository Writing, since the contents can now be found on the web, and likewise for the appendix listing addresses of mathematical organizations.

I also added a substantial amount of new material. Here are some of the more notable changes.

hwms1to3spines.jpg
  • A new chapter Workflow discusses how to organize and automate the many tasks involved in writing. With the increased role of computers in writing and the volume of digital material we produce it is important that we make efficient use of text editors, markup languages, tools for manipulating plain text, spellcheckers, version control, and much more.
  • The chapter on \LaTeX has been greatly expanded, reflecting both the many new and useful packages and my improved knowledge of typesetting.
  • I used the enumitem \LaTeX package to format all numbered and bulleted lists. This results in more concise lists that make better use of the page, as explained in this blog post.
  • I wrote a new chapter on indexing at the same time as I was reading the literature on indexing and making an improved index for the book. Indexing is an interesting task, but most of us do it only occasionally so it is hard to become proficient. This is my best index yet, and the indexing chapter explains pretty much everything I’ve learned abut the topic.
  • Since the second edition I have changed my mind about how to typeset tables. I am now a convert to minimizing the use of rules and to using the booktabs \LaTeX package, as explained in this blog post.
  • The chapter Writing a Talk now illustrates the use of the Beamer \LaTeX package.
  • The book uses color for syntax highlighted \LaTeX listings and examples of slides.
  • Sidebars in gray boxes give brief diversions on topics related to the text, including several on “Publication Peculiarities”.
  • An expanded chapter English Usage includes new sections on Zombie Nouns; Double Negatives; Serial, or Oxford, Comma; and Split Infinitives.
  • There are new chapters on Writing a Blog Post; Refereeing and Reviewing; Writing a Book; and, as discussed above, Preparing an Index and Workflow.
  • The bibliography now uses the backref \LaTeX package to point back to the pages on which entries are cited, hence I removed the author index.
  • As well as updating the bibliography I have added DOIs and URL links, which can be found in the online version of the bibliography in bbl and PDF form, which is available from the book’s website.

At 353 pages, and allowing for the appendices removed and the more efficient formatting, the third edition is over 30 percent longer than the second edition.

As always, working with the SIAM staff on the book was a pleasure. A special thanks goes to Sam Clark of T&T Productions, who copy edited the book. Sam, with whom I have worked on two previous book projects, not only edited for SIAM style but found a large number of improvements to the text and showed me some things I did not know about \LaTeX.

SIAM News has published an interview with me about the book and mathematical writing and publishing.

Here is a word cloud for the book, generated in MATLAB using the wordcloud function, based on words of 6 or more characters. wordcloud2.jpg

Lists in LaTeX with the enumitem Package

\LaTeX provides the enumerate and itemize environments for numbered and itemized (usually bulleted) lists, respectively. Various package are available that provide more customizable list environments. While preparing the third edition of Handbook of Writing for the Mathematical Sciences I came across the enumitem package and ended up using it to typeset lists throughout the book.

As well as allowing all the customizations I could possibly need, enumitem has two very useful built-in options. By default, \LaTeX lists contain quite a lot of vertical space. The nosep option, used as in

\begin{itemize}[nosep]
...
\end{itemize}

(and similarly for enumerate) removes vertical spaces in the list. The wide option, used as in

\begin{itemize}[wide]
...
\end{itemize}

produces lists whose entries have zero indentation on the second and subsequent lines. Both options save space and look better to my eye, especially for a book. They can be combined by specifying [wide,nosep].

An example of a customization possible with enumitem is

\begin{enumerate}[label=X\arabic*.,ref=X\arabic*]
\item\label{item1}
...
\end{enumerate}

This enumerated list has labels X1, X2, etc., and a reference such as “see \ref{item1}" reproduces the label: “see X1”.

Description environments can also be customized (I use these very little).

enumitem_demo.jpg

For examples of the above customizations see the LaTeX file and PDF output (shown to the right) in my enumitem_demo repository on GitHub.

These examples barely scratch the surface of the customizations that enumitem makes possible. Consult the manual for full details.

For guidance on how to punctuate lists see Handbook of Writing for the Mathematical Sciences (section 3.26) or my blog post Punctuating Lists.

Better LaTeX Tables with Booktabs

One of the joys of \LaTeX is that it makes it so easy to typeset tables. I’ve created many \LaTeX tables and I’ve always taken care to fine-tune them, most often by inserting commands of the form \rule{0cm}{8pt} to stop superscripts hitting a horizontal rule in the line above.

I’ve been aware for a while of a \LaTeX package called booktabs that claims to produce more beautiful tables that more closely resemble those used in traditional typesetting. I was dissuaded from trying it by three things: the results looked rather spread out, the package discourages the use of vertical rules (which I thought I needed), and I wasn’t sure if publishers such as SIAM would allow it to be used in their journals.

I was encouraged to give booktabs a try while I was preparing the third edition of Handbook of Writing for the Mathematical Sciences. I redid the tables from the previous edition using the package and, after some experimentation, became convinced that booktabs is indeed a great aid to producing better tables.

The best way to illustrate the attractions of booktabs is with a simple example. This table is from a 2017 SIAM J. Sci. Comput. paper of which I am a co-author: table_ex1.jpg

The original table did not have the vertical rules at the sides or the horizontal rule at the bottom, but I have added them since many people include them.

Here is a revised version of the table created with booktabs:

table_ex2.jpg

The second table dispenses with all the vertical rules and adds two partial horizontal rules to demarcate the span of the pairs of columns covered by the two tol values. Notice the thicker rules at the top and bottom and the greater spacing between lines. The booktabs version of the table is more aesthetically pleasing. It is also slightly easier to typeset. The rules at the top, middle, and bottom are typed with \toprule, \midrule, and \botomrule. The subrules are typed with \cmidrule{m-n} to span columns m to n. The usage \cmidrule(lr){m-n} crops (on the left and right) the rules so that adjacent subrules do not merge.

Here is the source code for the two tables:

% First version of table.
\begin{tabular}{|l|c|c|c|c|c|l|}\hline
& \multicolumn{3}{c|}{$\tol=\tols$} & \multicolumn{3}{c|}{$\tol=\told$}\\
           & $mv$  & Rel.~err & Time    & $mv$  & Rel.~err & Time   \\\hline
\trigmv    & 11034 & 1.3e-7 & 3.9 & 15846 & 2.7e-11 & 5.6 \\
\trigexpmv & 21952 & 1.3e-7 & 6.2 & 31516 & 2.7e-11 & 8.8 \\
\trigblock & 15883 & 5.2e-8 & 7.1 & 32023 & 1.1e-11 & 1.4e1\\
\expleja   & 11180 & 8.0e-9 & 4.3 & 17348 & 1.5e-11 & 6.6 \\\hline
\end{tabular}

% Second version of table, with booktabs.
\begin{tabular}{lcccccl}\toprule
& \multicolumn{3}{c}{$\tol=\tols$} & \multicolumn{3}{c}{$\tol=\told$}
\\\cmidrule(lr){2-4}\cmidrule(lr){5-7}
           & $mv$  & Rel.~err & Time    & $mv$  & Rel.~err & Time\\\midrule
\trigmv    & 11034 & 1.3e-7 & 3.9 & 15846 & 2.7e-11 & 5.6 \\
\trigexpmv & 21952 & 1.3e-7 & 6.2 & 31516 & 2.7e-11 & 8.8 \\
\trigblock & 15883 & 5.2e-8 & 7.1 & 32023 & 1.1e-11 & 1.4e1\\
\expleja   & 11180 & 8.0e-9 & 4.3 & 17348 & 1.5e-11 & 6.6 \\\bottomrule
\end{tabular}

Despite my initial skepticism, it does seem possible to manage without vertical rules in tables. Indeed, the Chicago Manual of Style (17th edition, 2017) advises that “Vertical rules should be used sparingly—for example, when a table is doubled up … or as an aid to comprehension in an especially long or complex table”. The extra space that booktabs puts around horizontal rules makes the table nicer to look at and helps to avoid the problem of superscripts hitting the rule above. And, importantly, SIAM are happy to for authors to use booktabs in their papers.

I am now using booktabs in all my \LaTeX code.

For more before-and-after examples of tables, which illustrate table design as well as the use of booktabs, see Handbook of Writing for the Mathematical Sciences (third edition, 2020).

One booktab tip that I needed in producing the Handbook was to reduce the space at the edges of some of the widest tables by shortening the horizontal rules. This can be done by putting @{} at the beginning and end of the column formatting argument. For the example above, this is done with

\begin{tabular}{@{}lcccccl@{}}\toprule

This blog contains various other posts about \LaTeX.

Good Times in MATLAB: How to Typeset the Multiplication Symbol

The MATLAB output

>> A = rand(2); whos
  Name      Size            Bytes  Class     Attributes

  A         2x2                32  double

will be familiar to seasoned users. Consider this, however, from MATLAB R2016b:

>> s = string({'One','Two'})

s = 
  1×2 string array
    "One"    "Two"

At first sight, you might not spot anything unusual, other than the new string datatype. But there are two differences. First, MATLAB prints a header giving the type and size of the array. It does so for arrays of type other than double precision and char. Second, the times symbol is no longer an “x” but is now a multiplication symbol: “×”.

The new “times” certainly looks better. There are still remnants of “x”, for example in whos s for the example above, but I presume that all occurrences of “x” will be changed to the new symbol in the next release

However, there is a catch: the “×” symbol is a Unicode character, so it will not print correctly when you include the output in LaTeX (at least with the version provided in TeX Live 2016). Moreover, it may not even save correctly if your editor is not set up for Unicode characters.

Here is how we dealt with the problem in the third edition (published in January 2017) of MATLAB Guide. We put the code

\usepackage[utf8x]{inputenc}
\DeclareUnicodeCharacter{0215}{\ensuremath{\times}}

in the preamble of the master TeX file, do.tex. We also told our editor, Emacs, to use a UTF-8 coding, by putting the following code at the end of each included .tex file (we have one file per chapter):

%%% Local Variables:
%%% coding: utf-8
%%% mode: latex
%%% TeX-master: "do"
%%% End:

With this setup we can cut and paste output including “×” into our .tex files and it appears as expected in the LaTeX output.

Second Edition (2016) of Learning LaTeX by David Griffiths and Des Higham

What is the best way to learn \LaTeX? Many free online resources are available, including “getting started” guides, FAQs, references, Wikis, and so on. But in my view you can’t beat using a (physical) book. A book can be read anywhere. You can write notes in it, stick page markers on it, and quickly browse it or look something up in the index.

grhi16_cover.jpg

The first edition of Learning \LaTeX (1997) is a popular introduction to \LaTeX characterized by its brevity, its approach of teaching by example, and its humour. (Full disclosure: the second author is my brother.)

The second edition of the book is 25 percent longer than the first and has several key additions. The amsmath package, particularly of interest for its environments for typesetting multiline equations, is now described. I often struggle to remember the differences between align, alignat, gather, and multline, but three pages of concise examples explain these environments very clearly.

The book now reflects the modern PDF workflow, based on pdflatex as the \TeX engine. If you are still generating dvi files you should consider making the switch!

Other features new to this edition are a section on making bibliographies with Bib\TeX and appendices on making slides with Beamer and posters with the a0poster class, both illustrated with complete sample documents.

Importantly for a book to be used for reference, there is an excellent 10.5-page index which, at about 10% of the length of the book, is unusually thorough (see the discussion on index length in my A Call for Better Indexes).

The 1997 first edition was reviewed in TUGboat (the journal of the TeX Users Group) in 2013 by Boris Veytsman, who had only just become aware of the book. He says

When Karl Berry and I discussed the current situation with \LaTeX books for beginners, he mentioned the old text by Grffiths and Higham as an example of the one made “right”…

This is indeed an incredibly good introduction to \LaTeX. Even today, when many good books are available for beginners, this one stands out.

No doubt Berry and Veytsman would be even more impressed by the improved and expanded second edition.

Given that I regard myself as an advanced \LaTeX user I was surprised to learn something I didn’t know from the book, namely that in an \includegraphics command it is not necessary to specify the extension of the file being included. If you write \includegraphics{myfig} then pdflatex will search for myfig.png, myfig.pdf, myfig.jpg, and myfig.eps, in that order. If you specify

\DeclareGraphicsExtensions{.pdf,.png,.jpg}

in the preamble, \LaTeX will search for the given extensions in the specified order. I usually save my figures in PDF form, but sometimes a MATLAB figure saved as a jpeg file is much smaller.

This major update of the first edition is beautifully typeset, printed on high quality, bright white paper, and weighs just 280g. It is an excellent guide for those new to \LaTeX and a useful reference for experienced users.

Typesetting Mathematics According to the ISO Standard

In The Princeton Companion to Applied Mathematics we used the conventions that the constants e (the base of the natural logarithm) and i (the imaginary unit), and the d in derivatives and integrals, are typeset in an upright font. These conventions are part of an ISO standard, ISO 80000-2:2009. The standard is little-known, though there is an excellent article about it in TUGboat by Claudio Beccari, and Kopka and Daly’s A Guide to \LaTeX has a page on the standard (in section 7.4.10 of the fourth edition and section 5.4.10 of the third edition).

pcam_p178.jpg
An extract from The Princeton Companion to Applied Mathematics (page 178) showing the upright e, d, and i in one equation.

The standard goes into great detail about how all kinds of mathematical notation should be typeset. It is unclear how the typesetting choices were made or who was on the technical committees that made them. Nevertheless the recommendations are well thought-out.

The most interesting aspects of the standard concern the use of an upright versus a sloping font, which in practice usually amounts to roman versus italic.

  1. Variables and generic functions are written in italic. This, of course, is standard practice.
  2. Mathematical constants whose values do not change are written in roman. Thus e, i, and \pi should be in roman font. However, standard \LaTeX fonts do not have upright lower case Greek letters, so an italic \pi is unavoidable.
  3. Mathematical functions with a fixed meaning, such as exp and sin, are written in roman. Of course, \LaTeX has such definitions built in for many standard functions, but it is a common error for inexperienced users to write, for example, $sin(x)$ (giving sin(x)) instead of $\sin(x)$ (giving \sin(x)). The best way to define macros for additional functions is via \DeclareMathOperator, assuming you are using the amsmath package:

    \DeclareMathOperator{\diag}{diag}
    
  4. Mathematical operators are written in roman. This includes the d in derivatives and integrals.

Although the second and fourth of these rules are not widely followed, they are appealing in that they distinguish variable quantities from fixed ones.

There are some subtleties and some dubious cases.

  • A capital delta may appear in both forms: as an operator, hence roman, as in the forward difference operator \Delta(f) = f(x+h) - f(x); and combined with a letter to denote a variable, hence italic, as in A + \mathnormal{\Delta}A (where in \LaTeX the latter delta is typed as \mathnormal{\Delta}).
  • The ISO standard explicitly says that named polynomials, such as the Chebyshev polynomials, should be written in roman: \mathrm{T}_n(x) instead of T_n(x). This certainly follows the rules above, since such polynomials have a fixed meaning, but I have never seen the upright font being used for such polynomials in practice.

I’ve started to use rules 1–4 in my recent papers, most thoroughly in this recent EPrint on matrix functions, and intend to use them in my future writing. In doing so, I am using the following \LaTeX macros, based on those suggested in Beccari’s article.

% The number `e'.
\def\eu{\ensuremath{\mathrm{e}}}
% The imaginary unit.
\def\iu{\ensuremath{\mathrm{i}}}
% The differential operator.
\def\du{\ensuremath{\mathrm{d}}}

The \ensuremath is not essential, but it means that you can type \eu, etc., outside math mode—for example, in the phrase “the limit of this sequence is \eu”. You may want to rewrite the \def commands using \newcommand, so that if the \eu command has already been defined an error will be issued:

\newcommand{\eu}{\ensuremath{\mathrm{e}}}

With these definitions the example at the start of this article is typed as

\int_C\frac{\eu^z}{z}\,\du z = 2\pi\iu.

Note that if you are using Beamer with the recommended sans serif fonts then mathrm should be replaced by \mathsf in these definitions.

Obtaining the Standard

If you wish to download the ISO standard document from the link given at the start of this post you will be charged the princely sum of around $150 for it! If the aim of the ISO is that the standard becomes adopted then this appears counterproductive. However, it is easy to find a freely downloadable version via a Google search.

Managing BibTeX Files with Emacs

Here are a couple of tips on exploiting Emacs when working with BibTeX databases. I do not use a BibTeX database manager (though I have tried Jabref). I prefer to edit my bib files entirely within Emacs, and have had no trouble doing so even with my largest database of around 6800 entries.

1. Cleaning Downloaded Bib Entries

Back in the 1980s and 1990s BibTeX users had little choice but to create bib entries from scratch. Nowadays most journal websites have an “export citation” option that allows you to download a bib entry for a paper you are looking at. Unfortunately, these bib entries are of widely variable quality and are almost never entirely correct. What’s more, they will not match your own house style as regards ordering of fields and use of abbreviations. A great help in reformatting bib entries is the bibtex-clean-entry command in the BibTeX-mode of Emacs. I use it to

  • remove unwanted blank lines and spaces,
  • put the fields in the order I prefer,
  • change field delimiters from curly brackets to quotes,
  • delete delimiters around numerical fields,
  • change double dashes to single dashes in page ranges (BibTeX will convert single dashes to double as necessary),
  • change the entry type and field names to lower case,
  • set the indentation of field to two spaces.

These and other aspects of the formatting are customizable. Here is an example of a bib entry downloaded from JSTOR.

@article{10.2307/2323313,
 ISSN = {00029890, 19300972},
 URL = {http://www.jstor.org/stable/2323313},
 author = {Dan Scott, Donald R. Peeples},
 journal = {The American Mathematical Monthly},
 number = {7},
 pages = {651-653},
 publisher = {Mathematical Association of America},
 title = {A Constructive Proof of the Partial Fraction Decomposition},
 volume = {95},
 year = {1988}
}

After I hit C-c C-c in Emacs the entry is transformed to

@article{10.2307/2323313,
  author = "Dan Scott, Donald R. Peeples",
  title = "A Constructive Proof of the Partial Fraction Decomposition",
  journal = "The American Mathematical Monthly",
  volume = 95,
  number = 7,
  pages = "651-653",
  year = 1988,
  issn = "00029890, 19300972",
  url = "http://www.jstor.org/stable/2323313",
  publisher = "Mathematical Association of America"
        }

Further work is needed (such as replacing the comma by “and” in the author field), but the entry is now much closer to the format I require.

BibTeX-mode is not perfect. While bibtex-clean-entry can even generate a new key for the entry, I have not been able to get it to match my key-generating algorithm. And I have not found a way to make bibtex-clean-entry delete fields (such as issn, or publisher for the article type) that I do not use.

If you would like to see how I customized BibTeX-mode, take a look at the .emacs and .emacs-custom_windows files in my dot-emacs setup.

2. Bib Search and PDF Display with Helm-BibTeX

The Emacs RefTeX package provides some useful features for handling citations within a \LaTeX document, providing an intelligent link between the \LaTeX document and the relevant BibTeX databases. One thing it does not do is enable easy access to PDF files corresponding to bib entries. The Helm-BibTeX package can do this and much more.

To explain how I use Helm-BibTeX, suppose I have the following lines in my dot emacs.

(setq helm-bibtex-bibliography '("~/texmf/bibtex/bib/la.bib"
                                 "~/texmf/bibtex/bib/njhigham.bib"
                                 ))

(setq helm-bibtex-library-path '("~/pdf_papers" "~/pdf_books"))

These tell Helm-BibTeX to look in the first path for bib files and in the second path for PDF files whose names match a specified bib key.

If I type M-x helm-bibtex and type dongarra in the minibuffer then all bib entries in la.bib and njhigham.bib containing dongarra in the author or title fields are displayed, one per line. I can narrow the list down by typing a space and then another search term. Hitting tab displays several options, which include options to insert a \cite command for the item under the cursor, to insert a formatted reference for the item under the cursor, and to go to that entry in the bib file. The fourth column shows a looped square symbol (⌘) that indicates the presence of a matching PDF file. Hitting enter (or f1, or Ctrl-j) opens the PDF file in the default PDF application.

Here is Helm-BibTeX in action. helm-bibtex.jpg

Helm-BibTeX relies on the Helm package, which provides a powerful framework for incremental completion and selection narrowing.

Three BibTeX Tips

BibTeX is an important part of my workflow in writing papers and books. Here are three tips for getting the most out of it.

1. DOI and URL Links from Bibliography Entries

A digital object identifier (DOI) provides a persistent link to an object on the web, via the server at http://dx.doi.org. Most scholarly journals now assign DOIs to papers, and many papers from the past have been retrofitted with them. Books can also have DOIs, as in SpringerLink or the SIAM ebook program.

It is very convenient for a reader of a PDF document to be able to access items from the bibliography by clicking on part of the item. The links can be constructed from a DOI, and if one does not exist a URL can be used instead. How can we produce such links automatically with BibTeX? Simply add fields doi or url and use an appropriate BibTeX style (BST) file. I’m not aware of any standard BST file that handles these fields, so I modified my own BST file using these tips. The result, myplain2-doi.bst, is available in this GitHub repository. Example bib entries that work with it are as follows.

@article{ahr13,
  author = "Awad H. Al-Mohy and Nicholas J. Higham and Samuel D. Relton",
  title = "Computing the {Fr{\'e}chet} Derivative of the Matrix Logarithm
           and Estimating the Condition Number",
  journal = "SIAM J. Sci. Comput.",
  volume = 35,
  number = 4,
  pages = "C394-C410",
  year = 2013,
  doi = "10.1137/120885991",
  created = "2012.07.05",
  updated = "2013.08.06"
}

@article{hpp09,
  author = "Horn, Roger A. and Piazza, Giuseppe and Politi, Tiziano",
  title = "Explicit Polar Decompositions of Complex Matrices",
  journal = "Electron. J. Linear Algebra",
  volume = "18",
  pages = "693-699",
  year = "2009",
  url = "https://eudml.org/doc/233457",
  created = "2013.01.02",
  updated = "2015.07.15"
}

The journal in which the second example appears is one that does not itself provide DOIs or URLs for papers. However, the European Digital Mathematics Library provides URLs for this journal, so I have used the appropriate one from there.

My BST file hyperlinks the title of each item to the corresponding DOI or URL. For an example of the style in use, see the typeset version of njhigham.bib, for which here is a direct link. An alternative style is simply to print the DOI or URL with a hyperlink.

2. Web page from Bib File via BibBase

Once you have made a bib file of a group of publications a natural question is how you can automatically generate a web page that displays the publications in an easily browsable format. A great way to do this is with BibBase. You simply point BibBase at your online bib file and it generates some JavaScript, PHP, or iFrame code. When you include that code in your a web page it displays the Bib entries sorted by year, with each DOI or URL field made clickable and each BibTeX entry revealable. A menu allows sorting by author, type, or year and the list can be folded. My bib file njhigham.bib formatted by BibBase is available here.

BibBase is free to use. It was first released a few years ago and is still being developed, with improved support for LaTeX and for special characters added recently. Keep up to date with developments by following the BibBase Twitter feed.

Here are two screenshots. The first shows part of the default layout, with outputs from 2015 folded and one bib entry revealed. bibbase1.jpg

The second screenshot shows part of the list ordered by author. bibbase2.jpg

3. Bib Entry from DOI

If you happen to know the DOI of a paper and want to obtain a bib entry, go to the doi2bib service and type in your DOI. For further information see this blog post and follow the doi2bib Twitter feed.

Top Tips for New LaTeX Users

This article is aimed at relatively new \LaTeX users. It is written particularly for my own students, with the aim of helping them to avoid making common errors. The article exists in two forms: this WordPress blog post and a PDF file generated by \LaTeX, both produced from the same Emacs Org file. Since WordPress does not handle \LaTeX very well I recommend reading the PDF version.

1. New Paragraphs

In \LaTeX a new paragraph is started by leaving a blank line.

Do not start a new paragraph by using \\ (it merely terminates a line). Indeed you should almost never type \\, except within environments such as array, tabular, and so on.

2. Math Mode

Always type mathematics in math mode (as $..$ or \(..\)), to produce “y = f(x)” instead of “y = f(x)”, and “the dimension n” instead of “the dimension n”. For displayed equations use $$, \[..\], or one of the display environments (see Section 7).

Punctuation should appear outside math mode, for inline equations, otherwise the spacing will be incorrect. Here is an example.

  • Correct: The variables $x$, $y$, and $z$ satisfy $x^2 + y^2 = z^2$.
  • Incorrect: The variables $x,$ $y,$ and $z$ satisfy $x^2 + y^2 = z^2.$

For displayed equations, punctuation should appear as part of the display. All equations must be punctuated, as they are part of a sentence.

3. Mathematical Functions in Roman

Mathematical functions should be typeset in roman font. This is done automatically for the many standard mathematical functions that \LaTeX supports, such as \sin, \tan, \exp, \max, etc.

If the function you need is not built into \LaTeX, create your own. The easiest way to do this is to use the amsmath package and type, for example,

\usepackage{amsmath}
...
% In the preamble.
\DeclareMathOperator{\diag}{diag}  
\DeclareMathOperator{\inert}{Inertia}

Alternatively, if you are not using the amsmath package you can type

\def\diag{\mathop{\mathrm{diag}}}

4. Maths Expressions

Ellipses (dots) are never explicitly typed as “…”. Instead they are typed as \dots for baseline dots, as in $x_1,x_2,\dots,x_n$ (giving x_1,x_2,\dots,x_n) or as \cdots for vertically centered dots, as in $x_1 + x_2 + \cdots + x_n$ (giving x_1 + x_2 + \cdots + x_n).

Type $i$th instead of $i'th$ or $i^{th}$. (For some subtle aspects of the use of ellipses, see How To Typeset an Ellipsis in a Mathematical Expression.)

Avoid using \frac to produce stacked fractions in the text. Write n^3/3 flops instead of \frac{n^3}{3} flops.

For “much less than”, type \ll, giving \ll, not <<, which gives <<. Similarly, “much greater than” is typed as \gg, giving \gg. If you are using angle brackets to denote an inner product use \langle and \rangle:

  • incorrect: <x,y>, typed as $<x,y>$.
  • correct: \langle x,y \rangle, typed as $\langle x,y \rangle$

5. Text in Displayed Equations

When a displayed equation contains text such as “subject to x \ge 0”, instead of putting the text in \mathrm put the text in an \mbox, as in \mbox{subject to $x \ge 0$}. Note that \mbox switches out of math mode, and this has the advantage of ensuring the correct spacing between words. If you are using the amsmath package you can use the \text command instead of \mbox.

Example

$$
      \min\{\, \|A-X\|_F: \mbox{$X$ is a correlation matrix} \,\}.
$$

6. BibTeX

Produce your bibliographies using BibTeX, creating your own bib file. Note three important points.

  • “Export citation” options on journal websites rarely produce perfect bib entries. More often than not the entry has an improperly cased title, an incomplete or incorrectly accented author name, improperly typeset maths in the title, or some other error, so always check and improve the entry.
  • If you wish to cite one of my papers download the latest version of njhigham.bib (along with strings.bib supplied with it) and include it in your \bibliography command.
  • Decide on a consistent format for your bib entry keys and stick to it. In the format used in the Numerical Linear Algebra group at Manchester a 2010 paper by Smith and Jones has key smjo10, a 1974 book by Aho, Hopcroft, and Ullman has key ahu74, while a 1990 book by Smith has key smit90.

7. Spelling Errors and \LaTeX Errors

There is no excuse for your writing to contain spelling errors, given the wide availability of spell checkers. You’ll need a spell checker that understands \LaTeX syntax.

There are also tools for checking \LaTeX syntax. One that comes with TeX Live is lacheck, which describes itself as “a consistency checker for LaTeX documents”. Such a tool can point out possible syntax errors, or semantic errors such as unmatched parentheses, and warn of common mistakes.

8. Quotation Marks

\LaTeX has a left quotation mark, denoted here \lq, and a right quotation mark, denoted here \rq, typed as the single left and right quotes on the keyboard, respectively. A left or right double quotation mark is produced by typing two single quotes of the appropriate type. The double quotation mark always itself produces the same as two right quotation marks. Example: ``hello'' is typed as \lq\lq hello \rq\rq.

9. Captions

Captions go above tables but below figures. So put the caption command at the start of a table environment but at the end of a figure environment. The \label statement should go after the \caption statement (or it can be put inside it), otherwise references to that label will refer to the subsection in which the label appears rather than the figure or table.

10. Tables

\LaTeX makes it easy to put many rules, some of them double, in and around a table, using \cline, \hline, and the | column formatting symbol. However, it is good style to minimize the number of rules. A common task for journal copy editors is to remove rules from tables in submitted manuscripts.

11. Source Code

\LaTeX source code should be laid out so that it is readable, in order to aid editing and debugging, to help you to understand the code when you return to it after a break, and to aid collaborative writing. Readability means that logical structure should be apparent, in the same way as when indentation is used in writing a computer program. In particular, it is is a good idea to start new sentences on new lines, which makes it easier to cut and paste them during editing, and also makes a diff of two versions of the file more readable.

Example:

Good:

$$
U(\zbar) = U(-z) = 
            \begin{cases}
                -U(z),   & z\in D, \\ 
                -U(z)-1, & \mbox{otherwise}.
            \end{cases}
$$

Bad:

$$U(\zbar) = U(-z) = 
\begin{cases}-U(z),   & z\in D, \\ 
-U(z)-1, & \mbox{otherwise}.
\end{cases}$$

12. Multiline Displayed Equations

For displayed equations occupying more than one line it is best to use the environments provided by the amsmath package. Of these, align (and align* if equation numbers are not wanted) is the one I use almost all the time. Example:

\begin{align*}
  \cos(A) &= I - \frac{A^2}{2!} + \frac{A^4}{4!} + \cdots,\\
  \sin(A) &= A - \frac{A^3}{3!} + \frac{A^5}{5!} -  \cdots,
\end{align*}

Others, such as gather and aligned, are occasionally needed.

Avoid using the standard \LaTeX environment eqnarray, because it doesn’t produce as good results as the amsmath environments, nor is it as versatile. For more details see the article Avoid Eqnarray.

13. Synonyms

This final category concerns synonyms and is a matter of personal preference. I prefer \ge and \le to the equivalent \geq \leq\ (why type the extra characters?).

I also prefer to use $..$ for math mode instead of \(..\) and $$..$$ for display math mode instead of \[..\]. My preferences are the original \TeX syntax, while the alternatives were introduced by \LaTeX. The slashed forms are obviously easier to parse, but this is one case where I prefer to stick with tradition. If dollar signs are good enough for Don Knuth, they are good enough for me!

I don’t think many people use \LaTeX‘s verbose

\begin{math}..\end{math}

or

\begin{displaymath}..\end{displaymath}

Also note that \begin{equation*}..\end{equation*} (for unnumbered equations) exists in the amsmath package but not in in \LaTeX itself.