-
Notifications
You must be signed in to change notification settings - Fork 0
/
latex-writing.html
172 lines (153 loc) · 10.2 KB
/
latex-writing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Damien Couroussé - Suggestions for improving scientific writings and the use of LaTeX</title>
<meta name="description" content="damien dot courousse dot fr">
<meta name="author" content="Damien Couroussé">
<link rel="stylesheet" href="https://unpkg.com/[email protected]/build/pure-min.css">
<!--[if lte IE 8]>
<link rel="stylesheet" href="/assets/css/side-menu-old-ie.css">
<![endif]-->
<!--[if gt IE 8]><!-->
<link rel="stylesheet" href="./assets/css/side-menu.css">
<!--<![endif]-->
<link rel="stylesheet" href="./assets/css/main.css">
<link rel="stylesheet" href="./assets/css/img-overlay.css">
</head>
<body>
<div id="layout">
<!-- Menu toggle -->
<a href="#menu" id="menuLink" class="menu-link">
<!-- Hamburger icon -->
<span></span>
</a>
<div id="menu">
<div class="pure-menu pure-menu-open">
<a class="pure-menu-heading" href="./index.html">Home</a>
<ul class="pure-menu-list">
<li class="pure-menu-item">
<a href="./publications.html" class="pure-menu-link">Publications</a>
</li>
<!-- <li class="pure-menu-item"> -->
<!-- <a href="/posts.html" class="pure-menu-link">Posts</a> -->
<!-- </li> -->
<!-- <li class="pure-menu-item"> -->
<!-- <a href="/sw.html" class="pure-menu-link">Software</a> -->
<!-- </li> -->
<!-- <li class="pure-menu-item"> -->
<!-- <a href="/expressions-urbaines.html" -->
<!-- class="pure-menu-link">Expressions urbaines</a> -->
<!-- </li> -->
</ul>
</div>
</div> <!-- /menu -->
<div id="main">
<div class="header">
<h1>Suggestions for improving scientific writings and the use of LaTeX</h1>
</div>
<div class="content">
<div class="pure-g">
<div class="pure-u-1">
<p>In this page, I humbly share a summary of the <em>things</em> that I frequently report to my co-authors. Many of those <em>things</em> could be called <em>errors</em>, while some others may be considered as a matter of taste.</p>
<h2>Some frequent LaTeX mistakes</h2>
<h3>Use of non-breaking spaces</h3>
<p>Add an non-breaking space (<code>~</code>) in front of most <code>\cite{…}</code>, <code>\page{…}</code>, etc. For example:</p>
<pre class="example"><code>Warren~\cite{Warren1965} was the first to…
See figure~\ref{fig:test} on page~\pageref{fig:test}.
</code></pre>
<p>Reference: <a href="https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing" class="uri">https://en.wikibooks.org/wiki/LaTeX/Labels_and_Cross-referencing</a></p>
<h2>Compatibility with Version Control Systems</h2>
<h3>Write each sentence <em>on a single text line</em></h3>
<ul>
<li>It helps to keep track of word changes across revisions.</li>
<li>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.</li>
</ul>
<h3>Editor settings</h3>
<ol>
<li><p>Don't use your editor's reformatting tools</p>
<p>See my point above about the use of single text lines for each sentence.</p>
<p>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.</p>
<p>For example, considering this short example:</p>
<pre class="example"><code>This section presents the existing works that investigate approaches
to evaluate...
</code></pre>
<p>… Adding the word <em>new</em> to the sentence, combined with editor formatting, modifies <em>two</em> text lines where a single word was actually modified in the text.</p>
<pre class="example"><code>This section presents the existing works that investigate new
approaches to evaluate...
</code></pre>
<p>The addition of one word, if combined with text reformatting, let's a VCS (e.g., git) report that <em>two</em> text lines were modified:</p>
<pre class="example"><code>$ 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...
</code></pre>
<p>If the sentence is kept in one single text line, git diff correctly reports a single change:</p>
<pre class="example"><code>- This section presents the existing works that investigate approaches to evaluate...
+ This section presents the existing works that investigate new approaches to evaluate...
</code></pre>
<p>Nota: <code>git diff</code> 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.</p>
<pre class="example"><code>$ git diff --word-diff
This section presents the existing works that investigate {+new+} approaches to evaluate...
</code></pre></li>
<li><p>Delete trailing spaces</p>
<p>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.</p>
<p>Emacs can be configured as follows:</p>
<pre class="elisp"><code>; 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)
</code></pre>
<p>If you know how to configure <a href="https://www.tug.org/texworks/">TeXworks</a> so that it automatically deletes trailing spaces, please let me know!</p></li>
</ol>
<h2>Typography</h2>
<h3>in French</h3>
<p>For the French typography, read the <a href="https://catalogue.bnf.fr/ark:/12148/cb38887921n.public">Lexique des règles typographiques en usage à l'Imprimerie nationale</a>.</p>
<p>Non-breaking spaces (<code>~</code> in LaTeX) are required before many punctuation marks, e.g., <code>?</code>, <code>!</code>, <code>:</code>, <code>;</code>, <code>»</code> (hence, also after <code>«</code>). For example, you would write in LaTeX: <code>«~Salut, la compagnie~!~»</code></p>
<p>The <code>babel</code> package, if correctly configured, is usually able to manage the use of non-breaking spaces automatically for you, but YMMV.</p>
<p>For LaTeX black-belts: <code>\,</code> inserts a <em>thinspace</em>, which is also non-breaking. Mostly used for math notations. LaTeX supports a plethora of different white spaces.</p>
<h3>in English</h3>
<p>For the English typography and many other topics related to writing, read the <a href="https://www.pearson.com/us/higher-education/product/Fowler-Little-Brown-Handbook-The-14th-Edition/9780134759722.html">Little, Brown Handbook</a>.</p>
<p>English does <em>not</em> use non-breaking spaces before punctuation marks. For example, you would write in LaTeX: <code>"Hello, World!"</code>.</p>
<p>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 <code>'\ '</code> (without the surrounding quotation marks) in LaTeX to enforce the use of the space character. For example: <code>'e.g.\ '</code> (although some manuals of style require the use of a comma after 'e.g.' or 'i.e.').</p>
<h2>Writing style</h2>
<p>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.</p>
<p>I recommend these two excellent books, frequently re-edited and revised:</p>
<p><em>Fowler, H. R., Aaron, J. E., & McArthur, M. (1992). The little, brown handbook. Pearson.</em></p>
<p><em>The Chicago Manual of Style, 17th edition (2017). University of Chicago Press.</em></p>
<h3>Don’t use adverbs</h3>
<p>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.</p>
<p>If you <em>really</em> need an adverb, think about it twice.</p>
<p>Adjectives are likely to receive the same treatment.</p>
<h3>Jargon consistency</h3>
<p>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.</p>
<h2>Use a grammar checker</h2>
<p>Most LaTeX editors do not support grammar checking. Or maybe, most users of LaTeX editors do not use grammar checking. I don't know.</p>
<h2>Use a spell checker</h2>
<p>Period.</p>
</div>
</div> <!-- pure-g -->
</div> <!-- /content -->
</div> <!-- /main -->
<footer id="footer">
<div class="footer">
<p style="text-align:center; font-size:75%">
Site generated by <a href="https://jaspervdj.be/hakyll">Hakyll</a>
and <a href="https://pandoc.org">pandoc</a>
</p>
<p style="text-align:center; font-size:75%">
<a href="https://github.com/damiencourousse/website/commits/master">
Page last modified
by commit 9475555,
Thu, 4 Jul 2024 22:17:01 +0200
</a>
</p>
<br>
</div>
</footer>
</div> <!-- /layout -->
<script src="./assets/js/ui.js"></script>
</body>
</html>