From 69d8388c672d695f2031ebc13ac4a83ab220b93f Mon Sep 17 00:00:00 2001 From: "Y. Wang" Date: Wed, 10 Aug 2022 15:12:13 +0200 Subject: Reformat the rest of the developer's manual as manpages --- .../man7advtrains/node_definition.7advtrains.md | 27 ++++++++++++++++++++++ .../man/man7advtrains/signal_aspects.7advtrains.md | 25 ++++++++++++++++++++ .../manual/man/man7advtrains/speed.7advtrains.md | 1 + assets/manual/tex/main.tex | 3 --- assets/manual/tex/nodedef.tex | 27 ---------------------- assets/manual/tex/tables.tex | 27 ---------------------- 6 files changed, 53 insertions(+), 57 deletions(-) create mode 100644 assets/manual/man/man7advtrains/node_definition.7advtrains.md create mode 100644 assets/manual/man/man7advtrains/signal_aspects.7advtrains.md delete mode 100644 assets/manual/tex/nodedef.tex delete mode 100644 assets/manual/tex/tables.tex diff --git a/assets/manual/man/man7advtrains/node_definition.7advtrains.md b/assets/manual/man/man7advtrains/node_definition.7advtrains.md new file mode 100644 index 0000000..c662614 --- /dev/null +++ b/assets/manual/man/man7advtrains/node_definition.7advtrains.md @@ -0,0 +1,27 @@ +--- +title: 'NODE_DEFINITION(7ADVTRAINS) | Advtrains Developer''s Manual' +seealso: +- signal_aspects(7advtrains) +--- + +# NAME +`node_definition` - Advtrains-specific node definition entries + +# DESCRIPTION +This page describes various fields in node definition tables that are used by Advtrains. + +# NODE GROUPS +Advtrains uses node groups to identify certain properties of a node. The following node groups are currently read by Advtrains: + +* `advtrains_signal`: When set, this property defines the type of signal this node belongs to. `1` indicates that this node is a static signal, and `2` indicates that this node is a signal with a variable aspect. +* `not_blocking_trains`: When set to 1, trains can move through this node. +* `save_in_at_nodedb`: When set to 1, this node should be saved in the internal node database used by Advtrains. + +# THE `advtrains` FIELD +The `advtrains` field in the node definition may contain the following fields: + +* `get_aspect(pos, node)`: This function should return the signal aspect of the node at the given position. + +* `set_aspect(pos, node, asp)`: This function should set the signal aspect of the node to `asp` if possible. `asp` is not guranteed to be an aspect supported by the node. + +* `supported_aspects`: This table should contain a list of supported signal aspects. diff --git a/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md b/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md new file mode 100644 index 0000000..0066f7f --- /dev/null +++ b/assets/manual/man/man7advtrains/signal_aspects.7advtrains.md @@ -0,0 +1,25 @@ +--- +title: 'SIGNAL_ASPECTS(7ADVTRAINS) | Advtrains Developer''s Manual' +seealso: +- speed(7advtrains) +--- + +# NAME +`signal_aspects` - Signal aspect tables for Advtrains + +# DESCRIPTION +A signal aspect table describes the status of a signal in relation to a train following it. + +A signal aspect table may contain the following fields: + +* `main`: The main aspect of the signal +* `type`: The type of speed restriction imposed by the main aspect +* `dst`: The distant aspect of the signal +* `shunt`: A boolean indicating whether shunting is allowed +* `proceed_as_main`: A boolean indicating whether a train in shunt mode should continue with shunt mode disabled + +The `main` and `dst` fields may contain + +* A non-negative number indicating the current or next speed limit +* -1, indicating that the speed limit is or will be lifted +* `nil`, indicating that the speed limit is or will not be changed diff --git a/assets/manual/man/man7advtrains/speed.7advtrains.md b/assets/manual/man/man7advtrains/speed.7advtrains.md index 0977546..eefd764 100644 --- a/assets/manual/man/man7advtrains/speed.7advtrains.md +++ b/assets/manual/man/man7advtrains/speed.7advtrains.md @@ -3,6 +3,7 @@ title: 'SPEED(7ADVTRAINS) | Advtrains Developer''s Manual' seealso: - speed_lessp(3advtrains) - speed_set_restriction(3advtrains) +- signal_aspects(7advtrains) --- # NAME diff --git a/assets/manual/tex/main.tex b/assets/manual/tex/main.tex index 593c749..cea1cde 100644 --- a/assets/manual/tex/main.tex +++ b/assets/manual/tex/main.tex @@ -7,9 +7,6 @@ \include{signals.tex} \include{luaatc.tex} -\include{nodedef.tex} -\include{tables.tex} - \include{contributing.tex} \include{manpages.tex} diff --git a/assets/manual/tex/nodedef.tex b/assets/manual/tex/nodedef.tex deleted file mode 100644 index 04a409e..0000000 --- a/assets/manual/tex/nodedef.tex +++ /dev/null @@ -1,27 +0,0 @@ -\section{Node definition} - -\subsection{Node groups} -\advtrains{} uses node groups to identify whether a node has certain properties. The following fields are used: -\begin{apidoc}{Node definition!\texttt{groups}} -\item \apifield{advtrains\_signal} Whether the node is a signal. -\item \apifield{not\_blocking\_trains} The numeric constant 1 if the item does not block trains. -\item \apifield{save\_in\_at\_nodedb} The numeric constant 1 if the item should be save in the internal node database used by \advtrains{}. -\end{apidoc} - -The following values (as numeric constants) are accepted for items in the \texttt{advtrains\_signal} group: -\begin{apidoc}{Node definition!\texttt{groups}!\texttt{advtrains\_signal}} -\item \apienum{1} The node is a signal with a static signal aspect. -\item \apienum{2} The node is a signal, and its signal aspect can be set. -\end{apidoc} - -\subsection{The \texttt{advtrains} field} -The \texttt{advtrains} field in the node definition may contain the following fields: -\begin{apidoc}{Node definition!\texttt{advtrains}} -\item \apifield{get\_aspect(\var{pos}, \var{node})} A function that returns the signal aspect of the signal \var{node} at \var{pos}. The returned signal aspect does not need to be identical to the signal aspect passed to the previous call to \texttt{set\_aspect}. -\item \apifield{set\_aspect(\var{pos}, \var{node}, \var{asp})} A function that sets the aspect of the signal \var{node} at \var{pos} to \var{pos}. If \var{asp} is not supported by the signal, the implementation may choose to set the aspect to something different. -\item \apifield{supported\_aspects} A table of supported signal aspects. -\end{apidoc} - -%%% Local Variables: -%%% TeX-master: "a4manual" -%%% End: \ No newline at end of file diff --git a/assets/manual/tex/tables.tex b/assets/manual/tex/tables.tex deleted file mode 100644 index 91422b6..0000000 --- a/assets/manual/tex/tables.tex +++ /dev/null @@ -1,27 +0,0 @@ -\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{apidoc}{Signal aspect table} -\item \apifield{main} The aspect of the main signal. -\item \apifield{type} The type of signal. Please refer to section \ref{s:srtypes} for more information. -\item \apifield{dst} The aspect of the next main signal. -\item \apifield{shunt} Whether shunting is allowed. -\item \apifield{proceed\_as\_main} When shunting is not allowed, whether to let the train continue with shunt mode disabled. -\end{apidoc} - -The \texttt{main} and \texttt{dst} fields may contain one of the following: -\begin{itemize} -\item $n \geq 0$, which changes the speed limit of the corresponding type to $n$, or (for distant signals) indicates the speed limit for the upcoming main signal. -\item $-1$, which lifts the speed limit of the corresponding type, or (for distant signals) indicates that the speed limit is lifted at the upcoming main signal. -\item \luanil, which keeps the speed limit unchanged. -\end{itemize} - -\subsection{Train speed restriction table} -The speed restriction table for trains includes the speed limits for a train, where the key is the type of speed limit and the value is the speed limit itself. - -%%% Local Variables: -%%% TeX-master: "a4manual" -%%% End: \ No newline at end of file -- cgit v1.2.3