Fix index entries of \apiasp; add pictures for Ks and shunt signals

assets/manual/manual.tex

@@ -15,7 +15,7 @@
 \usepackage{amsmath,amssymb,siunitx}
 \usepackage[x11names,svgnames]{xcolor}
 \usepackage{tikz}
-\usetikzlibrary{arrows,backgrounds,calc,patterns}
+\usetikzlibrary{arrows,backgrounds,calc,patterns,shapes.geometric}
 
 \usepackage{imakeidx}
 \makeindex[columns=1,title=Alphabetical Index,intoc]
@@ -79,7 +79,7 @@
 \providecommand{\apient}[2]{\apientp{##1}{##2}\index{##1}}
 \providecommand{\apip}[2]{\apientp{\texttt{##1}}{##2}}
 \providecommand{\api}[2]{\apient{\texttt{##1}}{##2}}
-\providecommand{\apiasp}[1]{\apient{##1}{signal aspect}}
+\providecommand{\apiasp}[1]{\apientp{##1}{signal aspect}\index{#1!##1}}
 \providecommand{\apicmd}[1]{\api{##1}{command}}
 \providecommand{\apienum}[1]{\apip{##1}{enumeration}}
 \providecommand{\apifield}[1]{\apip{##1}{field}}
@@ -101,6 +101,85 @@
   tcb/.pic = {
     \draw (0,0) -- (0,0.2);
     \draw [<->] (-0.15,0.2) -- (0.15,0.2);
+  },
+  Ks signal/.pic = {
+    \fill[black] (-1,-1.3) rectangle (1,1.6);
+    \fill[gray] (-0.7,1.3) circle [radius=0.1];
+    \fill[gray] (0,1) circle [radius=0.2];
+    \fill[gray] (-0.4,0.2) circle [radius=0.2];
+    \fill[gray] (0.4,0.2) circle [radius=0.2];
+    \foreach \x in {-0.3,0,0.3} {
+      \fill[gray] (\x,-0.5) circle [radius=0.1];
+    }
+    \foreach \x in {-0.3,0} {
+      \fill[gray] (\x,-0.8) circle [radius=0.1];
+    }
+  },
+  Ks signal Hp 0/.pic = {
+    \pic at (0,0) {Ks signal};
+    \fill[red] (0,1) circle [radius=0.2];
+  },
+  Ks signal Hp 0 with Sh 1/.pic = {
+    \pic at (0,0) {Ks signal Hp 0};
+    \foreach \x/\y in {0/-0.5,-0.3/-0.8} {
+      \fill[white] (\x,\y) circle [radius=0.1];
+    }
+  },
+  Ks signal Ks 1/.pic = {
+    \pic at (0,0) {Ks signal};
+    \fill[green] (-0.4,0.2) circle [radius=0.2];
+  },
+  Ks signal Ks 2/.pic = {
+    \pic at (0,0) {Ks signal};
+    \fill[orange] (0.4,0.2) circle [radius=0.2];
+  },
+  shunt signal/.pic = {
+    \fill[black] (-1,0) -- (-1,-1) -- (1,-1) -- (1,0) -- (0.5,0.5) -- (-0.5,0.5) -- cycle;
+    \fill[gray] (-0.5,0) circle [radius=0.1];
+    \fill[gray] (0.5,0) circle [radius=0.1];
+    \fill[gray] (-0.5,-0.7) circle [radius=0.1];
+    \fill[gray] (0.2,0) circle [radius=0.1];
+  },
+  shunt signal Sh 0/.pic = {
+    \pic at (0,0) {shunt signal};
+    \fill[red] (-0.5,0) circle [radius=0.1];
+    \fill[red] (0.5,0) circle [radius=0.1];
+  },
+  shunt signal Sh 1/.pic = {
+    \pic at (0,0) {shunt signal};
+    \fill[white] (-0.5,-0.7) circle [radius=0.1];
+    \fill[white] (0.2,0) circle [radius=0.1];
+  },
+  signal sign Zs 3/.pic = {
+    \node[fill=black,text=white,regular polygon,regular polygon sides=3,inner sep=0.5ex,shape border rotate=180] at (0,0) {\Huge #1};
+  },
+  signal sign Zs 10/.pic = {
+    \fill[black] (-1,-1) -- (0,0) -- (1,-1) -- (1,4) -- (0,5) -- (-1,4) -- cycle;
+    \fill[white] (-0.8,-0.6) -- (0,0.2) -- (0.8,-0.6) -- (0.8,4) -- (0,4.8) -- (-0.8,4) -- cycle;
+    \fill[black] (-0.6,-0.2) -- (0,0.4) -- (0.6,-0.2) -- (0.6,4) -- (0,4.6) -- (-0.6,4) -- cycle;
+  },
+  signal sign Lf 1 and 2/.pic = {
+    \draw[fill=orange] (-0.5,-0.75) rectangle (0.5,0.75);
+    \node at (0,0) {\Huge #1};
+  },
+  signal sign Lf 3/.pic = {
+    \draw (-0.5,-0.75) rectangle (0.5,0.75);
+    \node at (0,0) {\Huge E};
+  },
+  signal sign Lf 7/.pic = {
+    \draw (-0.5,-0.75) rectangle (0.5,0.75);
+    \node at (0,0) {\Huge #1};
+  },
+  signal sign Ra 10/.pic = {
+    \draw (-1.5,0) -- (1.5,0) arc [start angle=0, end angle=180, radius=1.5];
+    \node [above] at ($(0,0)+(0,2.4em)$) {\large Halt};
+    \node [above] at ($(0,0)+(0,1.2em)$) {für};
+    \node [above] at (0,0) {Rangierfahrten};
+  },
+  signal sign PAM/.pic = {
+    \draw (-0.5,-0.5) rectangle (0.5,1);
+    \node at (0,0) {\huge S};
+    \draw [green,->,very thick,line width=2pt] (0,0.4) -- (0,0.8);
   }
 }
 \ifdefined\HCode
@@ -888,19 +967,43 @@ The signal placement conventions assume right-hand traffic.
 \subsubsection{Ks signals}
 Ks signals are combined signals that combines the features of main signals and distant signals. The system was developed by the Deutsche Bahn AG after the Deutsche Bundesbahn in West Germany and the Deutsche Reichsbahn in East Germany merged, and the goal was to replace the other four signaling system in use in Germany, which still exist today.
 
-Ks signals have the following aspects:
+A real-life Ks signal looks similar to this:
+\begin{centeredtikzpicture}
+  \pic at (0,0) {Ks signal};
+\end{centeredtikzpicture}
+
+Ks signals in \advtrains{} have the following aspects:
 \begin{apidoc}{Signal aspects!Ks signals}
 \item \apiasp{Hp 0} Red light: Stop.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {Ks signal Hp 0};
+  \end{centeredtikzpicture}
 \item \apiasp{Ks 1} Green light: Proceed at maximum speed or with the speed limit shown on the Zs 3 indicator on the main signal (if present) and expect to pass the next main signal at maximum speed or, if the green light is flashing, with the speed limit shown on the Zs 3v indicator directly below the main signal.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {Ks signal Ks 1};
+  \end{centeredtikzpicture}
 \item \apiasp{Ks 2} Yellow light: Proceed at maximum speed or with the speed limit shown on the Zs 3 indicator on the main signal (if present) and expect to stop at the next main signal.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {Ks signal Ks 2};
+  \end{centeredtikzpicture}
 \end{apidoc}
 
-In addition, Sh 1 (see below) may also appear along with Hp 0, in which case the train proceeds in shunt mode.
+In addition, Sh 1 (see below) may also appear along with Hp 0:
+\begin{centeredtikzpicture}
+  \pic at (0,0) {Ks signal Hp 0 with Sh 1};
+\end{centeredtikzpicture}
+In this case, the train proceeds in shunt mode.
 
 \subsubsection{Shunt signals}
 \begin{apidoc}{Signal aspects!Shunt signals}
 \item \apiasp{Sh 0} Two horizontally aligned red lights: Stop.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {shunt signal Sh 0};
+  \end{centeredtikzpicture}
 \item \apiasp{Sh 1/(ex-DR) Ra 12} Two white lights aligned on a slanted line: Shunting allowed.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {shunt signal Sh 1};
+  \end{centeredtikzpicture}
 \end{apidoc}
 
 \subsubsection{Signal signs}
@@ -908,18 +1011,39 @@ In addition, Sh 1 (see below) may also appear along with Hp 0, in which case the
 
 \begin{apidoc}{Signal aspects!Signal signs}
 \item \apiasp{Zs 3} White number on a black background: Proceed with the main speed restriction shown on the sign.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Zs 3=3};
+  \end{centeredtikzpicture}
 \item \apiasp{Zs 10} An upward-pointing arrow: The speed restriction set by Zs 3 and regular signals is lifted.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Zs 10};
+  \end{centeredtikzpicture}
 \item \apiasp{(ex-DR) Lf 1/2} Black number on an orange background: Proceed with the temporary speed restriction shown on the sign.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Lf 1 and 2=10};
+  \end{centeredtikzpicture}
 \item \apiasp{Lf 3} Black ``E'' on a white background: The temporary speed restriction set by Lf 1/2 is lifted.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Lf 3};
+  \end{centeredtikzpicture}
 \item \apiasp{Lf 7} Black number on a white background: Proceed with the line speed restriction shown on the sign.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Lf 7=6};
+  \end{centeredtikzpicture}
 \item \apiasp{Ra 10} The text ``Halt für Rangierfahrten'' on a white semicircle: Do not proceed if the train is in shunt mode. This signal is conventionally placed on the left side of the track.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign Ra 10};
+  \end{centeredtikzpicture}
 \item \apiasp{PAM} The text ``S'' below a green arrow: Proceed without shunt mode. This sign does not have a real-life counterpart.
+  \begin{centeredtikzpicture}
+    \pic at (0,0) {signal sign PAM};
+  \end{centeredtikzpicture}
 \end{apidoc}
 
 \subsubsection{Differences from real-life signals}
 The signal book at \url{https://www.bahnstatistik.de/Signale_pdf/SB-DBAG.pdf} is used for reference. This list is not comprehensive.
 \begin{itemize}
-\item The speed is indicated in m/s instead of km/h.
+\item The speed is indicated in m/s instead of multiples of 10km/h.
 \item Certain visual effects, such as making signal signs reflective or lit at night, are not implemented.
 \item Distant signaling is not implemented.
 \item The location of most signals are not checked. The location of the mounted Zs 3(v) indicators are checked relative to the main signal.