Complement information on T junctions; add LuaATC station example

2 files changed, 55 insertions, 6 deletions

diff --git a/assets/manual2/manual.tex b/assets/manual2/manual.tex
index e271263..3d7502e 100644
--- a/assets/manual2/manual.tex
+++ b/assets/manual2/manual.tex
@@ -2,11 +2,19 @@
 \usepackage[a4paper,margin=1in]{geometry}
 \usepackage[T1]{fontenc}
 \setlength{\parindent}{0pt}
+\usepackage{listings}
 \usepackage{hyperref}
 \usepackage{amsmath,siunitx}
 \usepackage[x11names,svgnames]{xcolor}
 \usepackage{tikz}
-\usetikzlibrary{arrows,calc}
+\usetikzlibrary{arrows,backgrounds,calc}
+
+\lstdefinestyle{luastyle}{
+  language=[5.1]Lua,
+  basicstyle=\ttfamily,
+  columns=spaceflexible,
+  tabsize=2
+}
 
 \newcommand{\argname}[1]{$\mathit{\langle}$\textrm{\textmd{\textit{#1}}}$\mathit{\rangle}$}
 
@@ -23,7 +31,7 @@
 }
 
 \newenvironment{ttdescription}{
-  \renewcommand{\descriptionlabel}[1]{\texttt{\textbf{##1}}}
+  \renewcommand{\descriptionlabel}[1]{\hspace{\labelsep}\texttt{\textbf{##1}}}
   \begin{description}
   }{
   \end{description}
@@ -62,6 +70,7 @@
 \item Arguments to functions and ATC commands are delimited using angle brackets \argname{like this}.
 \item Argument names are generally lowercase, but the first letter may be capitalized.
 \item Lua string constants are written without quotation marks when the content does not resemble any numeric or symbolic constant and when used as enumerators or table indices.
+\item Like in other parts of advtrains, Lua code is indented with tabs.
 \end{itemize}
 
 \mainmatter
@@ -154,7 +163,7 @@ Turnouts are tracks that connect tracks from more than one direction. Some examp
 
 The figure above aligns the tracks in a way that they always merge into the track that connects to the south. This is mainly done for intuitivity - you can rotate the turnouts freely in any of the 16 directions.
 
-\section{Crossings}
+\section{Crossings}\label{s:xings}
 There are a few crossing nodes that allow you to create intersections:
 \begin{itemize}
 \item Perpendicular crossings: intersections where two tracks are perpendicular to each other
@@ -201,6 +210,8 @@ It is also possible to create track layouts without using crossings. Some exampl
   }
 \end{centeredtikzpicture}
 
+Exercise: Build a T junction. You will need this later in section \ref{s:iljunctions}. You can also look at the scheme in that section if you need a hint.
+
 \section{Special tracks}
 
 Advtrains also have a few special tracks, some of which are explain in their own sections.
@@ -620,7 +631,9 @@ The previous sections were mainly theoretical in that the sections mostly introd
 
 \subsection{Junctions}\label{s:iljunctions}
 
-One of the most important considerations when setting up interlocking at a junction is to make sure that multiple trains can go through the junction at the same time when possible. For example, look at the junction below:
+One of the most important considerations when setting up interlocking at a junction is to make sure that multiple trains can go through the junction at the same time when possible.
+
+As an exercise in section \ref{s:xings}, you were asked to build a T junction. A scheme is shown below if you are stuck. Try to interlock the junction based on what you have learned in the last few sections.
 
 \begin{centeredtikzpicture}[ultra thick]
   \draw [->] (-0.5,-1.5) -- (-0.5,0) arc [start angle=0,end angle=90,radius=1] -- (-3,1);
@@ -631,8 +644,6 @@ One of the most important considerations when setting up interlocking at a junct
   \draw (-3,1) -- (3,1);
 \end{centeredtikzpicture}
 
-(Note: the diagram is a scheme - it is up to you to figure out the actual placement of the tracks.)
-
 The lazy method would be to set up the entire junction as a single track section - you only need 6 TCBs for that. However, a train passing through would occupy the entire junction, even when two trains could use the junction at the same time - for example, a train going from east to west and another one from west to east. This can be solved by a slighly more complicated setup with four sections, each shown below with a different color:
 
 \begin{centeredtikzpicture}[ultra thick]
@@ -650,6 +661,10 @@ The lazy method would be to set up the entire junction as a single track section
   \draw [green] (0.5,0) arc [start angle=0,end angle=15,radius=2];
 \end{centeredtikzpicture}
 
+An example setup can be found in section \ref{s:stjunction}.
+
+It is also possible to build the junction on multiple levels. This is known as grade separation. In real life, grade-separated railway junctions are not common, mostly because of the larger curve radii and slopes that are notably less steep (for example the steepest slope of the Schwarzwaldbahn in Baden, which has an altitude between 384m and 832m, is only 2\%). As an exercise, you can try to make the T junction grade-separation.
+
 \subsection{Track capacity and deadlock}\label{s:ilcapacity}
 You can not infinitely add trains to a line. If you do, you will end up with a deadlock, where every train is stuck at a red light, waiting for the previous train to clear the track section ahead, while the previous train is also stuck at a red light, waiting for the train ahead of it to leave the section ahead, and so on:
 
@@ -796,6 +811,29 @@ The signal book at \url{https://www.bahnstatistik.de/Signale_pdf/SB-DBAG.pdf} is
 
 LuaATC offers the ability to run Lua code. It is provided by the \texttt{advtrains\_luaautomation} mod. The documentation for LuaATC can be found in \texttt{advtrains\_luaautomation/README.md} file, but it may be included here in the future.
 
+\chapter{Example setups}\label{s:sexamples}
+This chapter shows some example setups that you can use on your rail lines. These are intended as examples and not standards - it is up to you to develop your own standards.
+
+\section{Station code using LuaATC}
+\lstinputlisting[style=luastyle]{station.lua}
+
+\newpage
+\section{T junction}\label{s:stjunction}
+\begin{centeredtikzpicture}[very thick,draw=white]
+  \fill [red] (-0.5,6.5) rectangle ++(16,3);
+  \fill [orange] (-0.5,7.5) |- ++(3,-3) -- ++(2,-2) |- ++(3,-3) -- ++(0,8) -- cycle;
+  \fill [green] (15.5,7.5) |- ++(-3,-3) -- ++(-2,-2) |- ++(-3,-3) -- ++(0,8) -- cycle;
+  \fill [blue] (2.5,7.5) -- ++(5,-5) -- ++(5,5) -- cycle;
+  \draw [shift={(-0.5,-0.5)},gray,thin] (0,0) grid (16,10);
+  \foreach \x/\s in {0/1,-15/-1} {
+    \draw [<->,xscale=\s] (\x,6) -- ++(2,0) -- ++(2,-1) -- ++(1,-1) -- ++(1,-2) -- ++(0,-2);
+    \draw [<-,xscale=\s] (\x,9) -- ++(2,0) -- ++(2,-1) -- ++(4,-4) -- ++(1,-2);
+  }
+  \foreach \y in {6,9} {
+    \draw (2,\y) -- ++(12,0);
+  }
+\end{centeredtikzpicture}
+
 \part{Developer's Manual}
 
 \chapter{The \texttt{advtrains} table}\label{s:tadvtrains}
diff --git a/assets/manual2/station.lua b/assets/manual2/station.lua
new file mode 100644
index 0000000..fae7525
--- /dev/null
+++ b/assets/manual2/station.lua
@@ -0,0 +1,11 @@
+function F.station(station_name)
+	if event.train then
+		atc_send("B0WOL")
+		atc_set_text_inside(station_name)
+		interrupt(10, "depart")
+	end
+	if event.int and event.message == "depart" then
+		atc_set_text_inside("")
+		atc_send("OCD1SM")
+	end
+end