Add RWT documentation; minor corrections.

1 files changed, 50 insertions, 8 deletions

diff --git a/assets/manual2/manual.tex b/assets/manual2/manual.tex
index 17a4aa0..24f6fe6 100644
--- a/assets/manual2/manual.tex
+++ b/assets/manual2/manual.tex
@@ -62,11 +62,16 @@
 \addcontentsline{toc}{section}{Introduction}
 Advtrains is a mod with the goal of introducing realistic trains and rail equipments. It also has features allowing automated trains on a large scale, including interlocking and a few methods of scripting.
 
-This manual is written for the specific version of advtrains that the corresponding \LaTeX{} source is distributed with. It is dividied into two parts, where the first part mainly documents the various features of advtrains, and the second part focuses on the internals of advtrains.
+This manual is written for the specific version of advtrains that the corresponding \LaTeX{} source is distributed with. It is divided into two parts, where the first part mainly documents the various features of advtrains, and the second part focuses on the internals of advtrains.
 
 \subsection*{Acknowledgments}
 
-A notable portion of the manual is influenced by various other guides and manuals for advtrains. In particular, the chapter documenting LuaATC is a reformatted and restructured copy of the LuaATC documentation. Section \ref{s:interlocking} is written with reference to orwell's interlocking guide and Blockhead's video explaining the three-station setup; the links to both sources can be found in that section.
+A notable portion of the manual is influenced by various other guides and manuals for advtrains. In particular:
+\begin{itemize}
+\item Section \ref{s:interlocking} is written with reference to orwell's interlocking guide and Blockhead's video explaining the three-station setup. The links to both sources can be found in that section.
+\item Section \ref{s:luaatc} is a reformatted and restructured version of the LuaATC documentation, written by orwell and Maverick2797.
+\item Section \ref{s:tilrwt} is a modified version of the railway time API documentation written by orwell. Part of the section is also taken from \texttt{advtrains\_line\_automation/railwaytime.lua}
+\end{itemize}
 
 \subsection*{Conventions}
 \begin{itemize}
@@ -464,10 +469,10 @@ The modes described here do not override any of the modes described above, but r
 
 Interlocking is a set of equipments employed to prevent train collisions while allowing trains to go to their destinations. This chapter will explain some basic concepts and includes a task at the end that you can try to do yourself.
 
-Please note that this chapter is also intended to be used as a reference, so some things may be explained in a way that is not easy to understand at first. If that is the case, the following links may be helpful, albeit possibly slighly outdated:
+Please note that this chapter is also intended to be used as a reference, so some things may be explained in a way that is not easy to understand at first. If that is the case, the following links may be helpful, albeit possibly slightly outdated:
 \begin{itemize}
 \item The online interlocking guide: \url{https://advtrains.de/interlocking}
-\item Blockhead's youtube video showing a simple three-station setup (see section \ref{s:ilbasicsetup}): \url{https://www.youtube.com/watch?v=ylG1vHj4zjg}
+\item Blockhead's Youtube video showing a simple three-station setup (see section \ref{s:ilbasicsetup}): \url{https://www.youtube.com/watch?v=ylG1vHj4zjg}
 \end{itemize}
 
 \subsection{TCBs}\label{s:iltcbs}
@@ -513,7 +518,7 @@ p  % second TCB
   \node at (7.25,1) {EOI};
 \end{centeredtikzpicture}
 
-Section $a$ begins at the side A of $P$ (sometimes written as $P/\mathrm{A}$) and extends to the west beyond the graph. Section $b$ is limited by $P/\mathrm{B}$ and $Q/\mathrm{A}$, effectlively spanning the line segment $\overline{PQ}$. $Q/\mathrm{B}$ is not part of any track section and is therefore known as \textit{end of interlocking} or \textit{EOI}, as the track beyond it is not part of the interlocking system.
+Section $a$ begins at the side A of $P$ (sometimes written as $P/\mathrm{A}$) and extends to the west beyond the graph. Section $b$ is limited by $P/\mathrm{B}$ and $Q/\mathrm{A}$, effectively spanning the line segment $\overline{PQ}$. $Q/\mathrm{B}$ is not part of any track section and is therefore known as \textit{end of interlocking} or \textit{EOI}, as the track beyond it is not part of the interlocking system.
 
 The graph below shows a track segment where $P$, $Q$, and $R$ form a section around the turnout $T$. Notice that a train entering from $Q$ cannot directly reach $R$ without reversing (or vice versa),  while a train entering from $P$ can reach both $Q$ and $R$.
 
@@ -680,7 +685,7 @@ The lazy method would be to set up the entire junction as a single track section
 
 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.
+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-separated.
 
 \subsubsection{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:
@@ -968,7 +973,7 @@ The following are available if \texttt{advtrains\_interlocking} is enabled.
 \end{ttdescription}
 
 \subsection{Railway time}
-All railway time functions are available in the \texttt{rwt} table.
+the railway time API described in section \ref{s:tilrwt} is available in the \texttt{rwt} table.
 \begin{ttdescription}
 \item[schedule(\argname{time},\argname{message})] Triggers a \texttt{schedule} event at \argname{time} with the message \argname{message}. Only one event can be scheduled this way.
 \item[schedule\_in(\argname{time},\argname{message})] Like \texttt{schedule}, but \argname{time} is given as the time until the event is triggered.
@@ -1060,6 +1065,41 @@ This chapter shows some example setups that you can use on your rail lines. Thes
 
 \section{The \texttt{advtrains} table}\label{s:tadvtrains}
 
+\subsection{Railway time (\texttt{advtrains.interlocking.rwt})}\label{s:tilrwt}
+Advtrains depends on Minetest's ``dtime'' for most operations, and may slow itself down when necessary (e.g. in a situation with a lot of lag) to prevent unexpected behavior. As a result, the internal time used by advtrains is not synchronized to real-life time due to lag and server restarts. Railway time was therefore introduced as a method of accurately measuring internal time, as well as to provide a scheduling system. It can, however, be set up to keep in sync with real-life time, depending on the real-life time adaptation mode (\texttt{advtrains\_lines\_rwt\_realtime}):
+\begin{ttdescription}
+\item[independent] Do not adapt to real-life time and instead keep in sync with advtrains' internal dtime.
+\item[follow\_real] Independent of real-life time, but counts up in real-life time.
+\item[adapt\_real] Use \texttt{os.time} for RWT.
+\end{ttdescription}
+
+Railway time is counted in cycles, minutes, and seconds, roughly corresponding to their real-life counterparts, with cycles roughly corresponding to hours.
+
+Railway time can be represented in three formats:
+\begin{itemize}
+\item As a table with the fields \texttt{c}, \texttt{m}, and \texttt{s}, holding the cycles, minutes, and seconds, respectively. It is an error if the \texttt{m} or \texttt{s} field is not an integer between 0 inclusive and 60 exclusive.
+\item As a string: The number of cycles, minutes, and seconds, delimited with a semicolon, such as \texttt{245;50;32}. The cycles may be absent, in which case the string is formatted as the number of minutes and seconds delimited with a semicolon, such as \texttt{37;25}. Fields do not have to be padded with zeroes, but the field should not be empty unless it is at the beginning or the end of the string; this criteria allows RWT values such as \texttt{43;3} (equivalent to \texttt{43;03}), \texttt{22;} (equivalent to \texttt{22;00}), \texttt{;10} (equivalent to \texttt{0;10}) and even \texttt{;} (equivalent to \texttt{0;00}). It is an error if the number of minutes and seconds is not an integer between 0 inclusive and 60 exclusive.
+\item As a number: the number of seconds since \texttt{0;0;0}.
+\end{itemize}
+
+The following functions are available as indices of \texttt{advtrains.interlocking.rwt}. \argname{Time}, \argname{t}, \argname{interval}, and \argname{offset} refer to a railway time object represented in one of the methods described above. \argname{Interval} and \argname{offset} represent the interval and offset of a repetition, respectively. \argname{Cycles}, \argname{minutes}, and \argname{seconds} should be the value of the \texttt{c}, \texttt{m} and \texttt{s} fields of a railway time table.
+
+\begin{ttdescription}
+\item[add(\argname{$t_1$},\argname{$t_2$})] Returns the sum of \argname{$t_1$} and \argname{$t_2$}.
+\item[copy(\argname{time})] Returns a copy of \argname{time}.
+\item[diff(\argname{$t_1$},\argname{$t_2$})] Returns the time in (RWT) seconds from \argname{$t_1$} to \argname{$t_2$}.
+\item[last\_rpt(\argname{time},\argname{interval},\argname{offset})] Returns the last occurrence of the repetition before or at \argname{time}.
+\item[new(\argname{cycles},\argname{minutes},\argname{seconds})] Returns a railway time table of \texttt{\argname{cycles};\argname{minutes};\argname{seconds}}.
+\item[next\_rpt(\argname{time},\argname{interval},\argname{offset})] Returns the next occurrence of the repetition at or after \argname{time}.
+\item[now()] Returns a table corresponding to the current railway time.
+\item[sub(\argname{$t_1$},\argname{$t_2$})] Returns the time in (RWT) seconds from \argname{$t_1$} to \argname{$t_2$}.
+\item[time\_from\_last\_rpt(\argname{time},\argname{interval},\argname{offset})] Returns the number of seconds from the last occurrence of the repetition before or at \argname{time} to \argname{time}.
+\item[time\_to\_next\_rpt(\argname{time},\argname{interval},\argname{offset})] Returns the number of seconds from \argname{time} to the next occurrence of the repetition at or after \argname{time}.
+\item[to\_table(\argname{time})] Returns a railway time table corresponding to \argname{time}.
+\item[to\_secs(\argname{time},\optargname{cycles})] Returns the railway time in number representation corresponding to \argname{time}. \argname{Cycles} is used as the number of cycles, if present.
+\item[to\_string(\argname{time}, \optargname{no cycle})] Returns a railway time string corresponding to \argname{time}. If \argname{no cycle} is true, the number of cycles is omitted from the return value.
+\end{ttdescription}
+
 \subsection{\texttt{advtrains.speed}}\label{s:tspeed}
 The \texttt{speed} library allows comparison of speed limits, which can be represented with:
 \begin{itemize}
@@ -1069,7 +1109,7 @@ The \texttt{speed} library allows comparison of speed limits, which can be repre
 
 Note that the meaning of \luanil{} here differ from the meaning used in signal aspect tables (see section \ref{s:sigasp}): \luanil{} lifts the speed limit instead of keeping it.
 
-The following functions are available in as indices of \texttt{advtrains.speed}:
+The following functions are available as indices of \texttt{advtrains.speed}:
 
 \begin{ttdescription}
 \item[lessp(\argname{a},\argname{b})] True if \argname{a} is more strict than \argname{b}.
@@ -1093,6 +1133,8 @@ For convenience, this manual refers to the functions above as \texttt{speed<}, \
 
 \section{Table structures}\label{s:structs}
 
+This section only documents table structures shared among multiple modules. API-specific table structures are documented in the corresponding sections.
+
 \subsection{Signal aspect table}\label{s:sigasp}
 Signal aspect tables may contain the following members:
 \begin{ttdescription}