day1latex_adjusted1.tex

\documentclass[a4paper,10pt]{report} % {article}
\input{./latex/in1header.tex}

\title{Advanced LaTeX Workshop}
\author{Your Name Here}
\date{19 June 2023} 

\pdfinfo{%
  /Title    (Advance LaTeX Workshop) 
  /Author   (Your Name Here)
  /Creator  (Your Name Here)
  /Producer (InScAPE)
  /Subject  (Intermediate and Advanced LaTeX)
  /Keywords (listing, tikz, figures) 
}
 
\begin{document}
% later: #4 generating index 
%--------------
%\makeindex
%--------------


% \maketitle
 \pagestyle{fancy}
 %\setcounter{page}{1}
 \pagenumbering{roman}

 \section*{Preface} 
 
 This document is a guidebook on intermediate and advanced topics in \LaTeX, with a target audience of researchers and other professionals who often have to use \LaTeX. The most up-to-date version is maintained on GitHub: \href{https://github.com/jchylik/advanced_latex_workshop}{github.com/jchylik/advanced\_latex\_workshop} \\
 
 
 This guidebook was originally started for the purpose of a informal workshop held at the University of Cologne. 
 The original overview follows: 
 \\~\vspace{5ex}
 
%-------- Workshop overview-------------------------------
\begin{tabular}{|p{0.8\textwidth}}
 \textcolor{gray}{
 We are organising an informal \textbf{workshop} on the \textbf{intermediate and advanced topics} in \LaTeX.
Although there are various \LaTeX tutorials and templates floating around, but they often omit some tools and packages that are useful in meteorology and geophysics. The workshop is primary focused on PhD students who are starting to write their thesis, but it is open to other \LaTeX users as well.}
\\
 \begin{enumerate}
 \item   \textcolor{gray}{Monday 19. June --- from 12:45 in CIP room}
 \item   \textcolor{gray}{Wednesday 21. June --- from 15:00 in CIP room} 
\end{enumerate}\\


\noindent
 \textcolor{gray}{ You can work from CIP workstation or bring your own device.}~\vspace{3ex}\\
\end{tabular}
 

 \begin{tabular}{l p{0.7\textwidth}}
   \textcolor{gray}{target audience:} & \textcolor{gray}{people with previous experience with \LaTeX} \\
   \textcolor{gray}{aims:}  & \textcolor{gray}{discuss \LaTeX ~topics practise skills} \\
   \textcolor{gray}{duration:} & \textcolor{gray}{one and half hour from start time or until you start getting tired} \\
   \textcolor{gray}{topics:} & \textcolor{gray}{see following sections \ref{sec:monday} and \ref{sec:wednesday}} \\
   \textcolor{gray}{registration:} & \textcolor{gray}{comment in this Slack thread} \\ 
 \end{tabular}
 
 \pagebreak


%-----------------------------------------------------------------------------
 
 \maketitle
 
\section{Monday} \label{sec:monday}




\subsection{Combining Document from Pieces}
Combining documents from multiple files speeds up the editing process, makes collaboration easier, and also lowers the risk of accidentally rewriting something. You can see an example how most of the header of this document is in a separate file.\\

\lstinputlisting[ language={[latex]tex},      % tex syntax, latex option
  caption={Input statement}, label={code:input}, 
  firstline=1, firstnumber=1, lastline=3, numbers=left, captionpos=b,
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
]{./day1latex_adjusted1.tex} 

The input statements could be then again used in the file that was itself inputted:

\lstinputlisting[ language={[latex]tex},      % tex syntax, latex option
  caption={Input statement inside in1header.tex}, label={code:input2}, 
  firstline=50, firstnumber=50, lastline=54, numbers=left, captionpos=b,
  frame=single, 
  basicstyle=\footnotesize\color{cyan},
  keywordstyle=\color{magenta}, stringstyle=\color{brown}, commentstyle=\color{gray},
  breaklines=true
]{./latex/in1header.tex} 

% #1 
To try this, write some dummy text in a separate file and insert is here using the \texttt{input} command:\\
\input{./data/just2lines.txt}\\


% #2  
The \texttt{input} statement can also work on multiple levels
\begin{enumerate}
    \item Make a copy of \texttt{style1headerfooter.tex} and modify it.
    \item Open \texttt{in1header.tex} and replace \texttt{style1headerfooter.tex} with the name of your new file.
    \item Recompile the main document.
\end{enumerate} 



\subsection{Automatically Generated Lists} \label{sec:lists}  
There is an easy way how to create list of figures, tables, as well as index of phrases. 
 See on the following page: 

% We are going to start witth this documet
%  #1 change the class of document from article to report
%  



%\pagenumbering{roman}
%   \let\clearpage\relax 
   \tableofcontents 
    \label{contents}
   \addcontentsline{toc}{section}{Table of Contents}  
   \let\clearpage\relax
   \addcontentsline{toc}{section}{List of Tables}
    \listoftables  
  \let\clearpage\relax
   \addcontentsline{toc}{section}{List of Figures}  
   \listoffigures\label{lof}  
    \chapter*{List of Symbols}
   \addcontentsline{toc}{section}{List of Symbols}
   \input{./latex/list_symbols.tex}    
% \newpage

\setcounter{chapter}{1}
\setcounter{figure}{1} 
\addcontentsline{lof}{figure}{ \arabic{chapter}.\arabic{figure}  Fake Figure} 

\newpage 

\setcounter{chapter}{2}
\newcounter{warning}[chapter]
\pagenumbering{arabic}
\chapter{Monday} 

\section{Automatically Generated Lists}\label{sec:automatic}
On the previous pages we can see lists of tables, figures, symbols and abbreviations. The first three of the lists are automatically generated, using commands:

\begin{lstlisting}[language={[latex]tex},
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
  \tableofcontents
  \listoftables
  \listoffigures
\end{lstlisting}

\subsection{Adding Entries to List}
 Since we want the lists of tables and figures to appear in the table of content, we manually add an entry. The command \texttt{addcontentsline} takes three arguments:
 \begin{enumerate}[label=\arabic*)]
  \item Which list we are adding an item into,
  \item Which kind of item we are adding,
  \item The text that appear in the list
 \end{enumerate}

 We have added the list of figures to the table of content (toc) using: 
 \begin{lstlisting}[language={[latex]tex},
   frame=single,
   basicstyle=\footnotesize\color{darkgray}, 
   keywordstyle=\bf\color{magenta},
   commentstyle=\color{ForestGreen},  %
   breaklines=true
   ]
   \addcontentsline{toc}{section}{List of Figures} 
   \listoffigures
\end{lstlisting}

Similarly to adding to \textbf{toc}(table of content), we can add to the 
\textbf{lof} (list of figures), \textbf{lot} (list of tables), and possibly other defined lists.   

  \subsection{Force Adding Entries to Lists}
  Sometimes we are faced with a situation that figure would be inserted as a separate page afterwards, or that we want to refer to a figure in the chapter that has not yet been written. Instead of compiling the document with multiple warnings or errors, we can force add entries into the table of content, table of lists, etc.\\
  
  You can see that in the List of figures is a non-existent figure called "Figure to be added later". This has been created using: 
  
  \stepcounter{table} 
  \addcontentsline{lot}{table}{ \arabic{chapter}.\arabic{table}  Fake Table} 
  
   \begin{lstlisting}[language={[latex]tex},
    frame=single,
    basicstyle=\footnotesize\color{darkgray}, 
    keywordstyle=\bf\color{magenta},
    commentstyle=\color{ForestGreen},  %
    breaklines=true
   ]
   \addcontentsline{lof}{figure}{ \arabic{chapter}.\arabic{figure} Figure to be added later}
   \addcontentsline{lot}{table}{ \arabic{chapter}.\arabic{table}  Fake Table}
\end{lstlisting}

\subsection{Formatting of Lists}

The list of Tables and the List of Figures are currently each on a separate page, which is bit wasteful. In order to remove the automatic page break, we just add one line : 
\begin{lstlisting}[language={[latex]tex}, 
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
   \addcontentsline{toc}{section}{List of Tables}
   \listoftables  
   \let\clearpage\relax    % removes pagebreak                       
   \addcontentsline{toc}{section}{List of Figures}  
   \listoffigures
\end{lstlisting}

 \setcounter{section}{1}
 %\setcounter{subsection}{7}  
 \section{Counters}%\label{sec:counters}
How did we suddenly jump from section \ref{sec:figures} to \ref{sec:counters}  ? We are now in the chapter \arabic{chapter} or \Roman{chapter} in roman numbers.\\

\subsection{What Counters do}\label{sec:counters}
To keep track of sections, pages, figures, and other numbered parts of the document, we use \textbf{counters}. We can always outputs the current value of a counter, for example the section:
\begin{lstlisting}[language={[latex]tex}, 
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
  We are currently in  the section \arabic{section}.
\end{lstlisting}

We are currently in  the section \arabic{section}.\\

Some of the previous pages are not numbered in arabic numbers, but in roman numbers. We can get the same format also for section and chapter counters. 

\begin{lstlisting}[language={[latex]tex}, 
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
  We are currently in  subsection \roman{subsection}  % small roman numerals 
  of section \alph{section}                           % letters
  of chapter \Roman{chapter}.                         % capital roman numerals
\end{lstlisting}
 We are currently in  subsection \roman{subsection}  % small roman numerals 
  of section \alph{section}                           % letters
  of chapter \Roman{chapter}. \\                      % capital roman numerals

  We can also refer to counters in references.
  
  

\addtocounter{subsection}{3}
\subsection{This is Empty Subsection}\label{sec:empty}

\subsection{Modifying counters}

We could see that we have directly jumped from section \ref{sec:counters} to section \ref{sec:empty} and simply skipped the numbers in between.
How have we done that?
\begin{lstlisting}[language={[latex]tex},
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
\addtocounter{subsection}{3}
\subsection{This is Empty Subsection}  
\end{lstlisting}

Apart from increasing the counter by command \texttt{ \textbackslash addtocounter}, we cal also just increment the counter by one using \texttt{ \textbackslash stepcounter} or set it to a desired value using \texttt{ \textbackslash setcounter} command. 
  
\subsection{Custom Counters}
Yes, we can also add custom counters, such as numbering of warning messages:\\

 \stepcounter{section}
 \stepcounter{warning}
 Warning \arabic{warning}:  No new ideas here.\\
 \addtocounter{warning}{4}
 Warning \arabic{warning}:  Some new ideas here.\\
 
 How have we done this? Firstly, we need to define a new counter
\begin{lstlisting}[language={[latex]tex}, 
  frame=single,
  basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true
  ]
  \newcounter{warning}[chapter] 
\end{lstlisting}
The first required argument is the name of the counter and the second, optional argument, is when we reset it.
Afterwards we can set and step up this counter in the same way as for the sections. Outputting the values  of the counters also works the same way as for the sections, we just use the name of the counter:
\begin{lstlisting}[language={[latex]tex}, frame=single,basicstyle=\footnotesize,
  keywordstyle=\bf,
  commentstyle=\it\color{gray}
  ]
  Warning \arabic{warning}:  No new ideas here.\\
\end{lstlisting}

\setcounter{section}{\value{warning}}

\subsection{Counters Interaction}
Now if we consider that the output of a counter is also a value, we can play further tricks. 

Warning \arabic{warning}:  The section now has the same number as this warning. We achieved that by using:\\

\begin{lstlisting}[language={[latex]tex}, frame=single,basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  
  breaklines=true
  ]
\setcounter{section}{\value{warning}}  % set value to the current  value of another counter 
\end{lstlisting}

\subsubsection{Exercise:}
In this small exercise, we are going to add an entry to the table of content that would list the current chapter, section, and the value of the warning counter, for example:\\

\begin{center}
 3.5.Exercise answer: number 7 was the latest warning 
\end{center}

% Solution (shall be removed from the input)
\addcontentsline{toc}{subsection}{\arabic{chapter}.\arabic{section} the latest warning was number \arabic{warning}}



\newpage 
 \section{Modifying Plots and Schematics}\label{sec:figures}
 
 Inserting raster images in LaTeX is easy, however things get interesting when we start inserting vector graphics. Let us have a look on en example (Figure \ref{fig:figures}). Warning \arabic{warning}:  The figure might be boring.\\
 %\newpage
 %\thispagestyle{empty}
 %--> replace example with figure of radiation?
 \begin{figure}[!ht] 
         \input{./latex/diagram.tex}       % insert the diagram as first panel
     \includegraphics[width=0.52\textwidth]{./figures/prof_tend.pdf}
        \caption[Diagrams and plots]{Here we combine a \textbf{Tikz} diagrams and images. Note that there the references within the diagram include active hyperlinks to other part of this document.}    
      \label{fig:figures}    
 \end{figure}
 
\subsection{Picture}
The figure above is missing labels for some of the panels. Also, we would like to move diagram on the left little bit higher and the one right little bit lower. Instead of opening the figures in some graphical editor, we can perform these tasks \LaTeX with the environment \texttt{picture}. We then encapsulate both panels in the environment, and define the coordinates where each panel is located. You can see the result in figure \ref{fig:picture}. 
\begin{lstlisting}[language={[latex]tex}, frame=single,basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  % 
  breaklines=true
  ]
 \begin{picture}(220,180)              % define the size of the picture 
 \put(  0,  20){                       % first panel shifted up by 20 (mm, points, etc.)
     \input{./latex/diagram.tex}       % insert the diagram as first panel
 }
 \put(160,  0){                        % first panel shifted right by 160 (mm,
     \includegraphics[width=\textwidth]{./figures/prof_tend.pdf} 
 }
 \put(  0,  170){                      % position of the label for the first panel
     {\scriptsize a)}                  % label for the first panel 
 }
 \put(185,  170){                     % position of the label for the second panel
     {\scriptsize b)}                  % label for the second panel 
 }
\end{picture} \caption[Picture package]{Here we take ...
\end{lstlisting}
\begin{figure}[h]
 \begin{picture}(240,175)              % define the size of the picture 
 \put(  0,  20){                       % first panel shifted up by 20 (mm, points, etc.)
     \input{./latex/diagram.tex}       % insert the diagram as first panel
 }
 \put(170,  0){                        % first panel shifted right by 160 (mm,
     \includegraphics[width=0.52\textwidth]{./figures/prof_tend.pdf}
 }
 \put(  0,  170){                      % position of the label for the first panel
     {\scriptsize a)}                  % label for the first panel 
 }
  \put(185,  170){                     % position of the label for the second panel
     {\scriptsize b)}                  % label for the second panel 
 }
\end{picture}
        \caption[Picture package]{Here we take previous figure and use the picture environment to improve layout and add labels. }    
      \label{fig:picture}   
\end{figure}
 
 \subsection{TikZ}
 
 Figure  \ref{fig:figures} also shows an example of a vector graphics that is defined directly in \LaTeX. Out of various available packages, we picked Tikz. In the header of the \LaTeX file we should declare which parts of the package we want use:
  
 \begin{lstlisting}[language={[latex]tex}, frame=single,basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true,
  ]
   \usepackage{tikz} 
   \usetikzlibrary{arrows,positioning}
 \end{lstlisting}
 
 Creating the flowchart is relatively simple. From the broad range of graphical function available in the Tikz package, we use nodes and edges. In the text fields in the flowchart we can than use various other \LaTeX commands.\\
 We will have a brief look at an example:\\
 
\lstinputlisting[ language={[latex]tex},      % tex syntax, latex option
  caption={Tikz Latex code for Figure \ref{fig:picture}a }, label={code:thislatex}, 
  firstline=2, firstnumber=2, % lastline=387,
  numbers=left, captionpos=b,
  basicstyle=\scriptsize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true,
  frame=single
]{./latex/diagram.tex}

In tikzpicture consists of nodes and edges. For noded we define their type, relative position, name, and displayed text. For edges we the define their shape and which nodes they are connecting, and we can also add a text to them. The other option is to place nodes at exact positions that, as the following example shows:

\lstinputlisting[ language={[latex]tex},      % tex syntax, latex option
  caption={Tikz Latex code for Figure \ref{fig:picture}b }, label={code:thislatex}, 
  firstline=3, firstnumber=3,  lastline=6,
  numbers=left, captionpos=b,
  basicstyle=\scriptsize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true,
  frame=single
]{./latex/flowchart.tex}
 
 \subsection{Standalone}
 Some journals request you to upload each figure as a separate pdf. However, what can you do figure consists of multiple panels with labels added in LaTeX? No, you do not need to replot the figure, and you do not need to insert the figure as a separate page. Instead you use \textbf{standalone} document to produce a small image in pdf format. Instead of class such as articles or report, we start the source file with the standalone class:
 
  \begin{lstlisting}[language={[latex]tex}, frame=single,basicstyle=\footnotesize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  %
  breaklines=true,
  ]
  \documentclass{standalone}
 \end{lstlisting}
 followed by rest of the header and a short body. See an example \href{./latex/standalone.tex}{latex/standalone.tex} of such document. \\
 
 
 Once you compile a standalone document, you can use it as other graphical elements in pdf format. You can as well include it as an image in this document (see the example on the next page).
  
 \begin{figure}[!h] 
     %\input{./latex/diagram.tex}
    % ---- directly consrtruction diagram--------------
      % \begin{center}
      \tikzstyle{decision} = [diamond, draw, fill=blue!20, text width=8em, text badly centered, node distance=10em, inner sep=0pt]
      \tikzstyle{block} = [rectangle, draw, fill=blue!20, text width=8em, text centered, rounded corners,node distance=10em ,  minimum height=3em]
      \tikzstyle{block_done} = [rectangle, draw, fill=GreenDone, text width=8em, text centered, node distance=10em, rounded corners, minimum height=3em]
      \tikzstyle{block_special} = [rectangle, draw, fill=lightyellow, text width=8em, text centered, node distance=10em, rounded corners, minimum height=3em]
      \tikzstyle{line} = [draw, -latex']
      \tikzstyle{cloud} = [draw, ellipse, fill=lightyellow, node distance=8em, minimum height=0ex]

      \input{./latex/flowchart.tex}
   \caption{Here we have a Tikz diagram}
   \label{fig:directly} 
   \end{figure} 
    
    % ---- inserting it from standalone pdf ------------------
   \begin{figure}[!ht]
    \includegraphics[width=\textwidth]{./latex/standalone.pdf}
        \caption[Diagrams and plots]{We can also compile the figure as separate \textbf{standalone} \index{standalone} pdf and then include it as a graphical element. }  
      \label{fig:standalone}
 \end{figure}

 \newpage 
 
 \section{Customizing Links, References, and Citations}
 So far all the references to the figures, sections, pages, and other counters were marked by brick-red colour of the text. Could we change this style? Not only we can modify the text style of link, the styles can even vary, such as modifying the style of links to other parts of the same document (\nameref{sec:automatic}) and links to \href{https://geomet.uni-koeln.de/en/}{external websites}, as well as links to file such as this document \href{./day1latex.pdf}{./day1latex.pdf}.\\
 
 As you can see in the previous paragraph, we can set different formatting to different types of links. In order to achieve that, we need to include in the header first the package \texttt{hyperref} and then set up options using the command
 \texttt{\textbackslash hypersetup} in the header of the \LaTeX document:\\
 
 \lstinputlisting[ language={[latex]tex},      % tex syntax, latex option
  caption={hypersetup inside in1header.tex}, label={code:hyper}, 
  firstline=97, firstnumber=97, lastline=114, numbers=left, captionpos=b,
  frame=single,
  basicstyle=\scriptsize\color{darkgray}, 
  keywordstyle=\bf\color{magenta},
  commentstyle=\color{ForestGreen},  % 
  breaklines=true
]{./latex/in1header.tex} 
 
 Apart from the basic colour for the links (\texttt{linkcolor}), there are different colours for citation (\texttt{citecolor}), links to files (\texttt{filecolor}), and the web links (\texttt{urlcolor}).
 \pagebreak
 
 \section{Version Control and Comparison}
 We also look at the external tools such as \texttt{latexdiff} that compares \LaTeX files and  \texttt{pdfdiff} that compares \( \ldots \) you know what.\\
 
 Latexdiff can be run as shell command. The arguments are two \LaTeX files, and the output is \LaTeX code which clearly marks which lines of the document differ between the files and which ones are the same. We can redirect the output to a new file.
 
 \begin{lstlisting}[language={bash}, frame=single,basicstyle=\footnotesize
    ,basicstyle=\footnotesize\color{cyan}    % setting font
   ,keywordstyle=\color{magenta}            % setting font for keywords 
   ,stringstyle=\color{brown}
   ,commentstyle=\color{ForestGreen} 
 ]
  latexdiff day1latex.tex day1latex_adjusted1.tex > differences_day1latex.tex
\end{lstlisting}~\vspace{1ex}
%\stepcounter{samplecode}
  


% #4 generating index 
%   \clearpage
%   \phantomsection 
%   \addcontentsline{toc}{section}{Index}  
%   \label{index}  
%   Longer documents sometimes include index pages.
%   \printindex  

\section{Outlook for Wednesday}\label{sec:wednesday}

\begin{itemize}
 \item Tables
 \item Macros
 \item Index
 \item More on version Control
\end{itemize}

Continue with the file: \texttt{day2latex.tex}


 
\label{LastPage}
\newpage


\end{document}