The PXD Whitebook Instructions 1
Contents 1 Writing Conventions and Typesetting 3 Manfred Valentan 1.1 Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1 Spelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.2 Ignoring temporary files in git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.3 Acronyms and glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.4 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.5 Automatic compilation with latexmk . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.6 Tables, captions and labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.7 Axis labels and color map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2 Math typesetting in a nutshell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.1 Variables, functions and Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2.2 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.2.3 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.2.4 Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.5 Vectors and matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.2.6 Particles and chemical elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1.3 Other conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.1 Quotation marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.2 Umlauts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.3.3 Useful commands and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Glossary 11 Acronyms 14 2
Chapter 1 Writing Conventions and Typesetting Manfred Valentan This chapter gives an overview of guidelines, best practices and conventions which should lead to a con- sistent, useful and beautiful document. Read this first, before starting to write your own sections. If you have questions or suggestions, feel free to contact Manfred Valentan (manfred.valentan@mpp.mpg.de). 1.1 Best practices 1.1.1 Spelling For this document we use the US 1 spelling rather than the British one. Here are a few examples of spelling differences: US British digitizer digitiser neighbor neighbour flavor flavour labeling labelling center centre meter metre color colour gray grey We will update this list when more examples occur while writing the document. 1.1.2 Ignoring temporary files in git L A T EX compilation produces a lot of temporary files, which we don’t want to upload to the git repository. One can have git ignore these files by writing them into the file .gitignore 2 . 1 US: United States (of America) 2 .gitignore is a hidden file, make sure to change the view options of your file browser to display it. 3
To see an overview of all changed files, run git status in a terminal, in the root folder of the whitebook. The section untracked files shows files which are new to git . If you see temporary files there, please add them to .gitignore . 1.1.3 Acronyms and glossary The documentation of the Belle II PXD 3 project has to deal with a lot of acronyms and technical terms. In this whitebook we will compile a comprehensible collection of these terms in form of an acronym list and a glossary using the package glossaries [1]. The entries are defined in the files Conventions/acronyms.tex and Conventions/glossary.tex ; all entries contain a key , a name and a description . When you write your text and come across an acronym or technical term, first check if it is already defined in one of these two files. If so, you can use it with the following command: \gls{key} This will put the name in the text. If it is an acronym which occurs for the first time, it will create a footnote with the description . Use glspl{key} to get the plural form of a technical term, and Gls{key} or Glspl{key} for the capitalized versions. After adding a new acronym or glossary entry, make sure you use \gls{...} in the text to Usage invoke it. Compile the code once, then run makeglossaries PXDwb in a terminal. Many TeX editors have a dedicated button to do that. Recompile the code again. Your new acronym or glossary entry should appear in its respective section. See section 1.1.5 on how to automatize this compilation process. 1.1.4 Bibliography The bibliography is provided by BibTeX [2]. All references are put in the file bibliography.bib , and the bibliography at the end of the whitebook is automatically sorted. The bibtex file bibliography.bib can be edited in any editor, but for more comfort you can use a specialized program like JabRef [3]. After adding a new reference, make sure you use ~\cite{...} in the text to invoke it 4 . Compile Usage the code once, then run bibtex PXDwb in a terminal. Many TeX editors have a dedicated button to do that. Recompile the code again. Your new reference should appear in the bibliography section. See section 1.1.5 on how to automatize this compilation process. 1.1.5 Automatic compilation with latexmk The Pearl script latexmk [4] automatizes the compilation process, including all commands for the bib- liography, the glossary and the acronym list. This is optional, you can also compile the document the traditional way. If you want to use latexmk , make sure it is installed on your local system. Use the web search to find out how to do that for your operating system. Once installed, you can run the following command in a command prompt: latexmk -pdf PXDwb Many TeX editors have a dedicated button to run latexmk . 1.1.6 Tables, captions and labels Tables should only use horizontal lines, and the contents should be left-aligned [5]. 3 PXD: PiXel Detector 4 Please note the non-breaking blank ˜ before the cite command. This makes sure that the the citation number can’t be broken to the next line. 4
Table 1.1: A sample table to show the correct use of lines and justification. Header 1 Header 2 Header 3 Value 1 Value 2 Value 3 Value 4 Value 5 Value 6 Code for table 1.1: \begin{table}[htb] \centering \caption{A sample table to show the correct use of lines and justification.} \label{tab:sample} \begin{tabular}{lll} \toprule Header 1 & Header 2 & Header 3 \\ \midrule Value 1 & Value 2 & Value 3 \\ Value 4 & Value 5 & Value 6 \\ \bottomrule \end{tabular} \end{table} Please note that the command \label{} has to come after \caption{} , otherwise the counting of table numbers will be wrong. of tables go on top (like in table 1.1), while captions of pictures and plots are put on the Captions bottom. See figure 1.1 for an example plot. The caption should be self-explaining, i.e. one should be able to understand the plot with help of the caption only, without having to refer to the document text. used in the L A T EX code should consist of a prefix and a name, delimited by a semicolon: Labels \label{prefix:name} See the code for table 1.1 for a sample label. Common prefixes include: Prefix Use for Chapters, sections, paragraphs sec Tables tab Figures and plots fig 1.1.7 Axis labels and color map should always display the name of the plotted quantity and its unit. A physical quantity Axis labels is the product of a measure value (numerical) and a unit. In contrast, the values going into a plot are purely numerical, i.e. dimensionless. Consider this example: x = 3 cm This equation can be rewritten to: 3 = x/ cm . The left side of the equation is the numerical value of the quantity x , which is drawn in the plot, while the right side is what goes on the axis. A correctly set plot would look like this: 5
30 Velocity v /cm s − 1 20 10 − 6 − 4 − 2 0 2 4 6 Distance x /cm Figure 1.1: A sample plot to show the correct axis labeling. Note that the common notation “Distance x [cm]” is wrong. The square brackets symbolize the unit operator . Applying the unit operator to a quantity returns its unit: [ x ] = cm Read: “The unit of x is cm” The preferred and default colormap of Python’s plotting library matplotlib is Viridis. It Colormap is very linear, readable for partly color-blind people, and remains readable after conversion to grayscale. When you use a colormap, keep in mind that you can choose from many possibilities, and change to Viridis, if available. Figure 1.2 shows a comparison of the old and new default colormaps of matplotlib . (a) Old: Jet (b) New: Viridis Figure 1.2: Comparison of the old and new default colormaps of matplotlib . Viridis (b) is easier to read and converts better to grayscale. 1.2 Math typesetting in a nutshell All conventions presented here are defined in the standard ISO-31 [6, 7, 8]. 1.2.1 Variables, functions and Operators Symbols denoting variables are set italic . L A T EX math mode does that automatically. Variables 6
Recommend
More recommend
