├── README.md └── schema.bib /README.md: -------------------------------------------------------------------------------- 1 | # Advice for writing LaTeX documents 2 | 3 | - [Introduction](#introduction) 4 | - [Put the document under version control](#put-the-document-under-version-control) 5 | - [Write readable and maintainable LaTeX source code](#write-readable-and-maintainable-latex-source-code) 6 | - [Automate the document's build](#automate-the-document-build) 7 | - [Use continuous integration](#use-continuous-integration) 8 | - [Automate the management of bibliographic references](#automate-the-management-of-bibliographic-references) 9 | - [Use style files](#use-style-files) 10 | - [Use third-party LaTeX packages](#use-third-party-latex-packages) 11 | - [Avoid explicit formatting](#avoid-explicit-formatting) 12 | - [Use symbolic references](#use-symbolic-references) 13 | - [Mathematics](#mathematics) 14 | - [Number and unit formatting](#number-and-unit-formatting) 15 | - [Tables](#tables) 16 | - [Figures](#figures) 17 | - [Floats](#floats) 18 | - [Typography](#typography) 19 | - [LaTeX formatting](#latex-formatting) 20 | - [Writing](#writing) 21 | - [Additional material regarding LaTeX](#additional-material-regarding-latex) 22 | - [Material on writing and presenting information](#material-on-writing-and-presenting-information) 23 | - [License](#license) 24 | 25 | 26 | ## Introduction 27 | If you're writing a scientific book, a paper, or a thesis in 28 | computer science, engineering, mathematics, physics or a related 29 | field, it pays to write it using [LaTeX](https://www.latex-project.org/about/), 30 | especially if your work contains 31 | formulas, symbols, and heavy cross referencing. 32 | Here is advice for doing so, collected over decades of writing 33 | [hundreds of papers and books](https://www.spinellis.gr/pubs/index.html), 34 | mostly using LaTeX. 35 | 36 | Note that this list is not intended to provide advice on 37 | English writing style, scientific writing, or TeX programming. 38 | There are many other excellent guides for all these topics. 39 | 40 | Contributions to this guide via _GitHub_ pull requests are always welcomed. 41 | 42 | ## Put the document under version control 43 | * Create a repository for your document and add to it all the 44 | document's source code. 45 | This can live on _GitHub_ if you plan to work with others or want 46 | to keep a copy on another server, or it can be a local Git repository 47 | you create with `git init`. 48 | * Do not include in the repository generated files, such as 49 | the formatted PDF document, 50 | compiled bibliographies, 51 | or PDF charts generated from R or Python scripts. 52 | Instead, add _Makefile_ rules to automatically create these files 53 | at build time. 54 | Generated files needlessly increase the size of the repo, 55 | making it time-consuming to clone and fetch updates. 56 | They also pollute difference listings with immaterial changes. 57 | * Commit your changes to the repository in logical chunks using 58 | [meaningful commit messages](https://chris.beams.io/posts/git-commit/). 59 | * Don't combine heavy formatting changes (e.g. adopting a different 60 | publisher's style) with semantic changes (e.g. changes following 61 | suggestions by the second reviewer). 62 | Instead, perform a separate commit for each set of changes. 63 | * When you remove text, delete it completely, rather than commenting 64 | it out. 65 | The version control system will keep track of it and your document 66 | will remain clean. 67 | * Tag the revisions you submit using annotated tag objects (`git tag -a`). 68 | This allows you to go back to specific versions when going over review comments, 69 | or when starting a version of a new publication venue. 70 | Push the tags to the online repository you're using so that all can see them 71 | (`git push --tags`). 72 | 73 | ## Write readable and maintainable LaTeX source code 74 | * Treat the LaTeX source code with love and care as you would treat 75 | software code. 76 | You aim is to keep the source code readable and maintainable. 77 | * Avoid long lines, splitting text somewhere between column 60 and 70. 78 | (You can configure your editor to do this for you). 79 | * Start each phrase on a separate line, and further split a phrase 80 | according to its logical structure. 81 | Here is an example. 82 | ``` 83 | Obtaining metrics from large code bodies is difficult 84 | for technical and operational reasons~\cite{Moc09,GS13}. 85 | On the technical side, 86 | code dependencies make it difficult to establish 87 | the full context needed in order to parse and semantically analyse the code. 88 | This is especially true for C code, 89 | where the compilation depends on 90 | system header files, 91 | compiler-defined macros, 92 | search paths, and 93 | compile-time flags passed through the build process~\cite{Spi03r,LKA11,GG12}. 94 | The operational reasons are associated with the required throughput, 95 | though due to the relatively small number of releases we examined, 96 | this was not a major issue in this study. 97 | ``` 98 | * Splitting lines at the level of phrases and a sentence's logical structure 99 | offers you the following advantages. 100 | * It gives clean line differences of changes made between versions; 101 | a line change corresponds at most to a single phrase. 102 | (You can obtain difference listings on _GitHub_, or via `git diff`.) 103 | Clean differences make it easier to see what has changed and to 104 | merge changes of others when working as a group. 105 | * It makes it easy to rearrange the order of sentences or the elements 106 | in a list, simply by moving lines around. 107 | * It gives you with a second (a structural) view of your document, 108 | which nicely complements the flowed typeset view that LaTeX generates. 109 | This provides you with additional opportunities to spot and fix 110 | syntax, grammar, and style mistakes. 111 | For example, this allows you to spot inconsistent or repetitive 112 | structure in a paragraph's sentences. 113 | * Use comments (sequences starting with `%`) to indicate the key idea of each 114 | paragraph or section. 115 | * Use comment keywords, such as `XXX` or `TODO`, to indicate places 116 | where more work is needed. 117 | * Write LaTeX code and configure your editor so that you can 118 | fold sections and paragraphs. 119 | This shall allow you to inspect your document's structure as an outline. 120 | If needed, add fold marks in comments (e.g. `% {{{2`) to facilitate this. 121 | For example, if your document's structure is in sections and subsections, 122 | these would be level-1 and level-2 folds. 123 | You would then start each paragraph with a level-3 fold comment, 124 | such as the following. 125 | ``` 126 | % Advantages of model-based development {{{3 127 | ``` 128 | * Avoid splitting short documents (such as a journal or conference paper) 129 | into multiple files (e.g. `introduction.tex`, `methods.tex`, `results.tex`, 130 | `conclusions.tex`). 131 | Such splitting makes it difficult to perform a number of tasks with 132 | your editor: 133 | * overview the material's composition 134 | (e.g. the balance of the sections' length), 135 | * globally search or search and replace a particular term, and 136 | * move matter from one section to another. 137 | 138 | When the document is split, these tasks require you to switch from one 139 | file to another or to use external tools. 140 | * Split long documents (such as a book or a thesis) into multiple files, 141 | e.g. one for each chapter, 142 | in order to shorten the project's long build and loading time. 143 | Use the `\include` command to include each chapter in the main document 144 | and the `\includeonly` command to specify which parts shall appear 145 | in the subset you are working on. 146 | For guidance, 147 | see [this example](http://latexref.xyz/Larger-book-template.html). 148 | 149 | ## Automate the document build 150 | Ensure that the document can be built with a single command, 151 | and that files that are out of date are appropriately rebuilt. 152 | This saves you from repeatedly executing multiple commands, 153 | makes it easier to work as a team, and 154 | avoids the accidental use of outdated files. 155 | You have the following options here. 156 | * You can use the Unix _make_ command. 157 | It's available out of the box, but expressing the need for 158 | multiple passes over your document is difficult, 159 | so you may end up processing the document more often than needed. 160 | * A second alternative is 161 | [latexmk](https://www.ctan.org/pkg/latexmk), 162 | which comes bundled with most LaTeX distributions. 163 | See [this StackExchange answer](https://tex.stackexchange.com/a/40759/10140) 164 | for a complete example. 165 | * A third alternative is the use of 166 | [BSD Owl](https://github.com/michipili/bsdowl) scripts, 167 | as documented 168 | [here](https://github.com/michipili/bsdowl/blob/master/doc/LaTeXDocument.md). 169 | Both _latexmk_ and _BSD Owl_ will help you create clean and functional 170 | build setups. 171 | Choose the one that is easier to install on your system and matches your 172 | taste. 173 | * A fourth alternative is 174 | [SCons](https://scons.org/). 175 | SCons' configuration files, typically named `SConstruct`, 176 | are Python scripts. 177 | One such is demonstrated 178 | [here](https://tex.stackexchange.com/a/26573/8272). 179 | You may find a short overview of supported commands/packages 180 | [here](https://github.com/SCons/scons/wiki/LatexSupport). 181 | 182 | ## Use continuous integration 183 | 184 | Once you have automated your build, you are ready for the next step: 185 | continuous integration (CI) for LaTeX documents. 186 | Executing an automated build on every commit allows you to 187 | easily spot accidentally forgotten auxiliary files such as images or tables. 188 | You can also easily isolate changes that broke the build and that are 189 | sometimes hard to debug later. 190 | Moreover, CI creates a defined way to build your project, 191 | on which every collaborator can rely on. 192 | 193 | You can automate this process using the 194 | [github-action-for-latex](https://github.com/marketplace/actions/github-action-for-latex) GitHub Action, or the 195 | [travis-ci-latex-pdf](https://github.com/harshjv/travis-ci-latex-pdf) 196 | solution for [Travis CI](http://travis-ci.org/). 197 | 198 | While at it, consider integrating 199 | [the running of linters](#latex-formatting) into the build process. 200 | 201 | 202 | ## Automate the management of bibliographic references 203 | * Create one or more centrally-managed bibliography files for your 204 | work, and list those in a `\bibliography` command in all documents you write. 205 | You can use [these tools](https://github.com/dspinellis/bibtools) 206 | to share your references with others and navigate to them. 207 | * Using [BibTeX](https://en.wikipedia.org/wiki/BibTeX) or 208 | [Biber](https://en.wikipedia.org/wiki/Biber_(LaTeX)) you can then 209 | automatically create the document's list of references in the style 210 | prescribed by the publisher. 211 | * Use `\cite` commands to reference specific bibliographic entries. 212 | * Include multiple references in the same `\cite` command 213 | (e.g. `\cite{Doh19,Spi22}`) rather than employing multiple `\cite` commands 214 | (`\cite{Doh19} \cite{Spi22}`). 215 | * If you need to reference a specific page or chapter, include this information 216 | in square brackets before the key. 217 | For example, write: `… educational use~\cite[p.~8]{LR89}.` 218 | * If your publisher requires in-text author-year citations, use 219 | [BibLaTeX](http://mirrors.ibiblio.org/CTAN/macros/latex/contrib/biblatex/doc/biblatex.pdf) 220 | or the 221 | [natbib](https://www.ctan.org/pkg/natbib?lang=en) package in conjunction 222 | with the `\citet`, `\citep`, and `\citeauthor` commands. 223 | For example, write: 224 | * `\citet{jon90} proposed …` to get `Jones et al. (1990) proposed …` 225 | * `Another argument \citep{jon90} …` to get 226 | `Another argument (Jones et al., 1990) …`. 227 | * `As \citeauthor{jon90} argued …` to get 228 | `As Jones argued …` (e.g. on a subsequent mention in the same paragraph). 229 | * Include in your BibTeX entries all required fields and as many of the 230 | optional fields as possible. Copy and consult 231 | [this file](https://github.com/dspinellis/latex-advice/blob/master/schema.bib) 232 | to remember which fields are available, which are required, and which 233 | are supported for each entry type. 234 | * Obtain a BibTeX entry for a publication's DOI using the 235 | [doi2bib](https://www.doi2bib.org/) service. 236 | In many cases the quality of its results is higher than that provided 237 | by the publisher's digital library. 238 | * If you copy-paste a BibTeX entry from a digital library, 239 | edit it carefully to ensure a consistent high-level of quality. 240 | * Write the title using 241 | [title capitalization](https://en.wikipedia.org/wiki/Title_case), 242 | e.g. write `The Elements of Programming Style`, rather than 243 | `The elements of programming style`. 244 | This ensures that the title will appear correctly 245 | if a particular bibliography style requires title capitalization. 246 | * Put a title's characters that should always be capitalized in braces, 247 | e.g. `The {C} Programming Language`, or `Fifty Years of {M}oore's Law`. 248 | This ensures these characters will not be converted to lowercase 249 | in bibliography styles that do not require title capitalization. 250 | * Use a consistent format for referring to conferences, for example, 251 | `{ICSE} '08: Proceedings of the 30th International Conference on Software Engineering`. 252 | It would be a mistake to use a different format, e.g. 253 | `12th Working Conference on Mining Software Repositories (MSR 2015), Proceedings of` in another entry. 254 | * Don't include a URL for entries that have a DOI, because the DOI 255 | is more authoritative than the URL, which may 256 | [decay over time](https://doi.org/10.1145/602421.602422). 257 | * In entries that have a DOI, don't store the resolution prefix. 258 | That is, set the DOI entry to something like 259 | `doi = {10.1371/journal.pone.0294946}`, rather than 260 | `doi = {https://doi.org/10.1371/journal.pone.0294946}`. 261 | The prefix can be easily added when needed, and many bibliography formats 262 | add it in the hyperlink without wasting space to show it. 263 | * Specify an em-dash or en-dash where required, e.g. 264 | `The Entity-Relationship Model---Toward a Unified View of Data` or 265 | `The Evolution of {C} Programming Practices: A Study of the {U}nix Operating System 1973--2015`. 266 | * Use LaTeX special characters for authors whose names contain non-ASCII 267 | characters, e.g. 268 | `author = {Yann-Ga\"{e}l Gu\'{e}h\'{e}neuc and Herv\'{e} Albin-Amiot}`. 269 | This change may not be required if you are using 270 | [Biber](https://en.wikipedia.org/wiki/Biber_(LaTeX)), provided that 271 | the digital library correctly provides the author names in Unicode. 272 | * Use consistent, easily derivable, short names for your bibliography entries. 273 | One practical scheme is as follows. 274 | * The single author's surname first three letters, followed by the 275 | last two year digits, e.g. `Ker08` for an article published 276 | by `Brian Kernighan` in 2008. 277 | * Up to four multi-author surname initials followed by the last two year 278 | digits, e.g. `DMG07` for an article published by 279 | `Duvall, Paul M. and Matyas, Steve and Glover, Andrew` in 2007. 280 | * The letter`a`, `b`, `c`, etc appended to the above keys in the case 281 | of clashes. 282 | 283 | Through this scheme you can easily search for an existing entry in your 284 | bibliography files and saved articles, because you can quickly derive 285 | the key used. 286 | Also this scheme will help you avoid duplicate entries, because the 287 | corresponding keys will clash. 288 | * If you save the PDF document associated with a bibliography entry in 289 | your files, name it using the entry's key, e.g. `LR89.pdf`. 290 | * If you print (or photocopy) a document associated with a bibliography 291 | entry, write the corresponding key on its top right corner. 292 | This will help you reference it in your work. 293 | You can also use this key to file the printout so that you can find it 294 | in the future. 295 | * If you prefer to edit your BibTeX files with an application 296 | rather than a generic editor, consider using 297 | [JabRef](https://www.jabref.org/) for the desktop or 298 | [Bibtool](http://www.gerd-neugebauer.de/software/TeX/BibTool/en/) 299 | on the command line. 300 | 301 | ## Use style files 302 | Conference organizers and publishers often supply style files that 303 | determine the appearance and formatting of a document and its references. 304 | Download them and use them. 305 | If you're writing a thesis and your institution doesn't provide a template 306 | you can use [this one](https://github.com/derric/cleanthesis). 307 | Seeing your document in its published look 308 | boosts your motivation, 309 | helps you appreciate how your readers will experience it, and 310 | minimizes rework by forcing you to comply with the publisher's 311 | requirements while you develop your document. 312 | 313 | ## Use third-party LaTeX packages 314 | You can obtain many formatting goodies by incorporating into 315 | your document third-party LaTeX packages. 316 | Most LaTeX distributions provide a package management system 317 | that simplifies the installation and maintenance of packages. 318 | Here are some popular LaTeX packages your may want to know about. 319 | * [algorithmicx](https://www.ctan.org/pkg/algorithmicx): Display good-looking pseudocode 320 | * [amsmath, amssymb](https://www.ctan.org/pkg/amsmath): AMS mathematical facilities 321 | * [amsthm](https://www.ctan.org/pkg/amsthm): Typesetting theorems (AMS style) 322 | * [booktabs](https://www.ctan.org/pkg/booktabs): Publication quality tables 323 | * [cite](https://www.ctan.org/pkg/cite): Improved citation handling 324 | * [enumitem ](https://ctan.org/pkg/enumitem): Control layout of itemize, enumerate, description 325 | * [fancyhdr](https://www.ctan.org/pkg/fancyhdr): Extensive control of page headers and footers 326 | * [geometry](https://www.ctan.org/pkg/geometry): Flexible and complete interface to document dimensions 327 | * [glossaries](https://ctan.org/pkg/glossaries): Define and typeset acronyms and glossaries 328 | * [hyperref](https://www.ctan.org/pkg/hyperref): Extensive support for hypertext 329 | * [listings](https://www.ctan.org/pkg/listings): Typeset source code listings 330 | * [minted](https://www.ctan.org/pkg/minted): Typeset source code listings with highlighting 331 | * [natbib](https://www.ctan.org/pkg/natbib): Flexible bibliography support 332 | * [PGF/TikZ](https://www.ctan.org/pkg/pgf): Create PostScript and PDF graphics 333 | * [setspace](https://www.ctan.org/pkg/setspace): Set space between lines 334 | * [siunitx](http://www.ctan.org/pkg/siunitx): A comprehensive (SI) units package 335 | * [titlesec](https://ctan.org/pkg/titlesec): Select alternative section titles 336 | * [url](https://www.ctan.org/pkg/url): Verbatim with URL-sensitive line breaks 337 | * [widows-and-orphans](https://ctan.org/pkg/widows-and-orphans): Warns of typographic widows and orphans 338 | * [xcolor](https://www.ctan.org/pkg/xcolor): Driver-independent color extensions 339 | * [xspace](https://www.ctan.org/pkg/xspace): Define commands that appear not to eat spaces 340 | * [cleveref](https://www.ctan.org/pkg/cleveref): Intelligent cross-referencing 341 | 342 | ## Avoid explicit formatting 343 | * Avoid the use of explicit formatting within the text. 344 | Instead, use commands that specify why your text should be formatted 345 | in a special way. 346 | For example, rather than specifying a large bold font, use 347 | `\section` and rather than specifying italic text use `\emph`. 348 | * If your document requires that particular text should be formatted 349 | in a special way, declare a new command or environment to format it. 350 | This will allow you to easily adjust the formatting throughout the 351 | document. 352 | For example, 353 | the following command sets a document's _finding_ in boldface 354 | ``` 355 | \newcommand{\finding}[1]{\textbf{#1}} 356 | ``` 357 | while the following environment declaration will list 358 | a software's license in a small font keeping its formatting. 359 | ``` 360 | \newenvironment{license}{\verbatim\scriptsize}{\normalsize\endverbatim} 361 | ``` 362 | 363 | ## Use symbolic references 364 | * Mark sections, tables, figures, and equations using the `\label` command, 365 |   and reference them using the [cleveref](https://www.ctan.org/pkg/cleveref) 366 | `\Cref` command. 367 | * Avoid referencing floating environments by name 368 |  (e.g. `see Figure~\ref{fig:foo}`);`\Cref` can create that for you: 369 |  `see~\Cref{fig:foo}`. 370 | * Use self-descriptive label names. 371 | For example, use `tab:statResults` rather than  `table1`. 372 | Use the `tab:` prefix when labelling tables, 373 | the `fig:` prefix  when labelling figures, and 374 | the `sec:` prefix  when labelling sections. 375 | 376 | ## Mathematics 377 | * Set all math, including formulas and stand-alone math symbols, 378 | in LaTeX's math mode. 379 | See the following example, which includes a little-known formula 380 | and in-text references to its elements. 381 | ``` 382 | \[ 383 | E = mc^2 384 | \] 385 | This formula states that the equivalent energy (\(E\)) 386 | can be calculated as the mass (\(m\)) multiplied 387 | by the speed of light (\(c\)) squared. 388 | ``` 389 | * Use balanced `\left` and `\right` commands to markup (balanced) 390 | bracketing elements. 391 | This ensures that the elements will be correctly sized, according 392 | to the formula they include. 393 | For example, write `\left(\cos(x) + i \sin(x)\right)^n`. 394 | * Use special markup for character sequences math mode. 395 | LaTeX assumes an implicit multiplication in character sequences it 396 | encounters in math mode, and sets the text with corresponding spacing. 397 | * If the characters indicate one of 398 | [LaTeX-supported operators](https://en.wikibooks.org/wiki/LaTeX/Mathematics#Operators) 399 | then use that operator command, e.g. `\mod`, `\max`, or `\sin`. 400 | * If the characters indicate an unsupported operator, 401 | declare it using the `amsmath` command `\DeclareMathOperator`, 402 | e.g. `\DeclareMathOperator{\sha}{sha}`. 403 | * If the characters indicate a multi-character variable name, 404 | set it in italics or roman using e.g. `\mathit{Delta}` or 405 | `\mathrm{Delta}`. 406 | * Set non-index or descriptive subscripts in roman rather than italic. 407 | Example: `x_{\mathrm{max}}` 408 | * Indent elements and break lines in order to express 409 | the logical structure of the formula you are writing, 410 | keeping the operators as the first character on a line. 411 | For example, write: 412 | ``` 413 | F_{n} = 414 | \cfrac{1}{\sqrt{5}} \left(\cfrac{1 + \sqrt{5}}{2}\right)^n 415 | - \cfrac{1}{\sqrt{5}} \left(\cfrac{1 - \sqrt{5}}{2}\right)^n 416 | ``` 417 | 418 | * For inline math, prefer the use of the LaTeX `\(` _math_ `\)` delimiters 419 | to TeX's `$` _math_ `$` style. 420 | * Ensure equations are correctly punctuated according to the sentence 421 | they belong to. 422 | Put a period at their end if the end a sentence, or a comma if they 423 | are given perenthetically. 424 | Space the trailing period or comma by prefixing it with a `\,`. 425 | Example: 426 | ``` 427 | The atomic age started with the establishment of the mass–energy equivalence, 428 | \[ 429 | E = mc^2 \,. 430 | \] 431 | ``` 432 | * If you write a lot of math in LaTeX, acquaint yourself and follow 433 | A.J. Hildebrand's 434 | [Top Ten List](https://web.archive.org/web/20170817055844/http://www.math.illinois.edu/~ajh/tex/tips-topten.html). 435 | 436 | ## Number and unit formatting 437 | * As mandated by the [NIST Guide for the Use of the International System of Units (SI)](https://physics.nist.gov/cuu/pdf/sp811.pdf#page=28), 438 | put a thin non-breaking space between a number and the unit it represents. 439 | Also, format long numbers with a thin-space decimal separator, and use 440 | a negative sign, rather than a hyphen to designate negative numbers. 441 | You can do all these tasks easily with the 442 | [siunitx](http://www.ctan.org/pkg/siunitx) package. Example: 443 | ``` 444 | It took \qty{7146}{s} to load a \qty{134}{\gibi\byte} file over a 445 | \qty{200}{\mebi\bit} connection over a distance of \qty{9500}{\km}. 446 | During the transfer \num{12345} packets were dropped. 447 | The ambient temperature was \qty{-35}{\degreeCelsius}. 448 | ``` 449 | 450 | ## Tables 451 | * Avoid the use of rules (`\hline` and `|`) in tables. 452 | They are unsightly and this is the reason you will rarely see them 453 | in professionally typeset books. 454 | * Specify the alignment of numbers to the right, 455 | text to the left, and single symbols on the center. 456 | * When listing numbers with a decimal point align them on the decimal 457 | point. 458 | You can [easily](https://tex.stackexchange.com/a/2747/10140) 459 | do this by using the [siunitx](http://www.ctan.org/pkg/siunitx) package. 460 | * Use hard tabs before each column's `&` separator to start each column's 461 | data on the same LaTeX source document column. 462 | See the following example. 463 | ``` 464 | tr -cs & 1 & \X & -- & \V & 1 \\ 465 | sort w & 0 & & -- & \X & 0 \\ 466 | fmt & 1 & \X & -- & \V & 1 \\ 467 | tr A-Z & 1 & \V & 1 & & 1 \\ 468 | sort -u & fmt & \X & -- & \V & 1 \\ 469 | ``` 470 | * If the column labels are too long, start them on separate lines, 471 | keeping the columns aligned with the data. 472 | Example: 473 | ``` 474 | % Column labels 475 | Command and options 476 | & Input requirements 477 | & Matched 478 | & Connected 479 | & Matched 480 | & Connected \\ 481 | \hline 482 | % Data 483 | tr -cs & 1 & \X & -- & \V & 1 \\ 484 | sort w & 0 & & -- & \X & 0 \\ 485 | ... 486 | ``` 487 | * If you want horizontal rules, use `\toprule`, `\midrule` and 488 | `\bottomrule` from the `booktabs` package. 489 | Example: 490 | ``` 491 | \toprule 492 | Header \\ 493 | \midrule 494 | Table row 1 \\ 495 | Table row 2 \\ 496 | \bottomrule 497 | ``` 498 | 499 | ## Figures 500 | * Use vector rather than bitmap images. 501 | So, avoid including a `.jpeg` or `.png` image if you can include 502 | a PDF created from vector data, e.g. by direct export from 503 | [Inkscape](https://inkscape.org/en/) or 504 | [GraphViz](http://graphviz.org/) or by converting an `.svg` file. 505 | * Use the same font in all your figures. 506 | This does not need to be the same font as the one you use for the document's 507 | text, it could be a sans-serif one, but it should be the same e.g. 508 | in charts and diagrams. 509 | * Ensure figure fonts are scaled to match the size of the document's 510 | font. 511 | Eyeballing is often enough. 512 | For exact measurements you have two options. 513 | If you scale the figure by an explicit amount (e.g. 1 or 0.5) you 514 | should use a font of the corresponding size (e.g. 11 points or 22 points). 515 | If you scale the figure by an arbitrary amount to match the document's 516 | column width, you can load the resultant PDF in Inkscape and measure the 517 | font size there. 518 | * Given that floating figures are described by their caption, there is no 519 | need to include a separate figure title. 520 | * Label the figure's axes. 521 | * Avoid [common chart errors](https://github.com/cxli233/FriendsDontLetFriends). 522 | 523 | ## Floats 524 | * Allow large displayed elements (figures, tables, listings) to have 525 | a floating position by using a _figure_ or _table_ environment. 526 | * Reference in the text all floats appearing in the document. 527 | * Put floats in your document before your first reference to them. 528 | * Use `\centering` within a figure or table environment to center its 529 | contents. 530 | This avoids the extra space introduced by the `center` environment. 531 | * Don't sweat too much about float positioning while writing. 532 | If your write for a journal, this will be handled during production; 533 | if you will provide a camera-ready version, leave this for the last 534 | minute. 535 | * Unless specified otherwise by your publisher, 536 | place table captions _above_ the table and 537 | figure captions _below_ the figure. 538 | 539 | ## Typography 540 | * Be consistent in the rules you follow. 541 | Some style guides offer contradicting advice. 542 | Examples include: 543 | * the placement of footnotes before or after punctuation, 544 | * the use of [title case](https://en.wikipedia.org/wiki/Title_case) 545 | or sentence case for capitalizing titles and section headings, 546 | * the spacing around the _em-dash_. 547 | 548 | This isn't a license to randomly use both the one or the other 549 | alternative within the document. 550 | Adopt your publisher's style or consistently follow the same rule 551 | throughout your document. 552 | * Use three dashes (`---`) to create the _em-dash_, 553 | which separates parenthetical phrases. 554 | According to the _Chicago Manual of Style_ (2.13), 555 | an em-dash has no space before or after it. 556 | (Note that _The Associated Press Stylebook_ specifies spacing.) 557 | * Use two dashes (`--`) to create an _en-dash_. 558 | Use this to specify number ranges, e.g. `2009--2015`. 559 | * Use `\dots` to produce an ellipsis (`...`) punctuation symbol. 560 | * Put footnotes _after_ punctuation symbols, unless your publisher's 561 | style specifies otherwise. 562 | For example, write `… is true.\footnote{See also …}` 563 | * Separate numbers and the units these represent with a (non-breaking) space: `12~kB`, `3.6~GHz`. 564 | No space is required for percentages and degrees: 90%, 45°. 565 | (Note that the SI standard, in contrast to the _Chicago Manual of Style_, 566 | specifies that a space should precede 567 | [°C](https://doi.org/10.6028/NIST.SP.330-2019#page=48) and 568 | [%](https://doi.org/10.6028/NIST.SP.330-2019#page=50).) 569 | * Avoid underlined text. 570 | Underlining is used for emphasis in handwritten text and was also 571 | carried over in this capacity in typewritten documents. 572 | With modern printers and software you don't need to underline, 573 | because you can use a different font style (bold or italic) for emphasis. 574 | * Avoid sequences of uppercase text. 575 | Text written in all-uppercase characters is an eyesore and 576 | considerably more difficult to read than its lowercase equivalent. 577 | Lowercase letters have been designed for easy reading, 578 | uppercase were originally designed for easy chiseling on stone. 579 | * Use small caps rather than an unsightly sequence of capital letters 580 | for writing abbreviations. 581 | For example, write `\textsc{sql}`, rather than `SQL`. 582 | Note that some publishers do not follow this style. 583 | If you are supplying the final camera ready version 584 | (e.g. for conference proceedings), use small caps. 585 | If a publisher will edit your document and the publisher does not use 586 | small caps, avoid their use; 587 | a common frustrating mistake is for publishers to remove the 588 | `\textsc` command, without writing the text in uppercase. 589 | * Display pseudo-code using the 590 | [algorithmicx](https://www.ctan.org/pkg/algorithmicx) 591 | package and environment. 592 | See [this wikibooks](https://en.wikibooks.org/wiki/LaTeX/Algorithms) 593 | entry for more details. 594 | * Display source code snippets using the 595 | [listings](https://www.ctan.org/pkg/listings) (simpler) 596 | or the [minted](https://www.ctan.org/pkg/minted) 597 | (nicer, but with extra dependencies) package. 598 | Make sure your code does not go over the paragraph length; 599 | if it does, adjust line breaking and/or font size accordingly. 600 | 601 | ## LaTeX formatting 602 | * Don't spend too much time on formatting your document. 603 | Concentrate on communicating your ideas and on making your document 604 | maintainable. 605 | Excessive formatting tweaks can be counterproductive: 606 | you waste time implementing them and 607 | your publisher may find it more difficult to use your document. 608 | * Use a tilde before `\cite`, `\ref`, etc. to avoid a line break immediately 609 | before the reference. 610 | For example, write `Some also use logging statements~\cite{Spi06e}`. 611 | * Put a backslash after a non-sentence ending period to ensure this will 612 | not be followed by the sentence-ending spacing. 613 | For example, write `In 1962 Watson et al.\ famously found …` 614 | * Do not use math mode to achieve typographic effects in plain text. 615 | For example write `RQ\textsubscript{2}` rather than `\(RQ_2\)`, if you 616 | must subscript the number of your research question 2. 617 | Similarly use `\textsuperscript` for plain superscripted text (e.g. 618 | `Wisper Quiet\textsuperscript{TM}`). 619 | * Match opening and closing quotes using one or two single-opening 620 | (`‘` or `‘‘`) and single-closing (`’` or `’’`) quote characters. 621 | Do not use the keyboard's double quote symbol (`"`). 622 | Alternatively you can use the `\enquote{}` macro from the `csquotes` 623 | package, which will automatically set the right quotes for the 624 | configure language and can handle nested quotes correctly. 625 | * Use the new local font style commands 626 | (e.g. `\texttt{}`, `\textsc{}`, or `\textbf{}`) 627 | rather than the old switches (e.g. `{\tt }`, `{\sc }`, `{\bf }`) 628 | * Run one or more of the LaTeX linters [LaCheck](https://ctan.org/pkg/lacheck) 629 | (with the `lacheck` command) and 630 | [ChkTeX](https://www.nongnu.org/chktex/) (with the `chktex` command) 631 | on your document to find and fix typesetting errors. 632 | These check documents for certain LaTeX anti-patterns, such as the use of 633 | `...` instead of the typographically correct `\dots` or other such violations. 634 | Users can define their own rules, too, for example to enforce consistency 635 | in the spelling of certain phrases. 636 | Now it is up to you to create ChkTeX rules to enforce the guidelines in this 637 | document. 638 | If you do, please share them. 639 | 640 | * To obtain a PDF document with the widely available Times/Helvetica/Courier 641 | font set, rather than the LaTeX, less widely used, Computer Modern fonts, 642 | use the following packages. 643 | ``` 644 | \usepackage{mathptmx} 645 | \usepackage[scaled=.90]{helvet} 646 | \usepackage{courier} 647 | ``` 648 | 649 | ## Writing 650 | This guide focuses on LaTeX document preparation. 651 | Nevertheless, here is some advice for improving your 652 | writing and for avoiding common mistakes. 653 | 654 | * Read, learn, and apply Strunk and White's 655 | [The Elements of Style](https://gutenberg.org/ebooks/37134). 656 | * Express each idea in a separate paragraph. 657 | * Begin each paragraph with a sentence summarising it, transitioning to it, 658 | or providing its overall theme. 659 | * Write your paper's abstract as a [structured abstract](https://www.nlm.nih.gov/bsd/policy/structured_abstracts.html) 660 | or as a similarly self-contained summary of the paper. 661 | Never summarize the paper's table of contents. 662 | ("In this paper we outline the problems associated with sinkholes, 663 | describe the methods we used to explore them, 664 | present the results of the experiments we performed, 665 | and discuss the implications of our findings.") 666 | * Don't present related work as a laundry list. 667 | (X did A [12]. Y developed B [45]. Z wrote C [37].) 668 | Instead, _analyze_ what has been done to identify commonalities, 669 | differences, evolution, 670 | or other noteworthy features of how scientific knowledge 671 | is built up in the area you're examining. 672 | Then present a _synthesis_ of the work along the axes you identified. 673 | You can find examples of the laundry-list appraoch and the recommended 674 | one [here](https://www.spinellis.gr/blog/20240805/). 675 | * Avoid the use of adjectives that express a subjective view of your work. 676 | (Our innovative method, remarkable results, outstanding accuracy, 677 | lightning performance, swift execution time.) 678 | Instead, present objective figures that speak for themselves. 679 | * When reporting numbers [round them to the appropriate number of significant 680 | digits and decimal places](https://dx.doi.org/10.1136/archdischild-2014-307149). 681 | * Don't treat bibliographic references as nouns. 682 | Rather than writing 683 | "According to [12] there are two escape mechanisms" 684 | write 685 | "According to reference [12] there are two escape mechanisms", 686 | or 687 | "According to Smith [12] there are two escape mechanisms", or 688 | (parenthetically) "There are two escape mechanisms [12]." 689 | Similarly, for author year reference styles, rather than writing 690 | "According to (Smith 2020) there are there are two escape mechanisms" 691 | write 692 | "According to Smith (2020) there are two escape mechanisms", 693 | or 694 | (parenthetically) "There are two escape mechanisms (Smith 2020)". 695 | Use LaTeX commands to automatically provide the author name 696 | with suitable brackets. 697 | The commands vary depending on the bibliography reference package you're 698 | using. 699 | For instance, under _natbib_ you can write 700 | `\citet{Smi20}` to obtain "Smith [12]" or "Smith (2020)" 701 | (depending on the citation style), 702 | or you can write `\citeauthor{Smi20}` to obtain "Smith". 703 | * Spell out numbers below 13, unless the number is used as a proper noun 704 | (e.g. "Section 2") or as part of an arithmetic construct ("element a[6]"). 705 | * Treat software system names as proper nouns. 706 | Just as you capitalize "Microsoft Windows", write 707 | "We used Git to store past versions.", "We employed a Python script …" or 708 | "The generics that Java provides …". 709 | Use lowercase (and a code-like font) only when you refer to the actual 710 | command-line invocation sequences: 711 | "By running `git log HEAD` we were able to inspect the most recent changes." 712 | * Do not capitalize the words that introduce an abbreviation, unless these 713 | are proper nouns. 714 | Thus write "we used a large language model (LLM)", but 715 | "as recommended by the American Psychological Association (APA)". 716 | * Don't start a lower-level structure, such as a section within a chapter or 717 | a subsection within a section, immediately after the parent's title. 718 | Instead begin the lower-level element with introductory text, such as 719 | an overview of what you will present. 720 | * Avoid creating a single subsection within a section. 721 | * Balance the size of your work's divisions (chapters, sections, subsections). 722 | 723 | ## Additional material regarding LaTeX 724 | * A.J. Hildebrand. [LaTeX Tips: Basic tips](http://www.math.uiuc.edu/~ajh/tex/basics.html) 725 | * Wikibooks. [LaTeX/Tips and Tricks](https://en.wikibooks.org/wiki/LaTeX/Tips_and_Tricks) 726 | * John Regehr. [John's Small Collection of LaTeX Tips](https://john.regehr.org/latex/) 727 | * Mark Trettin (author of German version) and Jürgen Fenn (English translation). 728 | [An essential guide to LaTeX2ε usage: Obsolete commands and packages](https://ctan.org/tex-archive/info/l2tabu/english/) 729 | * Martin J. Osborne [Some common (la)tex errors](https://www.economics.utoronto.ca/osborne/latex/LTXERR.HTM) 730 | * StackExchange Academia. [Does submitting a paper in Latex format enhance the chances of acceptance?](https://academia.stackexchange.com/questions/82641/does-submitting-a-paper-in-latex-format-enhance-the-chances-of-acceptance) 731 | * Knauff M, Nejasmic J (2014) An Efficiency Comparison of Document Preparation Systems Used in Academic Research and Development. PLoS ONE 9(12): e115069. https://doi.org/10.1371/journal.pone.0115069 732 | 733 | ## Material on writing and presenting information 734 | * [List of style guides](https://en.wikipedia.org/wiki/List_of_style_guides) 735 | on Wikipedia. 736 | * George Gopen, Judith Swan (1990) [The Science of Scientific Writing](https://www.americanscientist.org/blog/the-long-view/the-science-of-scientific-writing). _Americal Scientist_, November–December. 737 | * Lorna Mitchell (2022) [Write documentation like you develop code](https://opensource.com/article/22/10/docs-as-code) 738 | * University of Melbourne [Five principles of good graphs](https://scc.ms.unimelb.edu.au/resources/data-visualisation-and-exploration/data-visualisation) 739 | * George Orwell (1946). [Politics and the English Language](https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/). Horizon. 740 | * Diomidis Spinellis. [The Elements of Computing Style](https://www.spinellis.gr/computingstyle) 741 | 742 | ## License 743 | [![Creative Commons License](https://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 744 | 745 | This work is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-sa/4.0/). 746 | -------------------------------------------------------------------------------- /schema.bib: -------------------------------------------------------------------------------- 1 | % 2 | % Schema of a BibTeX file 3 | % 4 | % Copy this file and use it as a template for creating your new entries. 5 | % See also https://github.com/dspinellis/latex-advice 6 | % 7 | % (C) Copyright 1990-2019 Diomidis Spinellis. 8 | % 9 | % This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 10 | % International License. 11 | % 12 | 13 | % Documentation of all possible fields 14 | @Misc{Key, 15 | Address="Publishers address. For major ones just the city", 16 | Annote="Annotation", 17 | Author="First Last or Last, First. Multiple are separated by and", 18 | Booktitle="Title properly capitalised", 19 | Chapter="A chapter number", 20 | Edition="Edition of the book, e.g. second", 21 | Editor="First Last or Last, First. Multiple are separated by and", 22 | HowPublished="If it was published in a strange way", 23 | Institution="Institution that published it", 24 | Journal="Journal name. Abreviations may exist in TEXINPUTS/*.bst", 25 | Key="Used for alphabetizing and creating a label when no author", 26 | Month="Month of publication, usual abbreviations", 27 | Note="Additional information to help the reader", 28 | Number="Number of a journal magazine to TR.", 29 | Organization="Organization sponsoring the conference.", 30 | Pages="Page numbers or range.", 31 | Publisher="Publisher's name.", 32 | DOI="Digital Object Identifier (without the DOI prefix)", 33 | URL="Uniform Resource Locator", 34 | School="Name of the school where the thesis was written.", 35 | Series="The name of a series or set of books.", 36 | Title="The work's title.", 37 | Type="Type of a technical report e.g. Research Note", 38 | Volume="The volume of a journal or multivolume book.", 39 | Date="Date is yyyy-mm-dd format. Supported by BibLaTeX", 40 | Eid="Electronic identifier, e.g. article number. Supported by JabRef.", 41 | Year="The year of publication. Numerals only." 42 | } 43 | 44 | % Templates for each type. 45 | @Article{Key, 46 | Title="Required", 47 | URL="Optional", 48 | DOI="Optional", 49 | Author="Required", 50 | Journal="Required", 51 | Volume="Optional", 52 | Number="Optional", 53 | Pages="Optional", 54 | Month="Optional", 55 | Date="Optional", 56 | Eid="Optional", 57 | Year="Required", 58 | URL="Optional", 59 | Note="Optional" 60 | } 61 | 62 | @Book{Key, 63 | Title="Required", 64 | URL="Optional", 65 | Edition="Optional", 66 | Series="Optional", 67 | Volume="Optional", 68 | Author="Required or Editor", 69 | Editor="Required or Author", 70 | Publisher="Required", 71 | Address="Optional", 72 | Month="Optional", 73 | Date="Optional", 74 | Eid="Optional", 75 | Year="Required", 76 | Note="Optional", 77 | ISBN="Optional" 78 | } 79 | 80 | @Booklet{Key, 81 | Address="Optional", 82 | Author="Optional", 83 | HowPublished="Optional", 84 | Key="Optional (needed if no Author)", 85 | Month="Optional", 86 | Note="Optional", 87 | Title="Required", 88 | URL="Optional", 89 | Date="Optional", 90 | Eid="Optional", 91 | Year="Optional" 92 | } 93 | 94 | @InBook{Key, 95 | Address="Optional", 96 | Author="Required or Editor", 97 | Chapter="Required or Pages", 98 | Edition="Optional", 99 | Editor="Required or Author", 100 | Month="Optional", 101 | Note="Optional", 102 | Pages="Required or Chapter", 103 | Publisher="Required", 104 | Series="Optional", 105 | Title="Required", 106 | URL="Optional", 107 | Volume="Optional", 108 | Date="Optional", 109 | Eid="Optional", 110 | Year="Required" 111 | } 112 | 113 | @InCollection{Key, 114 | Author="Required", 115 | Title="Required", 116 | URL="Optional", 117 | DOI="Optional", 118 | Chapter="Optional", 119 | Pages="Required", 120 | Editor="Optional", 121 | Booktitle="Required", 122 | Publisher="Required", 123 | Address="Optional", 124 | Month="Optional", 125 | Date="Optional", 126 | Eid="Optional", 127 | Year="Required", 128 | Note="Optional" 129 | } 130 | 131 | @InProceedings{Key, 132 | Title="Required", 133 | URL="Optional", 134 | DOI="Optional", 135 | Author="Required", 136 | Booktitle="Required", 137 | Location="Optional", 138 | Month="Optional", 139 | Date="Optional", 140 | Eid="Optional", 141 | Year="Required", 142 | Organization="Optional", 143 | Pages="Optional", 144 | Editor="Optional", 145 | Address="Optional", 146 | Publisher="Optional", 147 | Note="Optional", 148 | URL="Optional" 149 | } 150 | 151 | @Manual{Key, 152 | Address="Optional", 153 | Annote="Annotation", 154 | Author="Optional", 155 | Edition="Optional", 156 | Key="Optional (needed if no Author)", 157 | Month="Optional", 158 | Note="Optional", 159 | Organization="Optional", 160 | Title="Required", 161 | URL="Optional", 162 | Date="Optional", 163 | Eid="Optional", 164 | Year="Optional" 165 | } 166 | 167 | @MastersThesis{Key, 168 | Address="Optional", 169 | Author="Required", 170 | Month="Optional", 171 | Note="Optional", 172 | School="Required", 173 | Title="Required", 174 | URL="Optional", 175 | Date="Optional", 176 | Eid="Optional", 177 | Year="Required" 178 | } 179 | 180 | @Misc{Key, 181 | Author="Optional", 182 | HowPublished="Optional", 183 | Key="Optional (needed if no Author)", 184 | Month="Optional", 185 | Note="Optional", 186 | Title="Optional", 187 | URL="Optional", 188 | Date="Optional", 189 | Eid="Optional", 190 | Year="Optional" 191 | } 192 | 193 | @PhDThesis{Key, 194 | Address="Optional", 195 | Author="Required", 196 | Month="Optional", 197 | Note="Optional", 198 | School="Required", 199 | Title="Required", 200 | URL="Optional", 201 | Date="Optional", 202 | Eid="Optional", 203 | Year="Required" 204 | } 205 | 206 | @Proceedings{Key, 207 | Title="Required", 208 | URL="Optional", 209 | DOI="Optional", 210 | Editor="Optional", 211 | Note="Optional", 212 | Organization="Optional", 213 | Location="Optional", 214 | Publisher="Optional", 215 | Month="Optional", 216 | Date="Optional", 217 | Eid="Optional", 218 | Year="Required" 219 | } 220 | 221 | @TechReport{Key, 222 | Author="Required", 223 | Title="Required", 224 | URL="Optional", 225 | DOI="Optional", 226 | Note="Optional", 227 | Type="Optional", 228 | Number="Optional", 229 | Month="Optional", 230 | Date="Optional", 231 | Eid="Optional", 232 | Year="Required", 233 | Institution="Required", 234 | Address="Optional" 235 | } 236 | 237 | @Unpublished{Key, 238 | Author="Required", 239 | Month="Optional", 240 | Note="Required", 241 | Title="Required", 242 | URL="Optional", 243 | Date="Optional", 244 | Eid="Optional", 245 | Year="Optional" 246 | } 247 | --------------------------------------------------------------------------------