Skip to content

Tip

The following guidelines are based on the most common mistakes in the reports and are constantly updated, please come back to check them regularly.

You can see the date of last edit at the bottom of the page.

Warning

Try to compile every time you change something and revert/fix/ask if it’s not working. Avoid accumulating errors.

Below you can find a list of best practices for writing LaTeX documents. These guidelines are meant to help you write clean, readable, and maintainable LaTeX code.

Also, as the reports will be converted to a web version, these guidelines will help to ensure a smooth conversion process.

A very good starting point for learning LaTeX with Overleaf are the Overleaf's tutorials.

If you have any questions, reach out to FCC IT Support.

When the document does not compile

If the document does not compile despite having fixed the errors, try the following steps:

  • Make sure your browser is up to date, we recommend Chrome as browser.
  • Reload the page.
  • Make sure you don't have any tabs/window open with the same document.
  • Clear the Overleaf cache. You can see here how to do it.
  • Recompile the document from scratch. You can see here how to do it.

If the error persists, please reach out to FCC IT Support.

Warning

Warnings are not errors, but they can lead to errors. Always try to fix them. The majority of warnings we are seeing are due to broken references, labels multiply defined and missing images.

Too many unprocessed floats

If you see the error Too many unprocessed floats, it means that LaTeX has too many figures and tables to process. You can fix this by adding the following line, in chapter.tex, after the section where the error is occurring:

\clearpage

Changelog (CHANGELOG.md)

This report must include a simple changelog in a Markdown file named CHANGELOG.md, placed in the main Overleaf folder (project root). Update it whenever you edit the report in Overleaf.

Writing changelog entries in Markdown

  • Headings use the # symbol in front of text.
  • "# Changelog" is the main title of the page.
  • "## vXX.XX - Unreleased" is the section where you list all current changes.
  • "### Chapter 1", "#### Section 2", "##### Paragraph 1" show where the change happens.
  • Under the appropriate heading, use simple bullet points with "-" and describe the change in one short sentence.
  • Always keep the wording clear and concise.

Rules for the changelog

  • Keep an “Unreleased” section for ongoing work: ## vXX.XX - Unreleased.
  • For each change, show the full hierarchy: for example Chapter → Section → Paragraph (or similar).
  • Use short, clear bullet points (one line each).
  • Write everything in simple Markdown. Quick reference: https://www.markdownguide.org/cheat-sheet/

Example structure for CHANGELOG.md:

# Changelog

It’s crucial to always include the entire hierarchy before writing about changes to a subsection, paragraph, or any other section. For instance, if you’re writing about changes to a section, make sure to include the chapter as well.

## vXX.XX - Unreleased

Below are examples, delete them once you get familiar with the syntax. You can find a guide here: https://www.markdownguide.org/cheat-sheet/.

### Chapter 1
- Change 1
- Change 2

#### Section 2
- Change 1

##### Paragraph 1
- Change 1

### Chapter 2
- Change 1
- Change 2

### Chapter 3
- I changed 3 words in chapter 3.

Custom commands

Below you can find a list of custom commands that we provide to help you write the reports.

Maps

If you want to add a map, use the onlinemap environment.

\onlinemap{filename}{map_url}{pdf_path}{caption}{label}{draft}
  • filename is the name of the low-resolution PDF map in the maps folder of the chapter.
    • Just the name, no need to add the .pdf extension or the path.
    • Maps should not exceed 5MB.
  • map_url is the URL of interactive map in the ArcGIS Portal.
  • pdf_path is the path in CERNBox of the high-resolution PDF version of the map.
    • The PDFs should be uploaded on CERNBox.
    • The uploaded PDFs will be served via this domain: (https://fcc-eisa-media.web.cern.ch/). However, no need to add the domain in pdf_path. pdf_path should be just the path to the PDF file, starting from the root.
  • caption is the caption of the map.
  • label is the label of the map, and should be a lowercase string. We encourage you to use a label that starts with map:.

If you don’t have a map ready when you write the text, you can just add the draft argument, like this:

\onlinemap{example}{https://cern.ch/map}{chapter/map.pdf}{a caption}{map:example}{draft}

and a placeholder will be automatically applied in the document. If you have the map ready, just remove the draft argument.

You can reference in the text with \autoref{label}, just like any other element. Note that label is the text you put in the argument of the onlinemap environment, not a number.

Media (Video or Audio)

If you want to add a media (video or audio) use the onlinemedia environment.

\onlinemedia{type}{URL}{description}{caption}{label}
  • type is the type of media (video or audio).
  • URL is the URL of the media.
  • description is a short description of the media.
  • caption is the caption of the media.
  • label is the label of the media, and should be a lowercase string. We encourage you to use a label that starts with video: or audio:.

You can reference in the text with \autoref{label}, just like any other element. Note that label is the text you put in the last argument of the onlinemedia environment, not a number.

Frequent Mistakes

In the following sections, we will cover the most common mistakes found in the reports and how to avoid them.

Text Formatting

Line Breaks

Do

Let LaTeX handle line breaks automatically for optimal formatting.

This is a line. 

This is another line.

\begin{itemize}
\item Item 1
\item Item 2
\end{itemize}
Don't

Force line breaks manually, as it reduces document flexibility.

This is a line. \\ This is another line.

\begin{itemize} 
\item Item 1 \\
\item Item 2 \\
\end{itemize}

Bold Text

Do

Use \textbf{} for bold text, as it is the preferred method in modern LaTeX.

\textbf{Site radioélectrique}
Don't

Use \bf, as it is outdated and deprecated.

\bf Site radioélectrique

Italics Text

Do

Use \textit{} for italic text, as it is the preferred method in modern LaTeX.

\textit{Site radioélectrique}
Don't

Use \it, as it is outdated and deprecated.

\it Site radioélectrique

Units of measure

Use the following commands to format any type of quantity or unit:

Functionality How to do
Quantity (number + unit) \qty{<number>}{<unit>}
Unit of measure only \si{<unit>}
Number only \num{<number>}

You can find a more complete guide here.

Do

Use the siunitx package to ensure consistent formatting for units.

en ces lieux n’excède pas \qty{5000}{\volt\per\meter} et que le champ magnétique
Don't

Hardcode units manually, which can lead to inconsistent formatting.

en ces lieux n’excède pas 5000~V/m et que le champ magnétique

References

Do

Use \autoref{} for references, as it ensures consistency and adds prefixes automatically.

Walter Brugger pour le Parc de l’école de Lullier (\autoref{fig:patrimoine_nature_PB_jardin_remarquable}) ou bien encore Erik Donht
Don't

Hardcode references manually, as they may break with document changes.

Walter Brugger pour le Parc de l’école de Lullier (Illustration 1) ou bien encore Erik Donht

Section Hierarchy

Do

Follow a logical progression in section hierarchy without skipping levels.

\section{Climat} 
\subsection{Évolution climatique}
\subsubsection{En Auvergne-Rhône-Alpes}
\paragraph{A proximité du Pays de Gex}
Don't

Skip section levels, as it disrupts the logical flow.

\section{Climat} 
\subsubsection{En Auvergne-Rhône-Alpes}

Images

We provide a custom command, named Figure, with capital F, to handle images. Note that images should not exceed 5MB.

Image Placeholder

Do

Use a placeholder for images to see positioning in the document without final images.

\includegraphics[width=\textwidth]{\textbf{example-image-a}}
Don't

Insert text directly as a placeholder for images.

Here goes an image

Figure Placement

Do

Don't specify a position for figures, allowing LaTeX to place them optimally.

\begin{Figure}
\includegraphics[width=\textwidth]{example-image.png}
\caption{Example caption}
\label{fig:example_label}
\end{Figure}
Don't

Force a specific position with [H] as it can disrupt LaTeX's flow.

\begin{Figure}[H]
\includegraphics[width=\textwidth]{example-image.png}
\caption{Example caption}
\label{fig:example_label}
\end{Figure}

Paths

Do

Use relative paths for images.

 \begin{Figure}
 \includegraphics{../img/example-image.png}
 \caption{Example caption}
 \label{fig:example-label}
 \end{Figure}
Don't

Use aboslute paths for images.

 \begin{Figure}
 \includegraphics{src/example-chapter/img/example-image.png}
 \caption{Example caption}
 \label{fig:example-label}
 \end{Figure}

Duplicate Labels

Do

One label.

\caption{text}
\label{fig:example}
Don't

Duplicate labels.

\caption{\label{fig:example}text}
\label{fig0:example}

Nested Labels

Do

One label.

\caption{text}
\label{fig:example}
Don't

Nested labels.

\caption{text
\label{fig:example}}

Footnotesize

Do

Don’t use Footnotesize.

\begin{Figure}
Don't

Use Footnotesize.

\begin{Figure}
\footnotesize

Tables

We provide a custom command, named Table, with capital T, to handle tables. You find below a complete example of a table:

\begin{Table}
\begin{tabular}{c|c}
Cell1 & Cell2 \\
\hline
Cell3 & Cell4 \\
\end{tabular}
\caption{Example caption}
\label{tab:example_label}
\end{Table}

Table Formatting

Do

Ensure consistent headings and alignment in tables.

\begin{tabular}{|c|c|c|}
Cell1 & Cell2 & Cell3 \\
Cell4 & Cell5 & Cell6 \\
\end{tabular}
Don't

Use inconsistent column headings or misaligned cells.

\begin{tabular}{|c|c|c|}
Cell1 & Cell2 \\
Cell3 & Cell4 \\
\end{tabular}

Wrap Text inside Cells

Use the p{} column type to wrap text inside cells.

\begin{tabular}{|p{4cm}|p{6cm}|}
\hline
Header 1 & Header 2 \\
\hline
This is a long piece of text that will automatically wrap to the next line when it reaches the end of the specified width. & Another long text that is set to wrap within a 6cm width column. \\
\hline
\end{tabular}

Space After Table

Do

No space after the table. 

\end{Table}

Don't

Space after the table. 

\end{Table}\\

Bibliography

You can include the references in the src/bib/volume.bib file as showed below.

img.png

You can find all the info on how to fill the file here.

In each chapter you will also find a bib/part.bib file where you can include the references specific to that chapter.

Note that this file is just a placeholder, and it's not actually displayed in the final PDF. It's to be used for your convenience while you are writing the chapter.

The final references must be included in the src/bib/volume.bib file.

Citing

Do

Use \cite{} to handle citations automatically.

According to \cite{patrimoine-ref1}
Don't

Refer to citations manually without using LaTeX commands.

According to reference [1]

URL Handling

Do

Place URLs in the url field. Add the urldate field to specify the date you accessed the URL.

@article{patrimoine-ref1,
    author = {E. Beaupere},
    title = {Escapade dans la campagne Suisse},
    year = {n.d.},
    url = {https://www.savoie-mont-blanc.com/itineraires-velo/escapade-dans-la-campagne-suisse-5844752/},
    urldate = {2024-04-27},
}
Don't

Use howpublished for URLs.

@article{patrimoine-ref1,
    author = {E. Beaupere},
    title = {Escapade dans la campagne Suisse},
    year = {n.d.},
    howpublished = "\url{https://www.savoie-mont-blanc.com/itineraires-velo/escapade-dans-la-campagne-suisse-5844752/}",
}

Bibliography Type

Do

Use the appropriate format for the type of reference. A complete list of entry types can be found here.

@article{patrimoine-ref1,
Don't

Use misc for everything.

@misc{patrimoine-ref1,