latex-writing

-- ispell-dictionary: "english" -- — title: Suggestions for improving scientific writings and the use of LaTeX —

In this page, I humbly share a summary of the things that I frequently report to my co-authors. Many of those things could be called errors, while some others may be considered as a matter of taste.

Some frequent LaTeX mistakes

Use of non-breaking spaces

Add an non-breaking space (~) in front of most \cite{…}, \page{…}, etc. For example:

Warren~\cite{Warren1965} was the first to…

See figure~\ref{fig:test} on page~\pageref{fig:test}.

Reference: https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing

Compatibility with Version Control Systems

Write each sentence on a single text line

  • It helps to keep track of word changes across revisions.
  • A long text line probably indicates that the sentence is too long and needs to be written differently. The practice of using one text line for each sentence helps identifying text structures that may need some simplification.

Editor settings

  1. Don't use your editor's reformatting tools

    See my point above about the use of single text lines for each sentence.

    Many editors can automatically reformat long text lines in a nicely formatted paragraph of text (in emacs, this is called word wrapping). You should disable this feature when editing versioned documents, because it may introduce unwanted changes in the versioning history.

    For example, considering this short example:

    This section presents the existing works that investigate approaches
to evaluate...

    … Adding the word new to the sentence, combined with editor formatting, modifies two text lines where a single word was actually modified in the text.

    This section presents the existing works that investigate new
approaches to evaluate...

    The addition of one word, if combined with text reformatting, let's a VCS (e.g., git) report that two text lines were modified:

    $ git diff
- This section presents the existing works that investigate approaches
- to evaluate...
+ This section presents the existing works that investigate new
+ approaches to evaluate...

    If the sentence is kept in one single text line, git diff correctly reports a single change:

    - This section presents the existing works that investigate approaches to evaluate...
+ This section presents the existing works that investigate new approaches to evaluate...

    Nota: git diff provides an option to highlight changed words instead of changed lines. The output is more readable with color output (not illustrated here). However, I suggest not to rely on this option of git, because all your co-authors may not be aware of this option, and they will probably not use the same git client.

    $ git diff --word-diff
This section presents the existing works that investigate {+new+} approaches to evaluate...

  2. Delete trailing spaces

    It is a common practice to delete trailing spaces in versioned documents. Here's why. Say A commits changes in a file, with trailing spaces left. Later, B adds some changes, but B's editor automatically deletes trailing spaces. The version control tool will attribute extra changes to B only because of the deletion of trailing spaces! This will make the change look bigger than it is in reality, and the real modifications of the document will be difficult to track because of the noise added.

    Emacs can be configured as follows:

    ; show trailing white-spaces
(setq-default show-trailing-whitespace t)
; delete trailing spaces when saving the file
(add-hook 'before-save-hook 'delete-trailing-whitespace)

    If you know how to configure TeXworks so that it automatically deletes trailing spaces, please let me know!

Typography

in French

For the French typography, read the Lexique des règles typographiques en usage à l'Imprimerie nationale.

Non-breaking spaces (~ in LaTeX) are required before many punctuation marks, e.g., ?, !, :, ;, » (hence, also after «). For example, you would write in LaTeX: «~Salut, la compagnie~!~»

The babel package, if correctly configured, is usually able to manage the use of non-breaking spaces automatically for you, but YMMV.

For LaTeX black-belts: \, inserts a thinspace, which is also non-breaking. Mostly used for math notations. LaTeX supports a plethora of different white spaces.

in English

For the English typography and many other topics related to writing, read the Little, Brown Handbook.

English does not use non-breaking spaces before punctuation marks. For example, you would write in LaTeX: "Hello, World!".

In English, the white space following the full stop at the end of a sentence is longer than other spaces between words. LaTeX automatically takes care of that for you. Other situations where a dot is used usually require a normal space, which is annotated '\ ' (without the surrounding quotation marks) in LaTeX to enforce the use of the space character. For example: 'e.g.\ ' (although some manuals of style require the use of a comma after 'e.g.' or 'i.e.').

Writing style

There are many good resources about writing style. My writings are probably not exemplary with regards to writing style, but I suggest here a few things that are not given enough care.

I recommend these two excellent books, frequently re-edited and revised:

Fowler, H. R., Aaron, J. E., & McArthur, M. (1992). The little, brown handbook. Pearson.

The Chicago Manual of Style, 17th edition (2017). University of Chicago Press.

Don’t use adverbs

Most of the time, adverbs do not contain useful information, and can be removed without changing the meaning of the text. In many cases, it is better is to think about a more expressive verb, or to write differently the sentence.

If you really need an adverb, think about it twice.

Adjectives are likely to receive the same treatment.

Jargon consistency

Check the consistent use of every term in the paper. You should use only one word for each use of the same meaning in the whole document. If you need two ore more words, make it clear to the reader that they mean different things, albeit close or related.

Use a grammar checker

Most LaTeX editors do not support grammar checking. Or maybe, most users of LaTeX editors do not use grammar checking. I don't know.

Use a spell checker

Period.